Files
ssw-platform/docs/mcp.md
T
admin 16266c93c3 feat(mcp): 业务工具扩到 12 个 + --mcp --with-http 双形态
- 新增 8 个只读工具:permission(user/role/authorize) · dict(type/data) · data(query/count) · schema(index)
- data.query/count 走严格白名单:表名 valid_table、列名查 information_schema、值全参数化
  (参数化只防值注入,结构注入必须靠列白名单)
- `--mcp --with-http`:MCP 与 HTTP 同一进程、同一 AppState、同一个库,人机协作不用切进程
- mcp-smoke 13 → 20 条(新增四域可用性 / 列裁剪 / 结构注入防护)
- 影响:测试 280;踩坑两处 —— COALESCE 默认值类型必须与列一致;入参 f_ 列名 / 出参 camelCase 两套命名
2026-10-31 10:47:06 +08:00

7.1 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 下也不稳)。

想同时用浏览器看效果?

./target/release/ssw-platform --mcp --with-http

同一进程、同一个 AppState、同一个库:AI 通过 MCP 建的表 / 写的菜单, 浏览器刷新就能看到;反之亦然。这才是「人 + AI 协作」该有的手感 —— 不用来回切进程、切数据目录。

MCP 客户端里加 "args": ["--mcp", "--with-http"] 即可, HTTP 默认监听 30010(PORT 可改),前端代理指过来就行。

⚠️ 一个数据目录只能被一个进程打开(pglite 独占)。 已经用 --with-http 起了服务,就别再单独起一个 ssw-platform。


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 自纠

当前业务工具(12 个,全部只读)

域 工具 一句话
context context.get 取后端/应用/表数
schema schema.table.list 列出物理表
schema schema.table.describe 看表的列与类型
schema schema.index.list 索引与唯一约束
menu menu.tree 菜单树(按应用隔离)
permission permission.user.list 用户(不含口令字段)
permission permission.role.list 角色
permission permission.authorize.list 查某对象的直授
dict dict.type.list 字典分类
dict dict.data.list 字典项
data data.query 按表名查数据(结构化条件)
data data.count 按表名计数

为什么这批全是只读:写工具的正确性依赖平台约束(enCode 唯一、菜单三处一致、 授权四源合并),这些在 P2 元数据引擎里才成体系。现在硬写「建菜单」会造出一堆 「能跑但会埋雷」的工具 —— 不如先把「看清现状」做扎实。


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 阶段)

限制 说明 计划
没有登录态 进程内适配器是管理员视角,绕过菜单守卫 刻意如此(本地开发);对外暴露必须换 BaselineHttpAdapter
业务工具 12 个,全只读 见上面清单 P1 后续补写工具;P2 补 form / model / workflow
prompts/* 返回空 多步流程模板还没写 P2
没有 BaselineHttpAdapter 只能驱动自身内核,不能打远端 Java 后端 P4 对账前必须有

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

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