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:
1 parent
b11ec26106
commit
217dadf008
20 files changed
+3173
-11
No files matched your search
@@ -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
|
||||
}
|
||||
|
||||
|
||||
Executable
+216
@@ -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"
|
||||
Reference in new issue
Block a user