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	将输出写入文件，而非 stdout	–
--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 会将格式化结果写入文件，并向 stdout 输出 Output written to <path>。

输出格式

表格格式（默认）

使用 Unicode 框线绘制的表格。每行都会标明拥有该路径的一侧：

• (Base) <path> — 该路径存在于基础侧（值或类型变更、删除）。
• (Contrast) <path> — 该路径仅存在于对比侧（新增）。
• (Root) — 顶层值本身不同时使用。

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

两个输入完全一致时，输出如下：

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	值存在于 contrast 中，但不存在于 base 中。
deleted	值存在于 base 中，但不存在于 contrast 中。
typeChanged	base 和 contrast 之间的值类型发生变化（例如，number → string）。
valueChanged	值发生变化，但类型保持不变。

MCP 服务

@compare-json/cli 还附带一个 MCP（Model Context Protocol） 服务，可将比较引擎作为工具提供给 AI 助手。

启动 MCP 服务

# from a global install
compare-json --mcp

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

该服务通过 stdio 通信。

可用工具

compare_json

比较两个 JSON 值并返回它们的差异。

输入参数：

参数	类型	必填	描述
baseJSON	any	条件必填	基础 JSON 值（已解析）。
baseJSONString	string	条件必填	字符串化形式的基础 JSON（由服务解析）。
baseJSONFilePath	string	条件必填	基础 JSON 文件的路径（由服务读取并解析）。
contrastJSON	any	条件必填	对比 JSON 值（已解析）。
contrastJSONString	string	条件必填	字符串化形式的对比 JSON。
contrastJSONFilePath	string	条件必填	对比 JSON 文件的路径。
options	object	否	比较选项（见下文）。

必须提供 baseJSON / baseJSONString / baseJSONFilePath 中至少一个，以及 contrastJSON / contrastJSONString / contrastJSONFilePath 中至少一个。同一侧设置多个参数时，优先使用文件路径，其次是字符串，最后是原始值。

选项：

选项	类型	默认值	描述
arrayCompareMethod	'byIndex' | 'lcs' | 'unordered'	'byIndex'	数组比较策略。
keyCaseInsensitive	boolean	false	比较键时忽略大小写。
valueCaseInsensitive	boolean	false	比较值时忽略大小写。
numericStringEqualsNumber	boolean	false	将数字字符串视为与数字相等。

输出：

返回 structuredContent.differences（一个 JSONValueDifference 对象数组），以及 content[0].text 中相同数据的 JSON 文本镜像。

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