compare-cli-mcp

compare-cli-mcp

エージェントのパイプライン向けに、compare-cli をラップする MCP（Model Context Protocol）サーバーです。3 つのツール、stdio トランスポート、JSON 優先のレスポンスに加え、任意で人間向けレポートを提供します。

設計上の契約：../docs/mcp.md。このパッケージには実装が含まれています。動作とスキーマは設計バージョンに準拠しています。

contract-ops suite の一部です。

---

インストール

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"
      }
    }
  }
}

これにより、エージェントが指定するすべての path 引数は COMPARE_MCP_BASE_DIR を基準に解決され、ディレクトリ外へのアクセスは拒否されます（シンボリックリンクは解決されます）。環境変数を設定しない場合、サーバーはプロセスが読み取り可能なあらゆるファイルを読み取ります。../docs/mcp.md §3.2 のセキュリティに関する注意を参照してください。

ツール

ツール	目的
compare_files	2 つのドキュメントを比較します。各側では path、content_base64、または content_text を指定できます。
compare_with_negotiation	nda-review-cli の negotiation.json からベースを読み取ります。base.negotiation_resolution を返すため、エージェントは合意テキストの生成に使用されたシグナルを監査できます。
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）。AGENTS.md に記載のとおり、compare-cli v1.x 全体で安定しています。エージェントが読み取る契約です。
• content[0] — 同じ JSON をテキストブロックとしてシリアライズしたものです。structuredContent をまだ読み取らない MCP クライアント向けです。
• content[1]（任意。呼び出し元が include_human_report: true を指定した場合）— 人間が読みやすいレポートです。

compare_with_negotiation は structuredContent.base.negotiation_resolution ∈ {"status", "per_round_agreed", "clause_status"} を追加します。これは、合意されたベーステキストの生成に使用された 3 つの解決階層のうち、どれが使われたかを示します。

エラーとドリフトの違い

実質的なドリフトは、ツール呼び出しが成功したことを意味します。 エージェントが何が違うのかを尋ね、サーバーが回答しました。exit_class によるルーティングが契約です。エラーエンベロープ（isError: true）は、I/O／引数の失敗と、明示的な前提条件の例外一つに限られます。

コード	発生条件
INPUT_NOT_FOUND	パスが見つからない、または読み取れない場合。
INPUT_MALFORMED	.docx／.pdf の形式が不正な場合。
PDF_NO_TEXT_LAYER	スキャンされた PDF で、pdfjs による抽出文字数が 0 の場合。
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	予期しないエラー。エージェントが状況を把握できるよう、根本のメッセージを表示します。

このパッケージの 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 を参照してください。