Files
ssw-platform/scripts/mcp-smoke.sh
T
admin 217dadf008 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
2026-10-31 10:29:14 +08:00

217 lines
8.6 KiB
Bash
Executable File
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/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"