feat(mcp): 落地 MCP 工具层 —— 4 元工具 + 分层加载 + 进程内适配器

- 新增 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
This commit is contained in:
admin committed 2026-10-31 10:29:14 +08:00
1 parent b11ec26106
commit 217dadf008
20 files changed
+3173 -11

No files matched your search

+5 -4
View File
@@ -20,8 +20,9 @@
# AR3 `crates/sspf-contract` 源码不许 `use axum|tokio|pglite|sqlx`
# —— 契约层一旦有 IO,业务包就再也不是「轻依赖」
# AR4 `crates/sspf-contract` 依赖 ⊆ {serde, serde_json, uuid, http}
# AR5 `crates/sspf-mcp`(若已存在)依赖 ⊆ {sspf-contract, serde, serde_json}
# —— MCP 层要能同时接「进程内内核」和「远端 Java 后端」⇒ 不许依赖内核内部
# AR5 `crates/sspf-mcp`(若已存在)依赖 ⊆ {sspf-contract, serde, serde_json, tokio, async-trait}
# —— MCP 层要能同时接「进程内内核」和「远端 Java 后端」⇒ **不许依赖内核内部**
# —— tokio / async-trait 是协议实现(stdio 异步读写)所需,不是业务依赖
# MEM1 非注释代码里不许出现 `SELECT *`
# —— 终端产品内存预算 ≤ 120MB(PLAN.md 判断 ⑥)⇒ 全表读进 Vec 直接爆
# MEM2 `crates/**` 与 `src/backend/src/platform/**` 里不许出现无界 `HashMap` 缓存
@@ -132,10 +133,10 @@ check_ar5() {
local f="$CRATES/sspf-mcp/Cargo.toml"
[ -f "$f" ] || { skip "AR5 sspf-mcp 不存在(P1 才落地)"; return; }
local deps; deps="$(deps_of "$f" | tr '\n' ' ')"
if subset_of "$deps" "sspf-contract serde serde_json"; then
if subset_of "$deps" "sspf-contract serde serde_json tokio async-trait"; then
ok "AR5 sspf-mcp 依赖干净([$deps])"
else
bad "AR5 sspf-mcp 依赖越界:[$deps] —— 只允许 sspf-contract/serde/serde_json"
bad "AR5 sspf-mcp 依赖越界:[$deps] —— 只允许 sspf-contract/serde/serde_json/tokio/async-trait"
fi
}
+216
View File
@@ -0,0 +1,216 @@
#!/usr/bin/env bash
# mcp-smoke.sh —— MCP 工具层契约尺子(第十道闸门)
#
# 测什么:**AI 能不能只靠 4 个元工具,把「找工具 → 看坑 → 执行」跑通**。
# 这是 P1 的唯一 KPI(PLAN.md §6.7)。
#
# 用法:
# bash scripts/mcp-smoke.sh # 用 debug 产物,自起隔离库
# bash scripts/mcp-smoke.sh --bin <path> # 指定二进制
#
# 退出码:0 全过 / 1 有断言失败 / 2 环境错
#
# ── 断言(每条一个「不变量」)──
# M1 initialize 报出 protocolVersion 与 serverInfo
# M2 tools/list **恰好 4 个**元工具(分层加载的硬约束)
# M3 业务工具**不出现**在 tools/list(否则 token 预算失效)
# M4 通知(无 id)不产生回复
# M5 sspf_context 返回 backend / tables / 能力域
# M6 sspf_discover 无 query ⇒ 分类树;有 query ⇒ 搜索结果
# M7 sspf_describe(level=pitfalls) 返回坑与前置条件
# M8 sspf_call 真执行业务工具并返回 ok=true
# M9 sspf_call 未知工具 ⇒ ok=false + TOOL_NOT_FOUND + next_actions(**不是**协议错误)
# M10 sspf_call(dry_run) 不产生副作用且能报缺参
# M11 **stdout 必须是纯 NDJSON**(每一行都能被 JSON 解析)
# M12 **stderr 不得混入协议 JSON**(防止重定向写反)
#
# 🔴 M11/M12 是在踩过一次坑之后加的:内嵌 PostgreSQL 会往 fd 1 打
# `PostgreSQL stand-alone backend 17.5` / `backend>`,且它的 single-user 后端
# 会占用 fd 0。内核在开库前用 `dup` 把协议通道整个复制出来(`detach_stdio_for_mcp`),
# 这两条断言就是钉住那个行为不被改回去。
set -u
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
BIN="$ROOT/target/debug/ssw-platform"
PASS=0
FAIL=0
while [ $# -gt 0 ]; do
case "$1" in
--bin) BIN="$2"; shift 2 ;;
--help) sed -n '2,32p' "$0"; exit 0 ;;
*) echo "未知参数: $1"; exit 2 ;;
esac
done
[ -x "$BIN" ] || { echo "❌ 二进制不存在: $BIN(先 cargo build)"; exit 2; }
command -v python3 >/dev/null || { echo "❌ 需要 python3"; exit 2; }
ok() { PASS=$((PASS + 1)); printf ' ✅ %s\n' "$1"; }
bad() { FAIL=$((FAIL + 1)); printf ' ❌ %s\n' "$1"; }
TMP="$(mktemp -d /tmp/sspf-mcp-smoke.XXXXXX)"
trap 'rm -rf "$TMP"' EXIT INT TERM
REQ="$TMP/req.ndjson"
OUT="$TMP/out.ndjson"
ERR="$TMP/err.txt"
cat > "$REQ" <<'NDJSON'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"sspf_context","arguments":{}}}
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"sspf_discover","arguments":{}}}
{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"sspf_discover","arguments":{"query":"表"}}}
{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"sspf_describe","arguments":{"tool_id":"schema.table.list","level":"pitfalls"}}}
{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"sspf_call","arguments":{"tool_id":"schema.table.list","args":{}}}}
{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"sspf_call","arguments":{"tool_id":"nope.nope","args":{}}}}
{"jsonrpc":"2.0","id":9,"method":"tools/call","params":{"name":"sspf_call","arguments":{"tool_id":"schema.table.describe","args":{},"dry_run":true}}}
{"jsonrpc":"2.0","id":10,"method":"ping","params":{}}
NDJSON
echo "── MCP 工具层契约尺子(4 元工具 + 分层加载)──"
PGLITE_DIR="$TMP/db" "$BIN" --mcp < "$REQ" > "$OUT" 2> "$ERR"
RC=$?
if [ "$RC" -ne 0 ]; then
echo "❌ MCP 进程退出码 $RC(期望 0)"
echo " stderr 尾部:"
tail -8 "$ERR" | sed 's/^/ /'
exit 2
fi
python3 - "$OUT" "$ERR" <<'PY'
import json, sys
out_path, err_path = sys.argv[1], sys.argv[2]
PASS = FAIL = 0
def ok(m): global PASS; PASS += 1; print(f" ✅ {m}")
def bad(m): global FAIL; FAIL += 1; print(f" ❌ {m}")
raw = open(out_path, encoding='utf-8', errors='replace').read()
lines = [l for l in raw.splitlines() if l.strip()]
# ---- M11 stdout 必须是纯 NDJSON ----
parsed = {}
bad_lines = []
for i, line in enumerate(lines, 1):
try:
m = json.loads(line)
except Exception:
bad_lines.append((i, line[:80]))
continue
if m.get("id") is not None:
parsed[m["id"]] = m
if bad_lines:
bad(f"M11 stdout 有 {len(bad_lines)} 行不是合法 JSON(NDJSON 被污染)")
for i, s in bad_lines[:3]:
print(f" 第{i}行: {s}")
else:
ok(f"M11 stdout 是纯 NDJSON({len(lines)} 行全部可解析)")
# ---- M12 stderr 不得混协议 ----
err = open(err_path, encoding='utf-8', errors='replace').read()
if '"jsonrpc"' in err:
bad("M12 stderr 混入了协议 JSON(重定向写反了)")
else:
ok("M12 stderr 无协议 JSON(日志与协议分离)")
def result(rid):
return parsed.get(rid, {}).get("result")
# ---- M1 initialize ----
r = result(1)
if r and r.get("protocolVersion") and r.get("serverInfo", {}).get("name") == "sspf-mcp":
ok(f"M1 initialize 报出 protocol={r['protocolVersion']} server={r['serverInfo']['name']}")
else:
bad("M1 initialize 响应不完整")
# ---- M2 恰好 4 个元工具 ----
tools = (result(2) or {}).get("tools", [])
names = [t.get("name") for t in tools]
expect = ["sspf_context", "sspf_discover", "sspf_describe", "sspf_call"]
if len(tools) == 4 and sorted(names) == sorted(expect):
ok("M2 tools/list 恰好 4 个元工具")
else:
bad(f"M2 tools/list 应为 4 个元工具,实际 {len(tools)}: {names}")
# ---- M3 业务工具不出现 ----
blob = json.dumps(result(2) or {}, ensure_ascii=False)
if "context.get" in blob or "schema.table.list" in blob:
bad("M3 业务工具泄漏到 tools/list(分层加载失效)")
else:
ok("M3 业务工具不在 tools/list(只能经 discover 访问)")
# ---- M4 通知不回复 ----
if len(parsed) == 10:
ok("M4 10 条带 id 的请求各一个回复;通知无回复")
else:
bad(f"M4 回复数 {len(parsed)},期望 10(通知不该有回复)")
# ---- M5 context ----
sc = (result(3) or {}).get("structuredContent", {})
if sc.get("backend") == "native" and isinstance(sc.get("tables"), int) and sc["tables"] > 0:
ok(f"M5 sspf_context: backend=native tables={sc['tables']} 能力域={len(sc.get('domains', []))}")
else:
bad(f"M5 sspf_context 异常: {json.dumps(sc, ensure_ascii=False)[:120]}")
# ---- M6 discover 两种模式 ----
d0 = (result(4) or {}).get("structuredContent", {})
d1 = (result(5) or {}).get("structuredContent", {})
if d0.get("mode") == "categories" and isinstance(d0.get("categories"), list):
ok(f"M6a discover 无 query ⇒ 分类树({len(d0['categories'])} 类)")
else:
bad("M6a discover 无 query 应返回分类树")
if d1.get("mode") == "search" and isinstance(d1.get("results"), list):
ok(f"M6b discover(query=表) ⇒ 搜索结果 {d1.get('count')} 条")
else:
bad("M6b discover 带 query 应返回搜索结果")
# ---- M7 describe pitfalls ----
dp = (result(6) or {}).get("structuredContent", {})
if dp.get("ok") and isinstance(dp.get("pitfalls"), list) and len(dp["pitfalls"]) > 0:
ok(f"M7 describe(pitfalls) 返回 {len(dp['pitfalls'])} 个坑")
else:
bad("M7 describe(pitfalls) 应返回坑清单")
# ---- M8 call 真执行 ----
c1 = (result(7) or {}).get("structuredContent", {})
if c1.get("ok") and c1.get("data", {}).get("count", 0) > 0:
ok(f"M8 sspf_call 执行业务工具成功(表数 {c1['data']['count']})")
else:
bad(f"M8 sspf_call 执行失败: {json.dumps(c1, ensure_ascii=False)[:120]}")
# ---- M9 未知工具 ⇒ 结构化错误(不是协议错误)----
r9 = parsed.get(8, {})
c2 = (r9.get("result") or {}).get("structuredContent", {})
if "error" not in r9 and c2.get("ok") is False \
and c2.get("error", {}).get("code") == "TOOL_NOT_FOUND" \
and isinstance(c2["error"].get("next_actions"), list):
ok("M9 未知工具 ⇒ ok=false + TOOL_NOT_FOUND + next_actions(业务失败未变成协议错误)")
else:
bad(f"M9 未知工具应返回结构化业务错误,实际: {json.dumps(r9, ensure_ascii=False)[:160]}")
# ---- M10 dry_run ----
c3 = (result(9) or {}).get("structuredContent", {})
if c3.get("dry_run") is True and isinstance(c3.get("problems"), list) and len(c3["problems"]) > 0:
ok(f"M10 dry_run 报出缺失必填参数({len(c3['problems'])} 项)")
else:
bad(f"M10 dry_run 应报缺参,实际: {json.dumps(c3, ensure_ascii=False)[:120]}")
print()
print(f"PASS={PASS} FAIL={FAIL}")
sys.exit(0 if FAIL == 0 else 1)
PY
RC=$?
echo "--------------------"
if [ "$RC" -eq 0 ]; then
echo "全绿 ✅(MCP 工具层契约闭环)"
else
echo "有 ❌,按上面修"
fi
exit "$RC"