9.4 KiB
MCP 配置、持久目录与按需调用
设置页面
MCP 配置分两步,使用现有 SettingDrawer,步骤导航沿用沙箱的圆形编号与连接线,分组使用标题和细分隔线。
- 连接配置:名称、启用状态、传输协议、URL、请求头、认证及超时。保存后进入第二步;OAuth 授权仍按用户独立进行。
- 工具与用途说明:编辑用途摘要和使用说明。进入本步时若还没有目录,会自动连接并拉取 Tools;已保存的目录直接展示,只有点刷新才会再次访问 MCP Server。连接已变更的旧目录不会自动覆盖,需手动刷新。工具启用和审批开关即时保存。
编辑时无需为展示 Tools 再次连接上游。首次使用旧服务需要同步一次:此前数据库只有工具的启用/审批设置,没有完整工具目录可以迁移。
存储及字段来源
迁移 000092_mcp_metadata 新增服务使用说明及持久目录表。
| 数据 | 存储位置 | 来源与更新方式 |
|---|---|---|
| 服务名称、用途摘要 | mcp_services.name / description |
人工配置 |
| 使用说明 | mcp_services.usage_instructions |
人工配置;刷新不会覆盖 |
| 原始服务说明 | mcp_metadata.instructions |
initialize.result.instructions |
| 服务端名称、版本及简介 | mcp_metadata.server_name / server_version / server_description |
initialize.result.serverInfo |
| 工具名称、完整描述、完整 schema | mcp_metadata.tools JSONB |
完整分页读取 tools/list 后原子保存 |
| 同步时间、连接指纹 | mcp_metadata.synced_at / config_fingerprint |
后端生成;指纹不返回前端 |
| 工具启用、审批策略 | 原有 mcp_tool_approvals |
单独保存;同步不会覆盖 |
目录按 (tenant_id, service_id, principal) 隔离。非 OAuth 服务在同一租户内共享一份快照;OAuth 服务使用有效授权主体的 StorageID,同一服务可以有多份用户目录,不回退读取其他用户的快照。主表的服务列表查询不会携带完整 Tools JSON。
连接指纹覆盖传输方式、URL、请求头、认证配置、stdio 配置和环境变量。密钥只参与指纹计算,不写入目录或模型上下文。修改用途文字不使目录失效;修改连接或认证配置后,旧目录仍可在管理页面查看,但标为 stale,不参与运行时工具加载。
刷新使用独立连接,30 秒超时;获取全部工具成功后才写库。失败保留原有快照,页面展示本次错误;不把不完整目录发布成成功结果。成功返回空列表则移除旧工具。刷新前后核对连接指纹,较早开始的慢刷新不能覆盖较新快照。现有客户端限制为 100 页、2,000 个工具及单个 schema 256 KiB;完整快照另有 8 MiB 上限,超限明确失败。
API
GET /api/v1/mcp-services/:id/metadata:只读库,未同步返回data:null,旧连接的快照返回stale:true;Viewer 及以上权限。POST /api/v1/mcp-services/:id/metadata/refresh:显式连接并同步。静态认证写入租户共享快照,需要 Admin(或具备 MCP 管理能力的 API key);OAuth 写入当前用户快照,Viewer 及以上可调用,以便对话内授权后落库。刷新失败对外返回笼统错误,不带回上游地址。- 服务原有 POST / PUT 接收
description和usage_instructions。凭证继续走独立子资源,编辑说明不会覆盖密钥。 - 旧
/test、/tools和/resourcesAPI 保留原有行为;新分步页面不通过它们读取缓存。
模型暴露链路
入库不等于全量发送给模型。 默认使用普通函数调用实现应用层按需加载,不依赖 Responses 或 Anthropic 的原生 tool-search 协议。
registerMCPTools筛选当前租户及 Agent 授权范围内的启用服务,安装受权限约束的目录。生产路径注入只读快照 loader;目录缺失时(升级后尚未同步)可在已授权连接上 livetools/list并写入当前主体的快照。OAuth 服务在预加载阶段不会 live 连接(避免弹出授权窗);对话内工具执行上下文中才允许 live-fill。连接已变更的 stale 快照不会在预加载时 live-fill。模型调用list_tools且refresh=true时会重新拉取上游并尝试落库;设置页刷新对静态认证需要 Admin,OAuth 仍可由授权用户同步。PrepareMCPTools预读数据库快照,不连接上游。读取最多 8 路并发,初始等待窗口 1 秒,整体受请求取消及 30 秒超时约束。未就绪服务仍展示在来源目录中。- 首轮模型只看到两个入口
discover_mcp_tools/call_mcp_tool,以及服务级名称、用途说明和状态。来源摘要有 16 KiB 总预算:能放下时模型应直接list_tools/describe,不要先list_servers;超出时才提示通过list_servers分页枚举。每个工具的完整描述和 schema 不在首轮 tools 中。 - 模型按服务
list_tools/search,再describe一个具体工具。describe返回完整描述、schema、原始服务 instructions、人工使用说明、function_name和tool_ref,并记录本次 engine 已读取的定义版本。 - 下一次模型请求前,
RefreshMCPTools把已 describe、或本会话历史里已经用过的工具发布为普通函数。新 engine 会从对话历史恢复mcp_*函数名和call_mcp_tool的tool_ref,避免多轮必须重新 describe。也可继续用call_mcp_tool兼容代理调用。目录操作和后台读取线程不会在并行执行期间修改 registry。 - 实际执行目标 MCP 工具时才建立所需连接。权限、审批、OAuth 等待、参数校验和结果处理继续走原有执行链。
没有 mention 也能看到所有获准服务;mention 只设置优先使用项,不缩小或扩大 Agent 配置的 all / selected / none 授权范围。
PrepareMCPToolsDirect 保留全量函数暴露的兼容路径,生产默认不使用。OpenAI 兼容和 Anthropic Messages 都支持上述普通函数的按需加载;Anthropic 适配器支持 tools、tool_use、并行 tool_result 和流式参数拼接。截断的参数流不会作为完整调用执行。
与 Codex 的对应和边界
对照 openai/codex@2cbbf0c9b542a36a1c3284b5e804917635b6f666:
codex-rs/codex-mcp/src/rmcp_client.rs:初始化后读取工具目录,普通 MCP 的 namespace description 来自initialize.instructions;Apps 使用 Connector 元数据。codex-rs/core/src/mcp_tool_exposure.rs:工具搜索启用时 Deferred,否则 Direct。codex-rs/core/src/tools/handlers/tool_search_spec.rs:首轮按来源去重展示名称及可选说明;world state 已声明来源时省略重复列表。codex-rs/core/src/tools/handlers/mcp.rs/tool_search.rs:逐工具元数据构建后台 BM25 索引,命中后加载完整工具定义。
本项目采用相同的“来源可感知、具体定义按需加载”原则,但当前检索是单服务名称/描述子串匹配,加分页枚举和精确 describe,不是 Codex 的原生 BM25 tool_search 协议。持久化管理目录也是本项目的服务端设计,不宣称照搬 Codex 的存储方式。
目录完整性、权限和历史
列表默认 20 项、最大 50 项。遵循 next_cursor 直到 has_more=false;列表摘要不提供可调用引用,必须 describe 完整定义。搜索为空时可以不带 query 枚举,工具可达性不依赖搜索排名。
当前 engine 的目录绑定租户、调用主体及有效 OAuth 主体。读取和执行重新检查服务配置、工具策略;缓存不缓存权限决策。新增到 Agent 授权范围外的服务不会自动进入当前目录。运行时 list_tools(refresh:true) 重新读取持久快照,上游同步由管理页面显式发起。
具体函数使用原始服务 ID 和工具名生成稳定哈希后缀,避免 Unicode、大小写、标点、超长名称清洗后冲突。调用引用绑定服务、原始工具名和 schema,旧 schema 被替换后无法沿用旧引用。新 engine 会根据会话历史恢复已用过的函数,无需再 describe 一次。
完整 JSON Schema 校验覆盖组合约束、额外属性、嵌套结构和本地引用。验证器不访问外部 URL 或文件。参数转换和审批后的修改也经过校验。定义结果超过预算会明确失败或整体替换为说明,不使用半截 JSON。
ToolCall.Name / Args / ID / ProviderMetadata 保留模型原始调用;ToolCall.Target 保存实际服务、工具名及内层参数,供界面和日志展示。工具图片、外部标识及内容项沿用现有处理,不改写成知识库身份。
服务端元数据是外部使用文档,不具有覆盖用户请求或权限策略的权威。函数说明带 external 前缀;目录结果的 notice 和执行结果的 untrusted 标记保留。人工说明与服务端原文分别保存、展示。
验证
覆盖完整 Tools/schema 入库及离线读取、刷新失败保留快照、较旧刷新不覆盖新快照、成功空目录、连接变更失效、人工说明保留、租户及 OAuth 主体隔离。1,000 个工具时,默认首轮仍只暴露来源和入口,describe 后只加载目标工具。
HTTP 集成测试覆盖 OpenAI / Anthropic 两种适配器的 Direct 和按需加载流程,验证未 mention 的模型请求、缓存发现阶段无上游请求、实际 MCP 执行和调用历史回传。既有权限、分页、schema、审批及图片回归测试继续保留。