Compare Cli Mcp

io.github.DrBaherPublished by GitHub account DrBaherv0.1.4Updated Oct 28, 2026

MCP server for compare-cli: contract version diff/redline and a drift gate as agent tools.

VerifiedSTDIODesktop onlyProductivity & WorkflowDeveloper Tools

Overview

AI-generated overview

Local MCP server wrapping compare-cli so an assistant can diff two contract documents, redline them, and gate on drift.

What you can do
  • Compare two documents supplied as a path, base64, or plain text and get structured differences, exit class, and warnings
  • Compare a candidate against a base taken from an nda-review-cli negotiation.json, with the resolution tier reported for auditing
  • Run a zero-argument demo comparison against bundled fixtures to confirm the server is wired up
  • Return the compare --json contract as structured content plus a text block, optionally with a human-readable report
When to use it
Useful when an assistant needs to check whether a contract or document changed between versions, produce a redline, or decide in a pipeline whether drift is substantive. Also handy as a quick connectivity check via the demo tool.
Requirements
Runs locally over stdio as an npm package; compare-cli is a peer dependency and must be installed alongside it, then started with the compare-mcp command. No authentication, API keys, or environment variables are required, though COMPARE_MCP_BASE_DIR can optionally restrict file access to one directory.
Before you install
Without COMPARE_MCP_BASE_DIR the server can read any file the process can read, so setting that variable is recommended for unattended use. Document contents are passed to the local compare-cli process; scanned PDFs and malformed files return errors rather than text.

Installation

In SourceWeft

  1. Open Compare Cli Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

compare-cli-mcp

[npm version]

MCP (Model Context Protocol) server wrapping compare-cli for agent pipelines. Three tools, stdio transport, JSON-first responses with optional human report.

Design contract: ../docs/mcp.md. This package ships the implementation; behavior and schemas track the design version.

Part of the contract-ops suite.

Install

compare-cli-mcp has compare-cli as a peer dependency, so install both:

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

Then run:

sh
compare-mcp           # spawns the MCP server on stdio

Wire into an MCP client

Claude Desktop / Claude Code

Add to your MCP-client config (e.g. ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

With base-directory lockdown (recommended for unattended use)

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

Every path argument the agent supplies is then resolved against COMPARE_MCP_BASE_DIR and rejected if it escapes the directory (symlinks collapsed). Without the env var the server reads any file the process can read — see the security note in ../docs/mcp.md §3.2.

Tools

ToolPurpose
compare_filesTwo-document comparison. Each side accepts path, content_base64, or content_text.
compare_with_negotiationBase is read from nda-review-cli's negotiation.json. Returns base.negotiation_resolution so the agent can audit which signal produced the agreed text.
compare_demoZero-arg synthetic comparison against bundled fixtures. Deterministically returns exit_class: "substantive". Use to confirm the server is wired up.

Tool descriptions, input schemas, and output schemas are advertised on tools/list. The schemas are stable across v1.x of this package; any change is fenced by the snapshot golden in tests/fixtures/tools-list.json.

Output shape

Every successful tool call returns:

  • structuredContent — the exact compare --json shape (top-level ok, exit_class, exit_code, base, candidate, summary, differences, warnings). Stable across compare-cli v1.x per its AGENTS.md. This is the contract the agent reads.
  • content[0] — the same JSON serialized as a text block, for MCP clients that don't yet read structuredContent.
  • content[1] (optional, when caller passes include_human_report: true) — the human-readable report.

compare_with_negotiation adds structuredContent.base.negotiation_resolution ∈ {"status", "per_round_agreed", "clause_status"} indicating which of the three resolution tiers produced the agreed base text.

Errors vs drift

Substantive drift is a successful tool call. The agent asked what's different and the server answered. Routing on exit_class is the contract — error envelopes (isError: true) are reserved for I/O / argument failures plus one explicit precondition exception:

CodeTrigger
INPUT_NOT_FOUNDPath not found / unreadable.
INPUT_MALFORMEDMalformed .docx / .pdf.
PDF_NO_TEXT_LAYERScanned PDF; pdfjs extracted zero characters.
INVALID_ARGSSchema-validation failure (missing args, oneOf violation, etc.).
PATH_OUTSIDE_BASE_DIRCOMPARE_MCP_BASE_DIR is set and the path escapes it.
NO_AGREED_ROUNDcompare_with_negotiation precondition: no agreed round found. The CLI returns exit 2 here; the MCP server promotes it to an error because no comparison ran.
NOT_SIGNED_OFFrequire_signoffs: true and signoffs.a / signoffs.b is missing.
INTERNAL_ERRORUnexpected; surfaces underlying message so the agent isn't blind.

Codes are stable across v1.x of this package.

Running the test suite

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

The conformance + snapshot suite is in tests/test_protocol.mjs. The tools/list golden lives at tests/fixtures/tools-list.json. To regenerate the golden after an intentional schema change (also bump the minor version):

sh
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

License

MIT. See ../LICENSE.

Source: mcp/README.md at commit 8b28632

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.4LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts