# 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/sspf-admin --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 下也不稳)。 ### 想同时用浏览器看效果? ```bash ./target/release/sspf-admin --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 自纠 ``` ### 当前业务工具(52 个) | 域 | 工具 | 一句话 | 写 | |---|---|---|---| | context | `context.get` | 取后端/应用/表数 | | | context | `context.app.list` | 列多应用(`base_system`,默认不含主系统) | | | schema | `schema.table.list` | 列出物理表 | | | schema | `schema.table.describe` | 看表的列与类型 | | | schema | `schema.index.list` | 索引与唯一约束 | | | schema | `schema.table.create` | 按低代码设计稿建表 + 回写模型 | ✅ | | menu | `menu.tree` | 菜单树(按应用隔离) | | | menu | `menu.info` | 菜单详情(改之前先看) | | | menu | `menu.create` | 建菜单(写全 enCode + systemId) | ✅ | | menu | `menu.update` | 改菜单(名称/地址/图标/排序) | ✅ | | menu | `menu.delete` | 软删菜单 | ✅ | | permission | `permission.user.list` | 用户(**不含口令字段**) | | | permission | `permission.user.create` | 建普通用户(可同时绑角色) | ✅ | | permission | `permission.user.delete` | 软删用户(管理员不可删) | ✅ | | permission | `permission.organize.tree` | 组织机构(平铺,含 parentId) | | | permission | `permission.role.list` | 角色 | | | permission | `permission.role.create` | 建角色(enCode 全平台唯一) | ✅ | | permission | `permission.role.delete` | 软删角色(系统角色不可删) | ✅ | | permission | `permission.authorize.list` | 查某对象的直授 | | | permission | `permission.authorize.grant` | 给用户/角色/组织/岗位授菜单(幂等) | ✅ | | permission | `permission.authorize.revoke` | 撤权(软删,撤不存在会报错) | ✅ | | permission | `permission.effective` | 四源并集算出**实际**可见的菜单 | | | dict | `dict.type.list` | 字典分类 | | | dict | `dict.data.list` | 字典项 | | | dict | `dict.type.create` | 建字典分类 | ✅ | | dict | `dict.type.update` | 改字典分类 | ✅ | | dict | `dict.type.delete` | 软删分类(**不级联**字典项) | ✅ | | dict | `dict.data.create` | 往分类追加字典项 | ✅ | | data | `data.query` | 按表名查数据(结构化条件) | | | data | `data.count` | 按表名计数 | | | data | `data.record.insert` | 按设计稿新增记录(主表 + 子表) | ✅ | | data | `data.record.update` | 按设计稿更新(子表差集对账) | ✅ | | data | `data.record.delete` | 删记录(逻辑/物理按功能设置) | ✅ | | form | `form.list` | 列低代码功能(`base_visual_dev`) | | | form | `form.describe` | 解析表单:主表字段/子表/控件类型 | | | form | `form.validate` | 校验表单声明的字段在表里是否真有列 | | | form | `form.create` | 建表单定义(草稿态;`formData` 可传对象) | ✅ | | form | `form.update` | 改表单定义(只 SET 传了的键) | ✅ | | form | `form.delete` | 软删功能(菜单需另行清理) | ✅ | | form | `form.selector` | 功能下拉(挂菜单/绑流程用) | | | workflow | `workflow.template.list` | 流程模板列表(元数据) | | | workflow | `workflow.template.info` | 模板详情 | | | workflow | `workflow.template.create` | 建模板(只写元数据) | ✅ | | workflow | `workflow.template.update` | 改模板 | ✅ | | workflow | `workflow.template.delete` | 软删模板 | ✅ | | workflow | `workflow.template.selector` | 流程下拉(绑表单/菜单用) | | | workflow | `workflow.task.list` | 任务元数据(无引擎 ⇒ 通常为空) | | | ops | `ops.health` | 表数 / 会话数 / admin 就绪 | | | ops | `ops.logs` | 按分类查系统日志 | | | ops | `ops.online` | 按账号聚合的在线会话(不含 token) | | | ops | `ops.schedule.list` | 定时任务定义(不跑调度) | | | ops | `ops.db.stats` | 关键表行数 + 库体积 | | **P3 这批(26 个)怎么实现的**:不重写 SQL,而是**进程内直调契约面 handler** (`crates/sspf-mcp-adapter/src/mcp_compat.rs`),与 HTTP 路由注册的是同一个函数 ⇒ 校验、默认值、 软删语义只有一份。代价是 MCP 适配器必须构造管理员请求头(`SessionStore::issue` 一个 `admin` 会话),所以**它只适用于本地开发**;对外暴露要走 `BaselineHttpAdapter` 带真实 token。 **写工具为什么少而严**:读工具错了只是「看到错的数据」,写工具错了是「把库改坏」。 所以写工具都在写库**之前**做完校验(必填/格式/父节点存在/编码唯一), 并给出可执行的 `hints`;删除一律软删。 🔴 **`data.query` 不投影口令 / 密钥列**(`f_password` / `f_secretkey`): 缺省投影会跳过它们并在结果里返回 `hiddenColumns`(藏了几列); 显式在 `columns` / `where` / `orderBy` 里要它们 ⇒ `SENSITIVE_COLUMN`。 要用户信息请用 `permission.user.list`(它本来就不返回口令字段)。 🔴 **`menu.create` 比 HTTP 侧的 `module_save` 更完整**:后者只写 12 列,缺 `f_en_code`(面 B 权限判据)与 `f_system_id`(多应用隔离)——那两列缺了, 菜单要么点进去 403,要么根本不显示。P2 元数据引擎统一时会把两处合成一处。 ### 授权闭环:建完菜单不等于看得见 ``` menu.create 建菜单 → permission.authorize.grant 授给角色(推荐)或用户(临时特批) → permission.user.create 建一个**非管理员**账号验证 → permission.effective 看他实际能访问什么,每项标明来自哪个源 ``` 🔴 **绝不能用 admin 验证**:`is_admin == 1` 在守卫第一条判据就返回 true, 根本不查授权表 —— 用 admin 测等于什么都没测。`permission.effective` 会显式 返回 `isAdmin: true` 与 `mode: "admin-bypass"`,提醒你这个结果不代表授权生效。 `permission.effective` 返回两组数,这是排查「授权了但看不见」的关键: | 字段 | 含义 | |---|---| | `fourSource` | 四源并集(直授 + 角色 + 组织 + 岗位),**不按应用过滤** | | `visible` | 再与当前应用的菜单求交 —— 这才是用户真正能点到的 | | `sources.*` | 每个源各贡献了哪些菜单 id(定位「这条权限从哪来」) | 两者不一致 ⇒ 授权指向了别的应用的菜单(或菜单已删)。 ### 低代码:看懂一张表单,先于写它 ``` form.list 有哪些功能(type/state) → form.describe 主表字段 / 子表 / 每个控件的存储类别 → form.validate 表单声明的字段 ↔ 表结构对不对得上 ``` `form.describe` 和 `form.validate` 支持**两种输入**: | 模式 | 入参 | 用在哪 | |---|---|---| | 查库 | `id` 或 `enCode` | 功能已经在 `base_visual_dev` 里 | | **inline** | `formData`(+ `tablesData`) | 草稿还没入库,先校验再说 | inline 模式是刻意的:AI 生成一份表单 JSON 后**先校验、后落库**,比写完再报错成本低得多。 **控件分类决定数据怎么存**(`sspf-lowcode/src/widget.rs`,54 种 jnpfKey → 11 类): | 类别 | 举例 | 接收入参 | |---|---|---| | text / number / dateTime / enum | `input` `inputNumber` `datePicker` `select` | ✅ | | entityRef | `userSelect` `organizeSelect` | ✅(存 id) | | attachment | `uploadFile` | ✅(URL 列表 JSON) | | **systemGenerated** | `billRule` `createUser` `createTime` | ❌ 后端填 | | **layout** | `groupTitle` `divider` | ❌ 不占列 | | **subTable** | `table` | ❌ 数据在独立表 | 🔴 让入参覆盖 `billRule`(单据号)或 `createUser`,会破坏业务编号规则与审计链路 —— 这是「数据被写坏」最常见的来源,所以 `acceptsInput` 在 `describe` 里显式返回。 **列名规则是确定的**(已对齐 jnpf 建表逻辑,见 `docs/visualdev-mechanism.md` §3): ``` 低代码动态建的表:列名 = lower(__vModel__) F_Room → f_room F_CreatorTime → f_creatortime(不是 f_creator_time) ``` jnpf 建表时原样写 vModel,PG/Kingsbase 再 `toLowerCase()`。 ⚠️ 平台表(`base_*`)的 `f_creator_time` 是**手写 DDL**,与这条规则无关 —— 别混。 **`form.validate` 只保证「设计稿自洽」,不等于「表已经建好了」**: 它比对表单推导的列与模型 `field` 推导的列(两边同一套规则,所以能验出「表单引用了模型里没有的字段」)。 但库里到底有没有这张表、列够不够,要拿 `information_schema` 比 —— 这一步由 P2-b 的写工具在**落库前**做(对不上报 `COLUMN_MISMATCH` / `TABLE_NOT_IN_DB`,拒绝写)。 ### 低代码动态 CRUD(P2-b) ``` schema.table.create(dryRun) 先看要建的 DDL 与回写后的模型 → schema.table.create 建表 + 回写 f_tables_data(幂等) → data.record.insert(dryRun) 看 SQL 与参数 → data.record.insert 落库 → data.query 查证 → data.record.update 改主表字段 / 子表差集对账 → data.record.delete 删(逻辑或物理,按功能的 logicalDelete) ``` **建表不是可选项**:低代码功能的表不会自己出现。`data.record.*` 直接写一张不存在的表 会报 `TABLE_NOT_IN_DB` —— 这时先 `schema.table.create`。 🔴 **建表后必须回写 `f_tables_data`**(工具内部做,`dryRun=false` 时)。 不回写的后果不是「少一列」这么轻:CRUD 层在**模型**里找 `f_delete_mark`, 找不到就报 `LOGICAL_DELETE_UNSUPPORTED`;而且「设计稿 vs 真实库」的列比对永远对不上。 基线平台 `VisualDevTableCre.tableList()` 建完表也是把装配后的 `TableModel` 写回 `f_tables_data`。 `schema.table.create` 支持两种输入: | 模式 | 入参 | 能落库吗 | |---|---|---| | 查库 | `id` / `enCode` | ✅ `dryRun=false` 建表 + 回写 | | inline | `formData` + `tablesData` | ❌ 只能演练(`INLINE_REQUIRES_DRY_RUN`)—— 没有可回写的功能记录 | **子表更新是差集对账,不是整条替换**(与主表的部分更新语义不同): | 情况 | 动作 | |---|---| | 入参行的主键在库里 | `updateSub` | | 入参行的主键不在库里 | `insertSub` | | 库里有、入参没有 | 删除(`logicalDelete` 开则 `softDelete`,否则 `hardDelete`) | 🔴 因此「只改子表一行的某个字段」也必须把**这张子表的所有行**都传进来, 否则没传的旧行会被删掉。只想追加不改动,就先把现有行查出来一起传。 **三道落库前校验**(都对齐基线平台,失败时一条 SQL 都不执行): | 校验 | 触发条件 | 错误码 | |---|---|---| | 单行唯一 | 控件 `unique=true` 且是普通输入 | `UNIQUE_CONSTRAINT_VIOLATED` | | 业务主键组合唯一 | 表单 `useBusinessKey=true` | `BUSINESS_KEY_VIOLATED` | | 必填 | 控件 `required=true` | `MISSING_REQUIRED` | 查重只算**未删除**的行(`f_delete_mark=0` 或该列不存在);更新时排除自己。 **写工具默认 `dryRun=true`**(不传就是演练)。dry-run 会返回完整 SQL 与参数 —— 这是刻意的:AI 要先能看清「到底写什么」,才谈得上让人放心让它写。 返回值里不含任何口令字段(适配器层就不投影这类列);业务数据本身**不做脱敏** —— dry-run 的意义就是让人核对真实值,遮掉反而看不出写错在哪。 ### 造一份示例功能:`--seed-lowcode-demo` ```bash PGLITE_DIR=/tmp/sspf-demo ./target/debug/sspf-admin --seed-lowcode-demo # 建表 + 写功能定义 PGLITE_DIR=/tmp/sspf-demo ./target/debug/sspf-admin --seed-lowcode-demo --dry-run # 只看不碰库(连库都不开) ``` - 固定 `id=lowcode-demo-receivable` + `enCode=receivableDemo` ⇒ **幂等**(重复跑是更新同一条) - 数据来源是**官方 fixture**(基线初始化数据里的「应收费用」)⇒ 种出来的库就是真实低代码功能的样子 - 只在 dev 档可用:`SSW_PROFILE=prod|production` 在**开库前**就拒绝(它会建表) - 种完可以立刻 `data.record.insert {"enCode":"receivableDemo",...}` 端到端试写 --- ## 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 工具不是一一对应) | ### 多步流程模板(`prompts/*`) 模板回答的是「整件事按什么顺序做、做到哪算完成」——AI 最容易错的不是参数, 而是**漏步骤**(建了菜单忘授权、授权了没验证)。 | 模板 | 参数 | 干什么 | |---|---|---| | `new_business_module` | `module_name` / `module_code` / `role_id`(可选) | 建菜单 → 授权 → 建非管理员账号 → 验证可见,共 5 步 + 失败对照表 | | `diagnose_menu_not_visible` | `account` | 五步定位法,按 `fourSource` / `visible` 分流判断根因 | | `verify_all` | — | 一次跑完全部测试、静态闸门、契约尺子、内存实测 | 模板**不占常驻 token**(只在用户主动引用时 `prompts/get`)。 🔴 模板正文里引用了工具 id,工具改名后模板会变成错误指导且**没人会发现**。 `crates/sspf-mcp/src/prompts.rs` 的测试会扫出正文里所有 `域.动作` 字符串逐个核对, 引用不存在的工具 ⇒ 测试失败。 ### 双后端:同一套工具打两种后端 `PlatformAdapter` 只有两个方法,实现有三个(`Null` 是测试用): | 实现 | 位置 | 后端 | 用在哪 | |---|---|---|---| | `NativeAdapter` | `crates/sspf-mcp-adapter/src/mcp_adapter.rs` | 进程内 `AppState` | 主力形态(`--mcp`) | | `BaselineHttpAdapter` | `crates/sspf-adapter-baseline` | 远端 HTTP(Java 后端或本仓内核) | P4 影子对账 / 过渡期提速 | 基线适配器**刻意只映射 5 个只读 op**(`context.get` / `menu.tree` / `permission.user.list` / `permission.role.list` / `dict.type.list`): - baseline 是**业务 API**,没有「列出表结构」这类端点 —— 硬凑会造出 「看起来能跑、语义其实不对」的工具,比明确不支持更糟 - 不支持的 op 返回 `CAPABILITY_UNSUPPORTED` + 「切 native」的可执行建议 它同时是**形状适配器**(这才是对账的关键): ``` baseline: {code,msg,data:{list,pagination}} → native: {count, users/roles/menus/types} organize → organizeId 多余键(creatorTime/fullName…) → 裁掉 ``` 形状不统一时,对账每一条都是差异,看不出业务问题。 ```bash # 探针:用它打任意实现了契约的 HTTP 后端 PGLITE_DIR=/tmp/db PORT=30994 ./target/release/sspf-admin & cargo run -p sspf-adapter-baseline --example probe -- \ http://127.0.0.1:30994 admin "$(./target/release/sspf-admin --enc 123456)" ``` 🔴 口令要传**密文**(`--enc` 生成)。适配器不复制 cipher 逻辑 —— 复制会漂移,下沉到 contract 会破坏「契约层无 IO」的边界(AR4)。 --- ## 5. 已知限制(P2-b 收尾时点) | 限制 | 说明 | 计划 | |---|---|---| | 没有登录态 | 进程内适配器是**管理员视角**,绕过菜单守卫 | 刻意如此(本地开发);对外暴露必须换 `BaselineHttpAdapter` | | 业务工具 26 个 | 见上面清单;model / workflow / release 域还没有 | P3 补 | | 读的是 `base_visual_dev`,不是 release | 只读工具与动态 CRUD 都取草稿表;发布快照 `base_visual_release` 只有种子在写 | 运行时读 release 待补(P2-c) | | 单据号生成器未做 | `billRule` 控件不接收入参,但**也不会自动生成**(需序号表);入参给了 `billRule` 字段会被忽略 | 序号表 + 规则引擎(P2-c) | | 没有乐观锁 | `concurrencyLock=true` 时插入会写 `f_version=0`,但更新**不校验**版本 | 真并发控制(P3) | | 建表只建不改 | 表已存在且列不同 ⇒ `TABLE_EXISTS_DIFFERENT`,不自动 ALTER | 刻意:自动迁移比报错危险 | | `schema.table.create` 只在 dev 档建表 | 生产档拒绝(会改库结构) | 刻意 | | 基线适配器只支持 5 个只读 op | baseline 无元数据 API | P4 按对账需要再补 | | 基线适配器只支持 `http://` | 未引入 TLS 栈;`https://` 构造期直接报错 | 需要时再加 | | `permission.user.create` 不开放建管理员 | `isAdministrator` 硬编码 false | 刻意:避免 AI 顺手造超管 | | 🔴 **stderr 不能是 `/dev/null`** | 见下方「坑 ④」 | 已在代码里尽量兜,但客户端请收 stderr | ### 🔴 坑 ④:stderr 指向 `/dev/null` 时会零响应 `--mcp` 模式会把 fd 1 让给 stderr(为了让 PG 的 `backend>` 日志不污染 NDJSON)。 如果**stderr 恰好是 `/dev/null`**,协议通道会和它共享同一个 file 描述, 导致写出去的数据被吞 —— 表现为**一条响应都没有,退出码却是 0**。 - ✅ MCP 客户端(Claude Code / Cursor 等)都会收 stderr 进日志 ⇒ 生产场景没问题 - ✅ shell 里测试用 `2>/tmp/mcp.log` - ❌ 别用 `2>/dev/null` 测 MCP `mcp-smoke.sh` 用的就是 `2> "$ERR"`(文件),所以能跑。 --- ## 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` **协议层、元工具、注册表都不用改。** 这是分层加载的直接收益。