Files
ssw-platform/docs/mcp.md
T
admin 217dadf008 feat(mcp): 落地 MCP 工具层 —— 4 元工具 + 分层加载 + 进程内适配器
- 新增 crates/sspf-mcp:registry / jsonrpc / server / 4 个元工具(context·discover·describe·call)
- 内核新增 mcp_adapter.rs(NativeAdapter,直接调 AppState)与 `--mcp` 子命令
- 工具定义自带五段自提示(含 pitfalls/examples),示例必须能被测试跑通
- 新增 scripts/mcp-smoke.sh(13 条)与 docs/mcp.md(接入说明)
- 影响:协议层只暴露 4 个工具(常驻约 1.8K token);业务失败返回结构化 error 而非协议错
- 踩坑记录:内嵌 PG 会抢 fd 0/1,必须在开库前 detach 标准流;tokio 的 stdin 在管道上 ENXIO
2026-10-31 10:29:14 +08:00

5.8 KiB
Raw Blame History

MCP 工具层 —— 让 AI 直接驱动 SSPF

一个进程、一条 stdio、4 个工具,AI 就能建表 / 建菜单 / 查数据。 架构与设计动机见 PLAN.md §6;本文只讲怎么接、怎么用、踩过什么坑。


1. 30 秒接入

# 确认二进制在
cargo build --release

# 手动跑一次(可选)—— 应该立刻回一行 initialize 的 JSON
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  | ./target/release/ssw-platform --mcp 2>/dev/null

Claude Code / 通用 MCP 客户端

在 MCP 配置里加一条(~/.claude.json 的 mcpServers,或客户端对应的配置文件):

{
  "mcpServers": {
    "sspf": {
      "command": "/绝对路径/ssw-platform",
      "args": ["--mcp"],
      "env": {
        "PGLITE_DIR": "/绝对路径/数据目录/lite.pg"
      }
    }
  }
}

🔴 PGLITE_DIR 必须写绝对路径:MCP 客户端启动子进程时 cwd 不确定, 相对路径会把库建到奇怪的地方(默认值依赖「从可执行文件向上找锚点」,MCP 下也不稳)。

🔴 一个数据目录只能被一个进程打开(pglite 独占)。 若 HTTP 后端已经在跑,MCP 要么复用同一个进程(暂不支持,见 §5), 要么用另一个数据目录(推荐:开发期用独立库,避免和前端联调互相干扰)。


2. 只有 4 个工具,但能干所有事

tools/list 永远只返回这四个:

工具 干什么 典型参数
sspf_context 我是谁、连的哪个后端、多少表 {}
sspf_discover 我想干 X → 有哪些工具 {"query":"表单 创建"}
sspf_describe 这个工具怎么用、有什么坑 {"tool_id":"form.create","level":"pitfalls"}
sspf_call 执行 {"tool_id":"schema.table.list","args":{}}

为什么不全量下发:55 个工具全注册约 18K token,200 个约 60K —— 还没干活就烧掉大半上下文。 现在常驻约 1.8K,用一个按需取一个(约 300 token)。

推荐调用顺序

sspf_context                       # 1. 先确认环境
  → sspf_discover("建一个报销单")    # 2. 找工具(返回精简索引)
  → sspf_describe(level="pitfalls") # 3. 先看坑(比看参数更重要)
  → sspf_call(dry_run=true)         # 4. 校验形态
  → sspf_call                       # 5. 真执行
  → 失败则读 error.hints / next_actions 自纠

3. 失败返回长什么样(比成功更重要)

业务失败不是 JSON-RPC error,而是正常返回里的结构化结果:

{
  "ok": false,
  "tool_id": "form.create",
  "error": {
    "code": "FORM_ENCODE_EXISTS",
    "message": "enCode 已存在:asset_ledger",
    "field": "enCode",
    "retryable": false,
    "hints": ["换一个 enCode,或对已有表单调用 form.update"],
    "next_actions": [
      { "tool": "form.list", "args": { "keyword": "asset_ledger" }, "why": "先确认是否同一个表单" }
    ]
  }
}

AI 应当据此改参数或先调 next_actions 里的工具,不要原样重试 —— 业务失败是确定性的(enCode 重复、无权限),原样重试一定再失败。

只有协议级问题(方法不存在、参数不是 JSON)才走 JSON-RPC 的 error。


4. 资源与提示

resources/read 可读:

URI 内容
sspf://registry/tools 全部业务工具索引(离线查阅用)
sspf://docs/quickstart 上面的推荐顺序与常见误区
sspf://contract/endpoints HTTP 契约端点表(与 MCP 工具不是一一对应)

5. 已知限制(P1 阶段)

限制 说明 计划
不与 HTTP 后端共用进程 MCP 与 HTTP 是两个进程,各自独占数据目录 P1.5 加 --mcp --with-http 双形态
没有登录态 进程内适配器是管理员视角,绕过菜单守卫 刻意如此(本地开发);对外暴露必须换 BaselineHttpAdapter
业务工具只有 4 个 context.get / schema.table.list / schema.table.describe / menu.tree P1 后续补到约 55 个
prompts/* 返回空 多步流程模板还没写 P2

6. 🔴 三个踩过的坑(改 MCP 代码前必读)

① 内嵌 PostgreSQL 会抢 stdin 和 stdout

pglite 的 PG single-user 后端会:

  • 往 fd 1 打 PostgreSQL stand-alone backend 17.5 和 backend> 提示符
  • 占用 fd 0 读 SQL —— 直接读 stdin 会拿到 ENXIO (Device not configured)

⇒ 内核在开库之前调 detach_stdio_for_mcp():先 dup 出协议通道, 再把 fd 0 指到 /dev/null、fd 1 指到 stderr。之后 PG 随便折腾,协议走专属 fd。

mcp-smoke.sh 的 M11/M12 就是钉住这个行为,改回去会立刻红。

② tokio 的 stdin / 文件 API 在管道上会 ENXIO

tokio::io::stdin() 与 tokio::fs::File 都要求 fd 可被 io 驱动注册; 复制出来的管道 fd 不满足。⇒ 用「独立线程同步读 + 同步写」(BlockingWriter)。

③ 业务失败与协议失败必须分开

混在一起,AI 分不清「我调错了」和「操作被业务规则拒了」, 会去改 tool_id 而不是改参数。协议错误只留给:方法不存在、参数不是 JSON。


7. 加一个业务工具的完整成本

  1. 在 crates/sspf-mcp/src/tools/mod.rs 写一个 ToolDef: schema + 注解 + 五段自提示(when_to_use / when_not_to_use / preconditions / pitfalls / examples)
  2. 加进 ALL_TOOLS
  3. 内核 mcp_adapter.rs 的 invoke() 加同名分支(op == tool.id,刻意同名)
  4. cargo test -p sspf-mcp —— 元测试会校验 schema 合法、one_liner ≤ 40 字、示例是合法 JSON、每个坑都有 rationale

协议层、元工具、注册表都不用改。 这是分层加载的直接收益。