Skip to main content

MCP（/mcp）

平台通过 MCP Server 在 /mcp 端点以 Streamable HTTP 方式暴露内置 AI 工具，外部 AI 客户端接入后，可让 AI 助手直接查询与配置平台的元数据和业务数据。

概述​

MCP（Model Context Protocol，MCP 接入 / MCP Server / AI 工具）是一种标准的 AI 工具调用协议。Chameleon 将平台内的 AI 工具（元数据查询与编辑、业务数据查询、数据源检索、平台知识库检索等）通过 MCP 协议开放给外部 AI 客户端，如 VS Code、Trae、Claude Code、MCP Inspector 等。

核心特性：

  • 标准协议：遵循 MCP 规范的 Streamable HTTP 传输，任何支持 MCP 的客户端均可接入，无需定制开发。
  • 自动授权：完整实现 OAuth 2.1 授权链路（发现、动态注册、PKCE、令牌交换），客户端发起连接后自动完成浏览器授权，无需手动填写令牌；也支持使用个人令牌免授权接入。
  • 按角色过滤工具：每次请求都根据当前登录用户的平台角色（PlatformRoleEnum）过滤可见工具，普通用户、租户管理员、平台开发者看到的工具集不同。
  • 租户与用户隔离：每次工具调用都携带当前用户的上下文，数据权限与平台内一致。

边界说明：本文档面向外部 AI 客户端接入平台能力的场景；平台内 AI 助手（Arthur 等）不经过 /mcp 端点，而是直接使用同一套工具实现。

快速接入​

端点地址​

环境URL说明
生产环境https://<域名>/mcp网关统一转发到 Pro API
本地直连http://localhost:5001/mcp本地调试 Pro API 时使用

认证方式​

/mcp 端点要求登录态，支持两种认证方式：

方式一：OAuth 2.1 自动授权（推荐，免配置）

客户端只需配置端点 URL，首次连接时自动完成全部授权流程：

  1. 客户端请求 /mcp，收到 401 质询，响应头 WWW-Authenticate 指向授权服务器元数据地址。
  2. 客户端自动获取授权服务器元数据并完成动态注册（注册端点为只读，返回固定的公开客户端 chameleon-mcp）。
  3. 浏览器打开平台授权页，使用平台账号登录并确认授权（已登录时静默通过）。
  4. 客户端自动用授权码换取令牌并完成连接，令牌过期后自动刷新。

要求客户端支持 MCP 规范的 OAuth 授权流程（VS Code、Claude Code、MCP Inspector 等均支持）。

方式二：个人令牌（免授权）

在平台管理端生成个人令牌（key- 前缀），在客户端配置中通过 Authorization 请求头携带：

{
  "servers": {
    "chameleon": {
      "type": "http",
      "url": "https://<域名>/mcp",
      "headers": {
        "Authorization": "Bearer key-xxxxxxxx"
      }
    }
  }
}

个人令牌支持配置 IP 白名单，适合脚本调用或不想走浏览器授权的场景。

客户端配置示例​

VS Code（用户级 ~/.vscode/mcp.json 或项目级 .vscode/mcp.json）：

{
  "servers": {
    "chameleon": {
      "type": "http",
      "url": "https://<域名>/mcp"
    }
  }
}

也可通过命令面板 MCP: Add Server...，类型选择 HTTP，填入端点 URL。

Trae / Claude Code 等其他客户端（通用 mcpServers 格式）：

{
  "mcpServers": {
    "chameleon": {
      "type": "http",
      "url": "https://<域名>/mcp"
    }
  }
}
tip

接入后建议先让 AI 执行一次「列出应用」类工具（如 list_meta_apps）验证连通性。若客户端不支持 OAuth 授权流程且不弹授权提示，可改用个人令牌方式。

工具列表​

工具按能力域分组。所有工具都要求登录；「最低角色」为 Developer 的工具仅平台开发者可见，其余工具所有登录用户可见。

工具名说明最低角色
ask_user向用户展示一组可点击的选项并等待选择，用于需要决策的场景User
refresh_content刷新聊天旁展示的内容区，让用户看到刚应用的修改User

应用与元对象查询

工具名说明最低角色
list_meta_apps按名称/编码模糊搜索应用，或不带关键字列出全部应用User
get_meta_app按应用 Id 获取单个应用定义User
list_meta_objects按关键字搜索业务元对象，返回 Id、编码与名称User
get_meta_object按元对象 Id 获取基础定义User
list_meta_fields列出元对象的字段，含编码、名称与字段类型User
list_meta_objects_by_app列出应用下全部业务元对象User

元对象编辑

工具名说明最低角色
create_meta_object在应用内创建业务元对象Developer
update_meta_object编辑元对象的基本属性（显示名称、描述）Developer
update_meta_object_settings编辑元对象设置（数据源、审计日志、查重规则等）Developer

字段编辑

工具名说明最低角色
create_meta_field在元对象上创建字段Developer
update_meta_field编辑字段的属性与设置Developer
save_meta_field_validations替换字段的校验规则Developer
list_field_data_sources列出可绑定到字段的数据源User

视图列表查询与编辑

工具名说明最低角色
list_meta_views按关键字搜索视图列表User
get_meta_view获取视图列表定义（含所属对象与列配置）User
create_meta_view在业务元对象上创建视图列表Developer
initialize_meta_view创建视图列表并按字段预填列，一步生成可用的列表Developer
update_meta_view编辑视图列表基本属性Developer
save_meta_view_settings保存视图列表页面设置（表标题、分页大小等）Developer
save_meta_view_columns保存视图列表的有序列配置Developer
save_meta_view_buttons保存工具栏按钮Developer
save_meta_view_batch_buttons保存批量操作按钮Developer
save_meta_view_row_buttons保存行按钮Developer

