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

158 lines
5.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`
**协议层、元工具、注册表都不用改。** 这是分层加载的直接收益。