08 内部平台数据接入：MCP Gateway

状态：暂缓实现。 当前阶段只对上层提供 API。本文保留设计，供以后接入时使用；其中 MCP Gateway 本身会在 M2 先上线，承载内置工具 web_fetch 和 kb_*（§5）。

1. 目标

让 Agent 能查询（必要时操作）你的内部平台数据，同时做到：

平台凭证只保存在服务端，Agent 拿不到
Agent 不直接访问局域网（见 06 §5）
Claude 和 Codex 用同一套工具定义
读操作自动放行，写操作必须人工审批
每次调用都有审计记录

2. 方案：服务内置的 MCP Gateway

claude CLI ──┐  MCP (Streamable HTTP)         ┌─► 平台 A API (LAN)
             ├──► /mcp (AgentServer 进程内) ───┼─► 平台 B API (LAN)
codex  ──────┘  Authorization: Bearer <run-token>  └─► 本地资料索引 / web_fetch

两个引擎都支持 HTTP 类型的 MCP Server，所以只做一个 Gateway，不在引擎侧分别实现。
Run Token：每个 Run 签发一个短期令牌（绑定 sessionId、userId、profileId，Run 结束即失效）。Gateway 据此判断当前 Run 能用哪些工具、以谁的身份调用。
不选 Claude SDK 的进程内 MCP：Codex 用不了，会导致两套实现。

3. 连接器（Connector）

一个内部平台对应一个连接器，以 TS 模块的形式放在 apps/server/src/connectors/<name>/：

export default defineConnector({
  id: 'finance',
  name: '家庭账本',
  config: z.object({ baseUrl: z.string().url(), token: z.string() }), // 后台填写，token 加密存储
  tools: [
    defineTool({
      name: 'query_transactions',
      description: '按日期范围、分类查询收支流水，返回 JSON 行',
      input: z.object({ from: z.string(), to: z.string(), category: z.string().optional() }),
      access: 'read',                       // read: 自动放行；write: 必须审批
      async run(input, { config, user, fetch }) { /* 调平台 API */ },
    }),
    defineTool({
      name: 'create_budget',
      access: 'write',
      approvalTitle: i => `创建预算：${i.name} ¥${i.amount}`,
      /* ... */
    }),
  ],
})

工具命名规则：<connectorId>__<toolName>；在引擎侧显示为 mcp__gateway__finance__query_transactions。

3.1 结果处理

大结果（超过 200 行或 100KB）不直接塞进上下文：写成 workspace/.agent/data/<toolcall>.json|csv，返回摘要、行数和文件路径，再由 Agent 用 pandas 分析。这一点对数据分析场景很重要。
统一错误格式，平台不可用时给出清楚的报错。

3.2 使用者身份

当前不区分使用者；连接器以服务端配置的身份访问平台。以后如需区分，可以在 Run Token 中携带调用方（API Key）标识。

4. 审批在 Gateway 内完成

access: 'write' 的工具被调用时，Gateway 自己调用 Interaction Service 发起 interaction.required，挂起 MCP 请求直到人工回复，再执行或返回拒绝。

这样不依赖引擎侧的审批机制，两个引擎行为一致。引擎侧（Claude 的 canUseTool）会把 mcp__gateway__* 加入自动放行，避免重复审批。

需要注意 MCP 请求的超时：引擎侧的 MCP 工具调用超时要调大（至少不低于交互超时），具体配置项在实现时核对。

5. 内置工具（Gateway 自带）

工具	说明	期次
`web_fetch`	抓取 URL → 清洗为 Markdown；拦截私网地址；遵守域名黑名单	M2
`kb_search`	本地资料库全文检索（见 07 §4.1）	M3
`kb_list_roots`	列出当前 Profile 可用的资料库及说明	M2
`ask_user`	给 Codex 用的结构化提问（对齐 Claude 的 AskUserQuestion）	M2

6. 后台管理

连接器列表：启用状态、健康检查（每个连接器可以实现 ping()）、最近调用情况
配置表单：由连接器的 config schema 自动生成，敏感字段只写不读
工具列表：可以单独禁用某个工具，或把 read 工具改为需要审批
Profile 中勾选启用的连接器和工具
调用日志：参数、耗时、结果摘要、审批记录

08-platform-connectors.md 4.2 KB Verlauf Originalformat