@compare-json/cli（JavaScript）

@compare-json/cli 是一个命令行工具和 MCP 服务器，用于对比 JSON 文件或字符串，基于 @compare-json/core 构建。

语言：JavaScript/TypeScript —— 运行于 Node.js，通过 npm 分发。其它语言的实现可能会陆续推出。

安装

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

# yarn
yarn global add @compare-json/cli

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

快速开始

# 查看帮助
compare-json --help

# 对比两个 JSON 字符串
compare-json '{"a":1}' '{"a":2}'

# 对比两个 JSON 文件
compare-json file1.json file2.json

# 以 JSON 格式输出
compare-json file1.json file2.json --json-export

# 将输出保存到文件
compare-json file1.json file2.json -o output.txt

# 启动 MCP 服务器（stdio 传输）
compare-json --mcp

用法

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

每个位置参数可以是内联 JSON 字符串，也可以是 JSON 文件路径。CLI 会自动判断：如果参数解析为已存在的文件，则解析文件内容；否则将参数本身作为 JSON 解析。如果 base 和 contrast 都未提供（且未设置 --mcp），则打印帮助信息。

参数

选项

示例

基础对比

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

输出：

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

数组对比方法

# 按索引（默认）
compare-json '[1,2,3]' '[2,3,4]'

# LCS —— 有序数组的最小差异
compare-json '[1,2,3]' '[2,3,4]' -a lcs

# Unordered —— 视为多重集合
compare-json '[1,2,3]' '[3,2,1]' -a unordered

每种策略的说明请参阅数组对比方法。

大小写不敏感对比

# 键名忽略大小写
compare-json '{"Name":"Alice"}' '{"name":"Alice"}' -k

# 值忽略大小写
compare-json '{"status":"OK"}' '{"status":"ok"}' -v

数字字符串对比

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

JSON 输出

compare-json file1.json file2.json -j

输出：

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

保存到文件

# 保存表格格式
compare-json file1.json file2.json -o diff.txt

# 保存 JSON 格式
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        │
└──────────────┴──────────────┘

当两个输入完全一致时，输出为：

No differences found

JSON 格式

使用 -j / --json-export 时，CLI 会打印原始的 JSONValueDifference 对象数组——完整结构请参阅 @compare-json/core。

MCP 服务器

CLI 还内置了 MCP（Model Context Protocol）服务器，将对比引擎作为工具暴露给 AI 助手：

# 全局安装后
compare-json --mcp

# 或通过 npx
npx @compare-json/cli --mcp

客户端配置和 compare_json 工具的参数说明请参阅 MCP 页面。

许可证

MIT