Madong-Saas MCP Server配置指南:把管理后台API暴露给AI助手的完整实践
Madong-Saas MCP Server配置指南:把管理后台API暴露给AI助手的完整实践
Madong-Saas 是基于 PHP Webman 的多租户 SaaS 管理后台后端,内置一套完整的 MCP(Model Context Protocol)Server。开启后,它把后台的管理能力(查角色、查菜单、看日志、清缓存、读配置等)封装成标准 MCP 工具,让 Trae、Cursor 等 AI 助手直接"调用管理后台 API",实现用自然语言查询后台状态、排查问题。本文带你完成 MCP 端点配置、双通道鉴权、租户绑定与本地验证的完整流程。
1. 为什么需要 MCP Server?
传统方式下,AI 助手无法直接访问你的后台:它只能"猜"接口文档,或者你手动复制粘贴返回数据。
Madong-Saas 的内置 MCP Server 解决了这个问题:
- 工具化:每个能力(如
role_list查角色、log_tail看日志)都以 MCP 工具形式注册,AI 按inputSchema自动传参; - 权限对齐:工具权限码直接复用后台 RBAC 菜单权限码,AI 能看到的工具与登录身份严格一致;
- 租户感知:SaaS 多租户场景下自动注入租户上下文,数据隔离与 HTTP API 一致。
相关源码:config/mcp.php 应用层配置、core/communication/mcp/ 核心实现。
2. 两条接入通道:HTTP 端点与 STDIO
Madong-Saas 提供两种接入方式,可按场景选择:
| 通道 | 入口 | 适用场景 |
|---|---|---|
| HTTP(Streamable HTTP) | POST/GET/DELETE /mcp |
Trae 等远程 MCP 客户端、生产/联调 |
| STDIO | php webman madong-mcp:serve |
MCP Inspector 等本地调试工具 |
HTTP 端点的路由注册见 core/communication/mcp/route.php,由 config/route.php 在关闭默认路由前引入,固定路径为 /mcp。
3. 一键配置步骤:编辑 config/mcp.php
所有开关集中在 config/mcp.php,webman 启动时自动加载为 config('mcp.*')。核心参数如下:
| 参数 | 默认值 | 说明 |
|---|---|---|
enable |
true |
总开关,false 时端点返回 404,不暴露存在性 |
endpoint |
/mcp |
端点路径(文档用途,实际路由由 route.php 注册) |
session.store |
file |
会话存储,可选 redis(需 webman/redis) |
auth.api_key |
true |
开启 X-Mcp-Api-Key 通道 |
auth.jwt |
true |
开启 Authorization: Bearer JWT 通道 |
tools.db_schema / tools.log_tail |
true |
内置工具开关 |
生产环境如果不用 MCP,把 enable 置为 false 即可,端点直接返回 404,避免暴露接口存在性。
最快配置方法:为编辑器配一个开发 API Key
默认已登记一个本机开发身份(config/mcp.php 中 api_keys):
'api_keys' => [
'dev-editor-key-local' => [
'id' => 0,
'name' => 'dev-editor',
'permissions' => ['*'], // 超级权限,仅限本地联调
'tenant_id' => null, // 平台级,不绑定租户
],
],
客户端请求时携带请求头 X-Mcp-Api-Key: dev-editor-key-local 即可,无需登录。上线前请删除或收紧此 key。
4. 双通道鉴权与租户绑定
鉴权逻辑在 core/communication/mcp/security/Authenticator.php,顺序为:
X-Mcp-Api-Key优先:配置式 key,适合 CI、脚本与编辑器联调;Authorization: Bearer <JWT>其次:由身份解析器 app/mcp/MadongIdentityResolver.php 把 JWT 解析为 MCP 用户,并复用后台菜单权限码计算可见工具——超管拿到*,普通管理员按其角色绑定的菜单权限过滤;- 两者都没有则匿名:只能看到
permission: null的工具(如ping、system_info)。
任一通道提供了凭证但解析失败会直接返回 401,不会静默降级为匿名,避免越权隐患。
SaaS 租户上下文优先级(见 core/communication/mcp/endpoint/McpEndpointController.php):
- API Key 配置中的
tenant_id→ 请求头X-Tenant-Id→ 不注入(平台级); - JWT 通道则优先取 token 中登录时写入的
current_tenant.id,回退到管理员所属租户。
5. 内置工具清单一览
工具通过 #<a href="https://link.gitcode.com/i/508331beec98645ed5f5863919b02527" target="_blank">McpTool] 属性声明([core/communication/mcp/attribute/McpTool.php),启动时由发现器自动扫描三个目录:app/mcp、plugin/*/app/mcp 与 core/communication/mcp/tool/。
| 分类 | 工具 | 用途 |
|---|---|---|
| 运维 | ping / health_check / system_info / server_monitor |
连通性验证、健康检查、服务器监控 |
| 运维 | cache_status / cache_clear / queue_status |
缓存与队列状态 |
| 开发 | db_schema / db_query / code_search / log_tail / route_list |
查表结构、检索代码、追日志、列路由 |
| 系统 | current_user / config_read / admin_account_query / scheduler_status |
当前身份、读配置、查管理员 |
| 目录 | menu_catalog / dict_catalog / plugin_list / tool_catalog |
菜单、字典、插件、工具自描述 |
| CI | job_trigger |
触发任务 |
| 应用桥接 | role_list / admin_user_list |
见 app/mcp/RoleListTool.php,示范工具直接调用 app 层 Service |
例如 role_list 声明了权限码 system:role:list,AI 助手只有以具备该权限的身份接入时才会看到它。
6. 本地验证:三条 CLI 命令快速自检
CLI 身份视为本机超管,最适合做部署后自检(命令实现见 app/command/mcp/):
# 1. 查看已发现的全部工具(Name/Permission/Handler/Source)
php webman madong-mcp:list
# 2. 直接调用工具,--tenant 可指定租户(多租户模式)
php webman madong-mcp:call system_info '{"section":"overview"}'
php webman madong-mcp:call role_list '{"keyword":"admin"}' --tenant 1
# 3. 以 STDIO 方式启动,供 MCP Inspector 等本地客户端调试
php webman madong-mcp:serve
提示:STDIO 通道在 Windows 控制台支持受限,建议 Linux/macOS,或改用 HTTP 端点。
HTTP 端点验证:启动服务后,用任意 MCP 客户端(或 MCP Inspector)连接 http://127.0.0.1:8500/mcp,调用匿名工具 ping / system_info 返回正常即说明链路打通。
7. 在 Trae 等 MCP 客户端中接入
以 Trae 编辑器为例:
- 在 MCP 客户端配置中新增 HTTP 类型服务器,地址填
http://127.0.0.1:8500/mcp; - 请求头添加
X-Mcp-Api-Key(值为 config/mcp.php 中登记的 key),需要租户上下文时再补X-Tenant-Id; - 保存后客户端完成
initialize握手并拉取tools/list,即可对 AI 说"查一下后台里编码包含 admin 的角色",助手会自动调用role_list并解读返回 JSON。
接入后的典型玩法:让 AI 用 log_tail 追错误日志、db_schema 看表结构、queue_status 看队列积压,把"登录后台点菜单"变成一句话。
8. 常见问题排查
| 现象 | 原因与处理 |
|---|---|
/mcp 返回 404 |
enable 为 false,或路由未生效;确认 config/route.php 中 mcp/route.php 在 Route::disableDefaultRoute() 之前引入 |
| 返回 401 | API Key 写错、或该通道在 auth 中被关闭;凭证无效不会降级为匿名 |
| 工具列表为空 | 身份权限不足(RBAC 过滤所致),超管或 * 权限身份应可见全部 |
| 数据跨租户串了 | 检查 X-Tenant-Id 或 API Key 的 tenant_id 配置 |
| Windows 下 serve 卡住 | STDIO 控制台限制,改用 Linux/macOS 或 HTTP 端点 |
9. 安全最佳实践清单
- 🔐 生产环境不启用则设
enable: false,端点 404 不暴露存在性; - 🔐 删除默认开发 key,为 CI/脚本单独签发最小权限的 API Key;
- 🔐 敏感工具保持权限码约束,避免配置
permissions: ['*']的 key 出现在公网配置; - 🔐 需要跨进程共享 MCP 会话时,将
session.store切换为redis; - 🔐 新增插件工具放到
plugin/*/app/mcp即可被自动发现,无需改核心代码。
总结
Madong-Saas 的 MCP Server 通过"一份配置 + 双通道鉴权 + 自动工具发现"把多租户 SaaS 管理后台的能力开放给了 AI 助手:配置上只需维护 config/mcp.php,验证上只需 madong-mcp:list / madong-mcp:call 两条命令,接入上在 Trae 等客户端填好 /mcp 地址与鉴权头即可。配合 RBAC 权限码与租户上下文隔离,你可以放心地让 AI 参与到日常运维与联调中——这大概是 PHP 管理后台"给 AI 装上手"最顺的一条路。