# MCP 工具层 —— 让 AI 直接驱动 SSPF > 一个进程、一条 stdio、4 个工具,AI 就能建表 / 建菜单 / 查数据。 > 架构与设计动机见 `PLAN.md` §6;本文只讲**怎么接、怎么用、踩过什么坑**。 --- ## 1. 30 秒接入 ```bash # 确认二进制在 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`,或客户端对应的配置文件): ```json { "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,而是正常返回里的结构化结果: ```json { "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` **协议层、元工具、注册表都不用改。** 这是分层加载的直接收益。