ccs-mcp-server 1.3.0 → 1.4.0

package/src/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * CCS Runtime Evidence MCP Server v1.0.0
+ * CCS Runtime Evidence MCP Server
  *
  * A standalone Model Context Protocol (MCP) server that exposes CCS runtime
  * verification as MCP tools, so any MCP-compatible client (Claude Desktop,
@@ -435,7 +435,7 @@ function verifyIntentBinding(intent, toolName, toolArgs, now = Date.now()) {
 // ---------------------------------------------------------------------------
 
 const PROTOCOL_VERSION = "2024-11-05";
-const SERVER_INFO = { name: "ccs-runtime-evidence", version: CCS_VERSION, title: "CCS Runtime Evidence" };
+const SERVER_INFO = { name: "agent-runtime-guard", version: CCS_VERSION, title: "Agent Runtime Guard" };
 
 // MCP tool annotations (spec 2024-11-05+). Hints describe the tool's real
 // runtime behaviour so clients/registries can drive consent, UI gating and
@@ -718,7 +718,67 @@ function handleRequest(req) {
   return null;
 }
 
+function cliInfo() {
+  const S = "  ";
+  return [
+    `ccs-mcp-server v${CCS_VERSION} — Agent 运行时验证 + CCS 收据验签`,
+    ``,
+    `用法:`,
+    `${S}npx -y ccs-mcp-server              # 作为 MCP server 启动（stdio）`,
+    `${S}npx -y ccs-mcp-server --help       # 显示本说明`,
+    `${S}npx -y ccs-mcp-server --version    # 显示版本`,
+    `${S}npx -y ccs-mcp-server --tools      # 列出可用工具`,
+    ``,
+    `配置到 MCP 客户端（Claude Code / Cursor / Cline / Windsurf）:`,
+    `${S}{ "mcpServers": { "ccs-mcp-server": { "command": "npx", "args": ["-y", "ccs-mcp-server"] } } }`,
+    ``,
+    `免费可用（本地离线，零依赖，无需 API key）:`,
+    `${S}verify_tool_call       7 维运行时验证，危险调用默认拦截（fail-closed）`,
+    `${S}issue_evidence         Ed25519 证据收据（放行与拦截都产生，第三方可离线验证）`,
+    `${S}audit_mcp_config       MCP 配置静态安全审计`,
+    `${S}verify_intent_binding  校验实际参数与声明意图是否一致（抓跨模型参数漂移）`,
+    `${S}verify_receipt         离线验签 CCS 收据、检测篡改`,
+    `${S}locate_tampering       逐字段定位收据被改动的位置（RFC 6901 路径）`,
+    ``,
+    `需要订阅（¥49.90/月，支付宝 SkillPay）:`,
+    `${S}· CCS收据验签        深度篡改取证`,
+    `${S}· CCS收据批量审计    目录级批量验签与合规留痕`,
+    `${S}· MCP配置安全体检    完整 7 维分级报告`,
+    `${S}货架: https://skillpay.alipay.com/public/correctover`,
+    ``,
+    `文档: https://github.com/DSHCorrectover/agent-runtime-guard`,
+  ].join("\n");
+}
+
+function cliTools() {
+  return [
+    "verify_tool_call       Runtime verification, 7 dimensions, fail-closed by default",
+    "issue_evidence         Issue an Ed25519-signed evidence receipt",
+    "audit_mcp_config       Static security audit of MCP server configuration",
+    "verify_intent_binding  Detect drift between declared intent and actual arguments",
+    "verify_receipt         Offline receipt verification and tamper detection",
+    "locate_tampering       Field-level localization of tampered fields (RFC 6901)",
+  ].join("\n");
+}
+
 function main() {
+  // CLI 参数层：只处理显式的信息类参数，未命中则行为与以往完全一致。
+  // 为什么需要这层：MCP 客户端调用不带参数，但人类用户会敲 --help / --version 探路。
+  // 之前无论传什么参数都直接启动 stdio 服务并打广告，用户得不到任何信息、命令还会挂住。
+  const argv = process.argv.slice(2);
+  if (argv.includes("--help") || argv.includes("-h") || argv.includes("help")) {
+    process.stdout.write(cliInfo() + "\n");
+    process.exit(0);
+  }
+  if (argv.includes("--version") || argv.includes("-v")) {
+    process.stdout.write(CCS_VERSION + "\n");
+    process.exit(0);
+  }
+  if (argv.includes("--tools")) {
+    process.stdout.write(cliTools() + "\n");
+    process.exit(0);
+  }
+
   const kp = receipts.getKeypair();
   const fp = receipts.publicKeyFingerprint();
   const banner =

package/test/run-tests.js

@@ -248,6 +248,102 @@ test("指针与点号路径同时可查（既有消费方不被破坏）", () =>
   assert.strictEqual(d.path_dotted, "a.b");
 });
 
+// ---------------------------------------------------------------------------
+// 6. CLI 参数层
+//
+// 为什么这些断言重要：用户会用 --help / --version 探路。
+// 在此之前，任何参数都会被无视、直接启动 stdio 服务并打广告 ——
+// 用户得不到信息、命令还会挂住，这是最早的流失点。
+// 同时必须保证：CLI 层是纯增量的，不带参数时协议行为一字不变。
+// ---------------------------------------------------------------------------
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+const INDEX = path.join(__dirname, "..", "src", "index.js");
+
+function runCli(args, input) {
+  return spawnSync(process.execPath, [INDEX, ...args], {
+    input: input || "",
+    encoding: "utf8",
+    timeout: 15000,
+  });
+}
+
+test("--help 输出版本号", () => {
+  const r = runCli(["--help"]);
+  assert.strictEqual(r.status, 0);
+  assert.ok(/ccs-mcp-server v\d+\.\d+\.\d+/.test(r.stdout), "缺少版本号行");
+});
+
+test("--help 输出用法说明而非广告", () => {
+  const r = runCli(["--help"]);
+  assert.ok(r.stdout.includes("用法:"), "缺少用法段");
+  assert.ok(r.stdout.includes("mcpServers"), "缺少 MCP 配置示例");
+});
+
+test("--help 列出全部工具", () => {
+  const r = runCli(["--help"]);
+  for (const tool of ["verify_tool_call", "issue_evidence", "audit_mcp_config",
+                      "verify_intent_binding", "verify_receipt", "locate_tampering"]) {
+    assert.ok(r.stdout.includes(tool), `--help 未列出工具 ${tool}`);
+  }
+});
+
+test("--help 不把广告放在开头", () => {
+  const r = runCli(["--help"]);
+  const firstLine = r.stdout.split("\n")[0];
+  assert.ok(!firstLine.includes("支付宝"), "第一行就是广告（时序错位）");
+});
+
+test("--version 只输出版本号", () => {
+  const r = runCli(["--version"]);
+  assert.strictEqual(r.status, 0);
+  assert.strictEqual(r.stdout.trim(), require("../package.json").version);
+});
+
+test("-v 与 --version 等价", () => {
+  assert.strictEqual(runCli(["-v"]).stdout.trim(), require("../package.json").version);
+});
+
+test("-h 与 --help 等价", () => {
+  assert.ok(runCli(["-h"]).stdout.includes("用法:"));
+});
+
+test("--tools 输出纯工具名，无广告", () => {
+  const r = runCli(["--tools"]);
+  assert.strictEqual(r.status, 0);
+  assert.ok(r.stdout.includes("verify_tool_call"));
+  assert.ok(!r.stdout.includes("支付宝"), "--tools 不应含广告");
+  assert.ok(!r.stdout.includes("SkillPay"), "--tools 不应含 SkillPay");
+});
+
+test("CLI 参数不启动 stdio 服务（立即退出）", () => {
+  const r = runCli(["--help"]);
+  assert.strictEqual(r.status, 0, "应正常退出而非挂住等待 stdin");
+});
+
+test("不带参数时协议行为不变：initialize 正常", () => {
+  const r = runCli([], '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}\n');
+  const line = r.stdout.split("\n").find((l) => l.includes('"id":1'));
+  assert.ok(line, "未收到 initialize 响应");
+  const d = JSON.parse(line);
+  assert.ok(d.result && d.result.serverInfo, "响应结构异常");
+  assert.strictEqual(d.result.protocolVersion, "2024-11-05");
+});
+
+test("不带参数时协议行为不变：tools/list 返回 6 个工具", () => {
+  const r = runCli([], '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n');
+  const line = r.stdout.split("\n").find((l) => l.includes('"id":1'));
+  const d = JSON.parse(line);
+  assert.strictEqual(d.result.tools.length, 6);
+});
+
+test("未知参数不误触发 CLI 层（仍进入服务模式）", () => {
+  const r = runCli(["--nonexistent-flag"], '{"jsonrpc":"2.0","id":1,"method":"ping"}\n');
+  const line = r.stdout.split("\n").find((l) => l.includes('"id":1'));
+  assert.ok(line, "未知参数不应阻止服务启动");
+});
+
 // ---------------------------------------------------------------------------
 console.log(`\n${"=".repeat(52)}`);
 console.log(`  ${passed}/${passed + failed} PASS`);