compare-cli-mcp

compare-cli-mcp

面向 Agent 流水线的 MCP（Model Context Protocol）服务，封装 compare-cli。提供三个工具，使用 stdio 传输，以 JSON 为主的响应，并可选提供人类可读报告。

设计约定：../docs/mcp.md。此软件包提供实现；行为和架构与设计版本保持一致。

属于 contract-ops 套件。

---

安装

compare-cli-mcp 将 compare-cli 作为同级依赖，因此请同时安装两者：

npm install -g compare-cli@^0.3.0 compare-cli-mcp@^0.1.1

然后运行：

compare-mcp           # spawns the MCP server on stdio

接入 MCP 客户端

Claude Desktop / Claude Code

将以下内容添加到 MCP 客户端配置中（例如，在 macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "compare-cli": {
      "command": "compare-mcp"
    }
  }
}

锁定基础目录（建议在无人值守时使用）

{
  "mcpServers": {
    "compare-cli": {
      "command": "compare-mcp",
      "env": {
        "COMPARE_MCP_BASE_DIR": "/path/to/contract/documents"
      }
    }
  }
}

之后，Agent 提供的每个 path 参数都会相对于 COMPARE_MCP_BASE_DIR 解析；如果路径超出该目录，则会被拒绝（符号链接会先被解析）。如果未设置此环境变量，服务可以读取进程有权读取的任何文件——请参阅 ../docs/mcp.md §3.2 中的安全说明。

工具

工具	用途
compare_files	比较两个文档。每一侧都接受 path、content_base64 或 content_text。
compare_with_negotiation	从 nda-review-cli 的 negotiation.json 读取基准文本。返回 base.negotiation_resolution，以便 Agent 审核哪个信号产生了双方同意的文本。
compare_demo	使用捆绑的测试文件进行零参数合成比较。确定性地返回 exit_class: "substantive"。可用于确认服务已正确接入。

工具描述、输入架构和输出架构会通过 tools/list 公布。此软件包 v1.x 版本中的架构保持稳定；任何变更都会由 tests/fixtures/tools-list.json 中的快照基准测试进行约束。

输出格式

每次成功的工具调用都会返回：

• structuredContent — 完全符合 compare --json 的格式（顶层字段为 ok、exit_class、exit_code、base、candidate、summary、differences、warnings）。根据 compare-cli 的 AGENTS.md，此格式在 compare-cli v1.x 中保持稳定。这是 Agent 读取的约定。
• content[0] — 将相同的 JSON 序列化为文本块，供尚未读取 structuredContent 的 MCP 客户端使用。
• content[1]（可选；调用方传入 include_human_report: true 时返回）— 人类可读报告。

compare_with_negotiation 会添加 structuredContent.base.negotiation_resolution ∈ {"status", "per_round_agreed", "clause_status"}，以指明哪个解析层级生成了双方同意的基准文本。

错误与偏差

实质性偏差属于成功的工具调用。 Agent 询问了有什么不同，服务端也给出了回答。根据 exit_class 路由是本契约的规定；错误封装（isError: true）仅用于 I/O / 参数错误，以及一种明确的前置条件异常：

代码	触发条件
INPUT_NOT_FOUND	路径不存在 / 无法读取。
INPUT_MALFORMED	.docx / .pdf 格式错误。
PDF_NO_TEXT_LAYER	扫描版 PDF；pdfjs 提取到的字符数为零。
INVALID_ARGS	未通过架构验证（缺少参数、违反 oneOf 等）。
PATH_OUTSIDE_BASE_DIR	已设置 COMPARE_MCP_BASE_DIR，且路径超出其范围。
NO_AGREED_ROUND	compare_with_negotiation 的前置条件：未找到达成一致的轮次。此时 CLI 返回退出码 2；由于未运行比较，MCP 服务会将其提升为错误。
NOT_SIGNED_OFF	require_signoffs: true，且 signoffs.a / signoffs.b 缺失。
INTERNAL_ERROR	意外错误；会显示底层消息，避免 Agent 无法了解情况。

这些代码在此软件包的 v1.x 版本中保持稳定。

运行测试套件

# From the repo root:
npm install              # workspaces resolve compare-cli + compare-cli-mcp
cd mcp && npm test       # 22 tests, ~100 ms

一致性测试和快照测试套件位于 tests/test_protocol.mjs。tools/list 的基准文件位于 tests/fixtures/tools-list.json。有意修改架构后（同时提升次要版本号），可按以下方式重新生成基准文件：

node -e 'import("./compare-cli-mcp.mjs").then(m => process.stdout.write(JSON.stringify(JSON.parse(JSON.stringify(m.TOOLS)), null, 2)))' > tests/fixtures/tools-list.json

许可证

MIT。请参阅 ../LICENSE。