Madong-Saas MCP Server配置指南:把管理后台API暴露给AI助手的完整实践

原创2026-10-29 15:33:461,053 阅读

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,顺序为:

  1. X-Mcp-Api-Key 优先:配置式 key,适合 CI、脚本与编辑器联调;
  2. Authorization: Bearer <JWT> 其次:由身份解析器 app/mcp/MadongIdentityResolver.php 把 JWT 解析为 MCP 用户,并复用后台菜单权限码计算可见工具——超管拿到 *,普通管理员按其角色绑定的菜单权限过滤;
  3. 两者都没有则匿名:只能看到 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 编辑器为例:

  1. 在 MCP 客户端配置中新增 HTTP 类型服务器,地址填 http://127.0.0.1:8500/mcp;
  2. 请求头添加 X-Mcp-Api-Key(值为 config/mcp.php 中登记的 key),需要租户上下文时再补 X-Tenant-Id;
  3. 保存后客户端完成 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 装上手"最顺的一条路。

登录后查看全文
madong-admin-saas