Compare JSON

@compare-json/cli

JSON ファイルや文字列を比較するコマンドラインツールおよびMCPサーバーです。@compare-json/coreを基盤としています。

オンラインプレイグラウンド

https://comparejson.comでお試しください。

インストール

# npm
npm install -g @compare-json/cli

# yarn
yarn global add @compare-json/cli

# pnpm
pnpm add -g @compare-json/cli

CLI

クイックスタート

# View help
compare-json --help

# Compare two JSON strings
compare-json '{"a":1}' '{"a":2}'

# Compare two JSON files
compare-json file1.json file2.json

# Output as JSON format
compare-json file1.json file2.json --json-export

# Save output to file
compare-json file1.json file2.json -o output.txt

# Start the MCP server (stdio transport)
compare-json --mcp

使い方

compare-json [base] [contrast] [options]

位置引数には、インラインのJSON文字列またはJSONファイルへのパスを指定できます。CLIは値を調べ、既存のファイルに解決される場合はファイルの内容を解析し、それ以外の場合は引数自体をJSONとして解析します。baseもcontrastも指定されていない場合（かつ--mcpが設定されていない場合）は、ヘルプが表示されます。

引数

引数	説明
[base]	ベースとなるJSON文字列またはファイルパス
[contrast]	比較対象となるJSON文字列またはファイルパス

オプション

オプション	エイリアス	説明	デフォルト
--array-compare-method <method>	-a	配列の比較方法：byIndex、lcs、unordered	byIndex
--key-case-insensitive	-k	キーを大文字と小文字を区別せずに比較します	false
--value-case-insensitive	-v	値を大文字と小文字を区別せずに比較します	false
--numeric-string-equals-number	–	数値文字列を数値として扱います	false
--json-export	-j	JSON形式で出力します	false
--output <file>	-o	標準出力の代わりにファイルへ出力します	–
--mcp	–	stdio経由でMCPサーバーとして実行します	false
--version	-V	CLIのバージョンを表示します	–
--help	-h	ヘルプを表示します	–

使用例

基本的な比較

compare-json '{"name":"Alice","age":30}' '{"name":"Bob","age":30}'

出力：

┌─────────────┬──────────────┐
│ Key         │ Change Type  │
├─────────────┼──────────────┤
│ (Base) name │ valueChanged │
└─────────────┴──────────────┘

ファイルの比較

compare-json base.json contrast.json

配列の比較方法

# By index (default)
compare-json '[1,2,3]' '[2,3,4]'

# LCS — minimal diff for ordered arrays
compare-json '[1,2,3]' '[2,3,4]' -a lcs
compare-json '[1,2,3]' '[2,3,4]' --array-compare-method lcs

# Unordered — treat as multisets
compare-json '[1,2,3]' '[3,2,1]' -a unordered
compare-json '[1,2,3]' '[3,2,1]' --array-compare-method unordered

大文字と小文字を区別しない比較

# Case-insensitive keys
compare-json '{"Name":"Alice"}' '{"name":"Alice"}' -k
compare-json '{"Name":"Alice"}' '{"name":"Alice"}' --key-case-insensitive

# Case-insensitive values
compare-json '{"status":"OK"}' '{"status":"ok"}' -v
compare-json '{"status":"OK"}' '{"status":"ok"}' --value-case-insensitive

数値文字列の比較

compare-json '{"count":1}' '{"count":"1"}' --numeric-string-equals-number

JSON出力

compare-json file1.json file2.json -j
compare-json file1.json file2.json --json-export

出力：

[
  {
    "pathSegments": ["name"],
    "pathString": "name",
    "pathBelongsTo": "both",
    "diffType": "valueChanged"
  }
]

ファイルへの保存

# Save table format
compare-json file1.json file2.json -o diff.txt

# Save JSON format
compare-json file1.json file2.json -j -o diff.json

-oが設定されている場合、CLIは整形した結果をファイルに書き込み、標準出力にOutput written to <path>と表示します。

出力形式

