MCP JSON Tools

MCP JSON Tools

简体中文

通过 Lodash 强大的数据处理功能和 JSONPath 查询，与本地 JSON 和 NDJSON 文件交互。 在 mcp_json_eval 和 mcp_json_multi_eval 工具中，使用 lodash 进行数据处理，并使用 jsonpath 执行查询。

主要功能

• 统一格式处理：自动读取标准 JSON 和按行分隔的 JSON（NDJSON/JSONL）。NDJSON 文件会被视为对象数组。
• 查询：使用标准 JSONPath 表达式，从 JSON 或 NDJSON 文件中选择数据（mcp_json_query）。
• 检查：获取 JSON/NDJSON 结构中的值及其精确路径（mcp_json_nodes）。
• 分析与修改：在沙箱虚拟机中执行 JavaScript（提供 Lodash _ 和 JSONPath jp），以便对 JSON/NDJSON 文件进行复杂分析或修改（mcp_json_eval、mcp_json_multi_eval）。修改后会保留原始文件格式（JSON 或 NDJSON）。
• 安全执行：在 eval 工具中使用 Node.js vm 模块安全地执行代码，并支持配置超时时间。
• 简单设置：通过 npx 以标准 Node.js 进程运行。

提供的工具

1. mcp_json_query

• 操作：对本地 JSON 或 NDJSON 文件执行 JSONPath 查询，并返回匹配的值。自动读取这两种格式；查询时会将 NDJSON 视为对象数组。
• 参数：
  • file_path（string）：JSON 或 NDJSON 文件的路径。
  • json_path（string）：JSONPath 查询。语法说明：
    • 对于标准 JSON（根节点为对象），路径通常以 $. 开头（例如 $.store.book[*].author）。
    • 对于 NDJSON（根节点为数组），路径必须以 $ 后跟 [ 开头（例如 $[?(@.user=='alice')].event 或 $[*].user）。对根数组使用 $[*][?(...)] 不会得到预期结果。
  • count（number，可选）：结果数量上限。
• 返回值：匹配值数组。
• 示例：获取所有图书作者（来自 JSON）
  • 目标：从 store.json 获取所有作者的姓名。
  • 工具调用：调用 mcp_json_query，并设置 file_path="test-data/store.json" 和 json_path="$.store.book[*].author"。
  • 预期输出：["Nigel Rees", "Evelyn Waugh", "Herman Melville", "J. R. R. Tolkien"]
• 示例：获取用户 'alice' 的事件类型（来自 NDJSON）
  • 目标：从 events.ndjson 获取用户 'alice' 的事件类型。
  • 工具调用：调用 mcp_json_query，并设置 file_path="{abspath}/mcp-json-tools/test-data/events.ndjson" 和 json_path="$[?(@.user=='alice')].event"。（请注意，根数组使用 $[?(...)] 语法。）
  • 预期输出：["login", "login", "view_item"]（以字符串形式表示的数组）

2. mcp_json_nodes

• 操作：对本地 JSON 或 NDJSON 文件执行 JSONPath 查询，并返回匹配的节点（值 + 路径）。自动读取两种格式；查询时会将 NDJSON 视为对象数组。
• 参数：
  • file_path（字符串）：JSON 或 NDJSON 文件的路径。
  • json_path（字符串）：JSONPath 查询。语法说明：
    • 对于标准 JSON（根节点是对象），路径通常以 $. 开头（例如，$.store.book[?(@.price<10)]）。
    • 对于 NDJSON（根节点是数组），路径必须以 $ 后接 [ 开头（例如，$[?(@.user=='bob')] 或 $[*]）。在根数组上使用 $[*][?(...)] 不会按预期工作。
  • count（数字，可选）：结果数上限。
• 返回值：对象数组 { path: Array<string|number>, value: any }。
• 示例：获取作者及其路径（来自 JSON）
  • 目标：从 store.json 中获取作者及其位置。
  • 工具调用：调用 mcp_json_nodes，传入 file_path="test-data/store.json" 和 json_path="$.store.book[*].author"。
  • 预期输出（简化）：[ { path: ['$', 'store', 'book', 0, 'author'], value: 'Nigel Rees' }, ... ]
• 示例：获取用户 'bob' 的完整事件对象（来自 NDJSON）
  • 目标：从 events.ndjson 中获取用户 "bob" 的完整事件对象（包括路径）。
  • 工具调用：调用 mcp_json_nodes，传入 file_path="{abspath}/mcp-json-tools/test-data/events.ndjson" 和 json_path="$[?(@.user=='bob')]"。（注意根数组使用 $[?(...)] 语法。）
  • 预期输出：字符串化的 JSON 数组，其中包含 bob 的事件节点对象 {path: ..., value: ...}。

3. mcp_json_eval

• 操作：读取 JSON 或 NDJSON 文件，在沙盒 VM 中执行 JavaScript 代码，并提供文件内容（$1：JSON 对象或 NDJSON 对象数组）、lodash（_）和 jsonpath（jp）。返回结果，或者在代码的最后一个表达式为 { type: 'updateFile', data: <new_data> } 时修改文件（保留原始格式：JSON 或 NDJSON）。超时时间为 30 秒。
• 参数：
  • file_path（字符串）：JSON 或 NDJSON 文件的路径。
  • js_code（字符串）：要执行的 JavaScript 代码。
• 文件修改：要触发文件写入，js_code 求值的最后一个表达式 必须是 ({ type: 'updateFile', data: <new_data> })。如果希望保留文件格式，<new_data> 应符合预期结构（JSON 对象或 NDJSON 数组）。
• 返回值：
  • 如果最后一个表达式不是更新指令：返回 js_code 执行的直接结果（对象或数组会转换为字符串，否则返回原始值）。
  • 如果最后一个表达式是更新指令：文件成功写入后返回成功消息（例如 "Successfully updated json file: ..." 或 "Successfully updated ndjson file: ..."）。
• ⚠️ 安全警告 ⚠️：会在沙盒 VM 中执行用户提供的代码。虽然比原始 eval() 更安全，但仍需检查代码是否可能导致资源耗尽或意外逻辑。请仅使用可信代码。
• 示例：添加 onSale 属性（修改 JSON）
  • 目标：为 store.json 中的每本书添加 onSale: false。
  • JavaScript 逻辑：

    // $1 is the JSON object
    _.forEach($1.store.book, (book) => {
      book.onSale = false;
    });
    ({ type: 'updateFile', data: $1 }); // Return update object
    

  • 工具调用：调用 mcp_json_eval，并在 js_code 参数中传入 file_path="test-data/store.json" 和上述 JavaScript 逻辑。
  • 预期输出："Successfully updated json file: test-data/store.json"
• 示例：计算平均价格（分析 JSON）
  • 目标：查找 store.json 中价格低廉的小说类书籍的平均价格。
  • JavaScript 逻辑：

    // $1 is the JSON object
    const books = jp.query($1, "$.store.book[?(@.category=='fiction' && @.price < 15)]");
    _.meanBy(books, 'price'); // Return the average price
    

  • 工具调用：调用 mcp_json_eval，并在 js_code 参数中传入 file_path="test-data/store.json" 和上述 JavaScript 逻辑。
  • 预期输出：10.99
• 示例：筛除失败事件（修改 NDJSON）
  • 目标：从 test-data/events.ndjson 中移除 success 为 false 的事件并更新文件。
  • JavaScript 逻辑：

    // $1 is the array of event objects from the NDJSON file
    const filteredData = _.filter($1, item => item.success === true);
    // Return the update object with the filtered array
    ({ type: 'updateFile', data: filteredData }); 
    

  • 工具调用：调用 mcp_json_eval，并传入 file_path="{abspath}/mcp-json-tools/test-data/events.ndjson" 和 JS 逻辑。
  • 预期输出："Successfully updated ndjson file: {abspath}/mcp-json-tools/test-data/events.ndjson"

4. mcp_json_multi_eval

• 操作：读取多个 JSON 或 NDJSON 文件，在沙箱 VM 中执行 JS 代码。代码可访问文件内容（$1 是一个数组，其中每个元素都是一个文件解析后的内容——JSON 文件对应对象，NDJSON 文件对应数组）、lodash（_）和 jsonpath（jp）。返回结果，或者在代码的最后一个表达式为 { type: 'updateMultipleFiles', updates: [{ index: <file_index>, data: <newData> }, ...] } 时修改文件（保留原始格式）。超时时间为 30 秒。
• 参数：
  • file_paths（字符串数组）：JSON 或 NDJSON 文件的路径。
  • js_code（字符串）：要执行的 JavaScript 代码。
• 文件修改：要触发文件写入，js_code 中求值的最后一个表达式必须是 ({ type: 'updateMultipleFiles', updates: [{ index: <file_index>, data: <newData> }, ...] })。只能更新输入 file_paths 中索引有效的文件。<newData> 应与该索引处文件的原始格式一致。
• 返回值：
  • 如果最后一个表达式不是多文件更新指令：返回 js_code 执行的直接结果（对象或数组会转换为字符串，否则返回原始值）。
  • 如果最后一个表达式是多文件更新指令：返回列出已更新文件的成功消息（例如，"Successfully updated files: ..."）。
• ⚠️ 安全警告 ⚠️：在沙箱 VM 中执行用户提供的代码。安全注意事项与 mcp_json_eval 相同。

配置

配置客户端（Cursor、VS Code），使用 npx 运行服务。这样就无需为服务命令本身指定绝对路径。

使用 NPX（推荐）：

• 重要提示：文件路径：使用 NPX 方式时，传递给工具的 file_path 或 file_paths 必须是绝对路径。由于 npx 执行命令的方式，可能无法正确解析相对路径。

• Cursor（.cursor/mcp.json）：

  {
    "mcpServers": {
      "jsonTools": {
        "description": "查询、检查和修改本地 JSON 和 NDJSON 文件的工具。",
        "command": "npx",
        "args": [ "mcp-json-tools" ] 
      }
    }
  }
  

• VS Code（.vscode/mcp.json 或用户设置）：

  {
    "jsonTools": {
      "description": "查询、检查和修改本地 JSON 和 NDJSON 文件的工具。",
      "command": "npx",
      "args": [ "mcp-json-tools" ] 
    }
  }
  

替代方案：直接使用 Node：

此方法要求你在 mcp.json 配置的 args 数组中指定 mcp-json-tools/index.js 文件的绝对路径（例如，"command": "node", "args": [ "/abs/path/to/mcp-json-tools/index.js" ]）。与 NPX 方式相比，此方法的可移植性较差。

要使用此方法，你需要先在本地获取代码：

1. 需要安装 Node.js（推荐使用 18 或更高版本）。
2. 克隆仓库：git clone https://github.com/zfirsty/mcp-json-tools.git
3. 进入目录：cd mcp-json-tools
4. 安装依赖：npm install（安装 @modelcontextprotocol/sdk、jsonpath、lodash、zod）。 然后，配置客户端使用克隆所得 index.js 文件的绝对路径。

许可证

MIT 许可证。详情请参阅 LICENSE 文件。