Files
ssw-platform/docs/mcp.md
T
admin 1d1a3b1ef9 feat(mcp): schema.table.create 落地 + P2-b 冒烟闭环,修 data.query 泄漏口令列
- MCP:新增 schema.table.create(第 26 个业务工具)—— 库内功能按设计稿建表并回写
  f_tables_data;内联 formData/tablesData 只能演练(INLINE_REQUIRES_DRY_RUN);
  写且幂等(表已存在跳 DDL,列不同报 TABLE_EXISTS_DIFFERENT),默认 dryRun=true
- mcp-smoke 32 → 48 条:先 --seed-lowcode-demo 造 receivableDemo,再用同一 PGLITE_DIR
  起 --mcp,python 动态驱动(主键是服务端 UUID)跑通「默认演练不落库 → 真写 → 查证 →
  子表差集三类 → 删除 → 建表演练/幂等」;M4 回复数改为按请求文件计算,不再写死 29
- lowcode-smoke 8 → 15 条:用内联演练钉建表规则(类型映射+dataLength / 复合主键 /
  逻辑删除三列 / 系统列视图类型),外加两条反自证(不开逻辑删除就不加删除列;
  inline 不许落库)
- fix:data.query 不再投影 f_password / f_secretkey(实测能拖走全库口令哈希);
  缺省滤掉并返回 hiddenColumns,显式 columns/where/orderBy 要用 ⇒ SENSITIVE_COLUMN
- docs:PLAN / CLAUDE / docs/mcp / docs/visualdev-mechanism 补 P2-b 结论;
  业务工具数 21 → 26 由 tool_count_matches_doc 钉死;清 f_foreign_id 文档漂移
  (子表外键列来自模型 tableField);补单租户口径的三条交叉证据(K8s 配置 / Java 常量 /
  官方 DDL);记 UNIQUE_CONSTRAINT_VIOLATED / BUSINESS_KEY_VIOLATED
2026-10-31 21:34:37 +08:00

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

当前业务工具(26 个)

域 工具 一句话 写
context context.get 取后端/应用/表数
schema schema.table.list 列出物理表
schema schema.table.describe 看表的列与类型
schema schema.index.list 索引与唯一约束
schema schema.table.create 按低代码设计稿建表 + 回写模型 ✅
menu menu.tree 菜单树(按应用隔离)
menu menu.create 建菜单(写全 enCode + systemId) ✅
menu menu.delete 软删菜单 ✅
permission permission.user.list 用户(不含口令字段)
permission permission.user.create 建普通用户(可同时绑角色) ✅
permission permission.role.list 角色
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 建字典分类 ✅
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 校验表单声明的字段在表里是否真有列

写工具为什么少而严:读工具错了只是「看到错的数据」,写工具错了是「把库改坏」。 所以写工具都在写库之前做完校验(必填/格式/父节点存在/编码唯一), 并给出可执行的 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. 加一个业务工具的完整成本

  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

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