页面与表单查询

工具名说明最低角色
list_meta_pages按关键字搜索页面User
get_meta_page按页面 Id 获取页面定义User
get_meta_page_layout获取页面的布局组件树User
list_meta_forms按关键字搜索表单User
get_meta_form按表单 Id 获取表单定义User
get_meta_form_layout获取表单的布局组件树User

表单编辑

工具名说明最低角色
create_meta_form在业务元对象上创建空表单Developer
initialize_meta_form创建表单并按业务字段预填布局，一步生成可用的表单Developer
update_meta_form编辑表单基本属性（名称、标题、描述）Developer
save_meta_form_layout替换表单布局（组件树，决定表单包含哪些字段及排布）Developer
save_meta_form_settings保存表单设置（按钮文案、动作、布局方向、间距等）Developer

业务数据与数据源

工具名说明最低角色
query_list分页查询元对象的业务记录，支持过滤与排序User
count_records按条件统计元对象的业务记录数User
get_record按 data id 获取单条业务记录User
search_data_source按标签或值搜索数据源选项（人名/组织名 → 存储值的转换）User
list_field_data_source列出字段所绑定数据源的选项User

平台知识与代码检索

工具名说明最低角色
search_platform_knowledge检索平台知识库（平台文档、API 契约、错误码等）User
get_knowledge_chunk按 Id 获取知识块的完整内容User
search_code在平台源码仓库中按正则或文本检索Developer
list_code_files列出源码仓库的文件Developer
read_code_file读取源码文件或其行区间Developer
角色层级

PlatformRoleEnum 取值向下兼容：User = 0（所有登录用户）、Admin = 1（租户管理员，满足 User 级别全部能力）、Developer = 2（平台开发者，满足全部级别）。即标记为 Developer 的工具对普通用户与租户管理员不可见。

下一步​

属性明细​

以下内容面向技术实现与 AI 检索。

服务端执行逻辑​

/mcp 端点部署在 Pro API（Chameleon.Pro.Api），基于 ModelContextProtocol.AspNetCore（MCP C# SDK）实现，传输模式为无状态 Streamable HTTP：每个请求独立处理、独立鉴权，不依赖会话亲和。

每次 MCP 请求的处理步骤：

  1. 鉴权：JWT（OAuth 换取）或个人令牌（ChameleonSystemTokenVerificationMiddleware 将 key- 前缀令牌校验并换取短时 JWT），通过 PolicyConst.User 授权策略。
  2. 构建工具目录：ConfigureSessionOptions 按请求重建工具集合——IAiToolsProvider.Build(Enum.GetValues<AiToolKind>()) 从工具描述表生成工具，AiAccessGuard.Satisfies(descriptor.MinSystemRole) 过滤掉超出当前用户角色的工具。
  3. 工具执行：每个工具实例从请求作用域解析，携带当前用户的 ChameleonContext（租户、用户、权限），执行结果与平台内权限一致。

认证端点明细​

端点认证说明
GET /.well-known/oauth-protected-resource匿名RFC 9728 受保护资源元数据，由 401 质询头引导
GET /.well-known/oauth-authorization-server匿名RFC 8414 授权服务器元数据，声明各端点地址
POST /connect/register匿名只读动态注册：不写数据库，返回固定公开客户端 chameleon-mcp
`GETPOST /connect/oauth2/authorize`登录态
POST /connect/token匿名form-urlencoded 令牌端点，支持 authorization_code（PKCE S256）与 refresh_token

要点：

  • MCP 接入使用固定的公开客户端 chameleon-mcp（OAuth2Const.McpClientId），强制 PKCE（S256），不需要客户端密钥；数据库中的客户端记录在首次授权时按租户惰性创建（OAuth2App.EnsureMcpClientAsync，依赖 ClientId 唯一索引保证并发幂等）。
  • 授权码绑定 code_challenge，换取令牌时校验 code_verifier；redirect_uri 支持回环地址（http://localhost:<任意端口>、http://127.0.0.1:<任意端口>，RFC 8252）与已配置的白名单地址。
  • 网关路由：location = /mcp → Pro API；/.well-known/、/connect/token、/connect/register → 核心 API；授权页走前端 SPA 路由。

相关实现​

模块位置
MCP 端点注册与 401 质询中间件chameleon-internal/chameleon-pro/Chameleon.Pro.Api/DependencyInjection/McpRegister.cs
工具描述表与角色过滤chameleon-internal/chameleon-pro/Chameleon.Pro.Application/AI/Providers/AiToolsProvider.cs
工具标识枚举（AiToolKind）chameleon-internal/chameleon-pro/Chameleon.Pro.Application/AI/Tools/AiToolKind.cs
角色守卫（AiAccessGuard）chameleon-internal AI 模块 AI/Core/AiAccessGuard.cs
OAuth 授权与令牌逻辑chameleon/server/Chameleon.Application/OAuth2App.cs
OAuth 常量与端点chameleon/server/Chameleon.Infrastructure/Consts/OAuth2Const.cs、chameleon/server/Chameleon.Api/Controllers/Authorization/
网关路由chameleon-internal/gateway/nginx/conf/chameleon.conf