テーブル形式（デフォルト）

Unicodeの罫線で描画されたテーブルです。各行には、そのパスを持つ側がラベルとして付けられます。

• (Base) <path> — パスがベース側に存在します（値または型の変更、削除）。
• (Contrast) <path> — パスがコントラスト側にのみ存在します（追加）。
• (Root) — トップレベルの値自体が異なる場合に使用されます。

┌──────────────┬──────────────┐
│ Key          │ Change Type  │
├──────────────┼──────────────┤
│ (Base) a     │ valueChanged │
│ (Base) b     │ deleted      │
│ (Contrast) c │ added        │
└──────────────┴──────────────┘

2つの入力が完全に一致する場合、出力は次のとおりです。

No differences found

JSON形式

[
  {
    "pathSegments": ["name"],
    "pathString": "name",
    "pathBelongsTo": "both",
    "diffType": "valueChanged"
  },
  {
    "pathSegments": ["age"],
    "pathString": "age",
    "pathBelongsTo": "base",
    "diffType": "deleted"
  },
  {
    "pathSegments": ["email"],
    "pathString": "email",
    "pathBelongsTo": "contrast",
    "diffType": "added"
  }
]

完全な構造については、@compare-json/coreのJSONValueDifferenceを参照してください。

差分の種類

種類	説明
added	値がbaseにはなく、contrastに存在します。
deleted	値がbaseに存在し、contrastにはありません。
typeChanged	baseとcontrastの間で値の型が変わりました（例：number → string）。
valueChanged	型は同じまま、値が変わりました。

MCPサーバー

@compare-json/cliには、比較エンジンをAIアシスタント向けのツールとして提供するMCP（Model Context Protocol）サーバーも含まれています。

MCPサーバーの起動

# from a global install
compare-json --mcp

# or via npx
npx @compare-json/cli --mcp

サーバーはstdio経由で通信します。

利用可能なツール

compare_json

2 つの JSON 値を比較し、その差分を返します。

入力パラメーター：

パラメーター	型	必須	説明
baseJSON	any	条件付き	ベースとなる JSON 値（解析済み）。
baseJSONString	string	条件付き	文字列化されたベース JSON 値（サーバーが解析）。
baseJSONFilePath	string	条件付き	ベース JSON ファイルのパス（サーバーが読み込み、解析）。
contrastJSON	any	条件付き	比較対象の JSON 値（解析済み）。
contrastJSONString	string	条件付き	文字列化された比較対象の JSON 値。
contrastJSONFilePath	string	条件付き	比較対象の JSON ファイルのパス。
options	object	いいえ	比較オプション（以下を参照）。

baseJSON／baseJSONString／baseJSONFilePath のうち少なくとも 1 つと、contrastJSON／contrastJSONString／contrastJSONFilePath のうち少なくとも 1 つを指定する必要があります。同じ側で複数指定した場合は、ファイルパス、文字列、未加工の値の順に優先されます。

オプション：

オプション	型	デフォルト	説明
arrayCompareMethod	'byIndex' | 'lcs' | 'unordered'	'byIndex'	配列の比較方法。
keyCaseInsensitive	boolean	false	キーの大文字と小文字を区別せずに比較します。
valueCaseInsensitive	boolean	false	値の大文字と小文字を区別せずに比較します。
numericStringEqualsNumber	boolean	false	数値文字列を数値と等しいものとして扱います。

出力：

JSONValueDifference オブジェクトの配列である structuredContent.differences と、同じデータを JSON テキストとして表す content[0].text を返します。

{
  "differences": [
    {
      "pathSegments": ["name"],
      "pathString": "name",
      "pathBelongsTo": "both",
      "diffType": "valueChanged"
    }
  ]
}

MCP クライアントの設定

以下を MCP クライアントの設定（例：mcp.json）に追加します。

{
  "mcpServers": {
    "compare-json": {
      "command": "npx",
      "args": ["@compare-json/cli@latest", "--mcp"]
    }
  }
}

ライセンス

MIT