- permission.organize.tree(机构平铺列表,建用户前取 organizeId) - form.selector(挂菜单/绑流程选功能) - ops.db.stats(关键表行数 + 库体积,快速判断空库/错库) - 同步 docs/mcp.md / PLAN / HANDOFF 的 52 个口径;全量测试与八道静态闸门全绿
22 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 下也不稳)。
想同时用浏览器看效果?
./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 自纠
当前业务工具(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
(src/backend/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
PGLITE_DIR=/tmp/sspf-demo ./target/debug/ssw-platform --seed-lowcode-demo # 建表 + 写功能定义
PGLITE_DIR=/tmp/sspf-demo ./target/debug/ssw-platform --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,而是正常返回里的结构化结果:
{
"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 |
src/backend/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…) → 裁掉
形状不统一时,对账每一条都是差异,看不出业务问题。
# 探针:用它打任意实现了契约的 HTTP 后端
PGLITE_DIR=/tmp/db PORT=30994 ./target/release/ssw-platform &
cargo run -p sspf-adapter-baseline --example probe -- \
http://127.0.0.1:30994 admin "$(./target/release/ssw-platform --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. 加一个业务工具的完整成本
- 在
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
协议层、元工具、注册表都不用改。 这是分层加载的直接收益。