- 新增 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
158 lines
5.8 KiB
Markdown
158 lines
5.8 KiB
Markdown
# 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`
|
||
|
||
**协议层、元工具、注册表都不用改。** 这是分层加载的直接收益。
|