MCP JSON 工具

简体中文

使用强大的数据操作工具Lodash和JSONPath查询本地的JSON和NDJSON文件。 利用lodash进行数据操作，并通过jsonpath在mcp_json_eval和mcp_json_multi_eval工具中进行查询。

主要功能

• 统一格式处理：自动读取标准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）。
• 安全执行：使用Node.js vm模块在eval工具中更安全地执行代码，支持配置超时时间。
• 简单设置：作为标准Node.js进程通过npx运行。

提供的工具

1. mcp_json_query

• 操作：对本地JSON或NDJSON文件执行JSONPath查询，返回匹配值。自动读取两种格式；NDJSON被视为对象数组进行查询。
• 参数：
  • file_path (字符串)：JSON或NDJSON文件的路径。
  • json_path (字符串)：JSONPath查询。语法说明：
    • 对于标准JSON（根是对象），路径通常以$.开头（例如，$.store.book[*].author）。
    • 对于NDJSON（根是数组），路径必须以$后跟[开头（例如，$[?(@.user=='alice')].event或$[*].user）。在根数组上使用$[*][?(...)]不会按预期工作。
  • count (数字，可选)：最大结果数。
• 返回：匹配值的数组。
• 示例：获取所有书籍作者（来自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<1.0)]）。
    • 对于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')]"。（注意根数组上的$[?(...)]语法）。
  • 预期输出：包含节点对象{path: ..., value: ...}的字符串化JSON数组，对应于bob的事件。

3. mcp_json_eval

• 操作：读取JSON或NDJSON文件，在带有文件内容（$1：JSON对象或NDJSON对象数组）、lodash (_) 和 jsonpath (jp) 的沙箱虚拟机中执行JavaScript代码。如果代码的最后一表达式是{ 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执行的直接结果（如果是对象或数组，则字符串化，否则为原始值）。
  • 如果最后一表达式是更新指令：成功写入文件的消息（例如，“成功更新json文件：...”或“成功更新ndjson文件：...”）。
• ⚠️ 安全警告 ⚠️：在沙箱虚拟机中执行用户提供的代码。虽然比原始eval()更安全，但仍需审查代码以防资源耗尽或意外逻辑。仅使用可信代码。
• 示例：添加'onSale'属性（修改JSON）
  • 目标：向store.json中的每本书添加onSale: false。
  • JavaScript逻辑：

    // $1 是JSON对象
    _.forEach($1.store.book, (book) => {
      book.onSale = false;
    });
    ({ type: 'updateFile', data: $1 }); // 返回更新对象
    

  • 工具调用：调用mcp_json_eval，参数为file_path="test-data/store.json"和上述JavaScript逻辑。
  • 预期输出："成功更新json文件：test-data/store.json"
• 示例：计算平均价格（分析JSON）
  • 目标：找到store.json中便宜小说书的平均价格。
  • JavaScript逻辑：

    // $1 是JSON对象
    const books = jp.query($1, "$.store.book[?(@.category=='fiction' && @.price < 15)]");
    _.meanBy(books, 'price'); // 返回平均价格
    

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

    // $1 是NDJSON文件中的事件对象数组
    const filteredData = _.filter($1, item => item.success === true);
    // 返回带有过滤数组的更新对象
    ({ type: 'updateFile', data: filteredData });
    

  • 工具调用：调用mcp_json_eval，参数为file_path="{abspath}/mcp-json-tools/test-data/events.ndjson"和上述JS逻辑。
  • 预期输出："成功更新ndjson文件：{abspath}/mcp-json-tools/test-data/events.ndjson"

4. mcp_json_multi_eval

• 操作：读取多个JSON或NDJSON文件，在带有文件内容（$1是一个数组，每个元素是文件解析的内容——JSON对象或NDJSON对象数组）、lodash (_) 和 jsonpath (jp) 的沙箱虚拟机中执行JavaScript代码。如果代码的最后一表达式是{ 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执行的直接结果（如果是对象或数组，则字符串化，否则为原始值）。
  • 如果最后一表达式是多更新指令：列出已更新文件的成功消息（例如，“成功更新文件：...”）。
• ⚠️ 安全警告 ⚠️：在沙箱虚拟机中执行用户提供的代码。与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：

此方法要求您在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文件。