- 新增 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
5.8 KiB
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. 加一个业务工具的完整成本
- 在
crates/sspf-mcp/src/tools/mod.rs写一个ToolDef: schema + 注解 + 五段自提示(when_to_use / when_not_to_use / preconditions / pitfalls / examples) - 加进
ALL_TOOLS - 内核
mcp_adapter.rs的invoke()加同名分支(op==tool.id,刻意同名) cargo test -p sspf-mcp—— 元测试会校验 schema 合法、one_liner≤ 40 字、示例是合法 JSON、每个坑都有rationale
协议层、元工具、注册表都不用改。 这是分层加载的直接收益。