AI导哈

JSON数据处理工具

提供JSON和NDJSON文件的查询、分析和修改功能，支持Lodash和JSONPath操作，适用于本地数据处理和自动化脚本开发。

  • by zfirsty
  • JavaScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 zfirsty/mcp-json-tools

使用说明

MCP JSON工具

简体中文

通过强大的数据操作与本地JSON和NDJSON文件交互 洛达斯 并使用JSONPath进行查询。 杠杆作用 lodash 用于操纵和 jsonpath 用于查询 mcp_json_eval 和 mcp_json_multi_eval 工具。

主要特点

  • 统一格式处理：自动读取标准JSON和换行符分隔的JSON（NDJSON/JSONL）。NDJSON文件被视为对象数组。
  • 查询：使用JSON或NDJSON文件中的标准JSONPath表达式选择数据(mcp_json_query).
  • 检查：检索JSON/NDJSON结构中的两个值及其精确路径(mcp_json_nodes).
  • 分析和修改：在沙盒VM中执行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 （string）：JSON或NDJSON文件的路径。
    • json_path （string）：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）
    • 目标：从获取用户“alice”的事件类型 events.ndjson.
    • 工具调用：呼叫 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 （string）：JSON或NDJSON文件的路径。
    • json_path （string）：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）
    • 目标：从以下位置获取用户“bob”的完整事件对象（包括路径） events.ndjson.
    • 工具调用：呼叫 mcp_json_nodes 随着 file_path="{abspath}/mcp-json-tools/test-data/events.ndjson" 和 json_path="$[?(@.user=='bob')]"（注意 $[?(...)] 根数组的语法）。
    • 期望输出：包含节点对象的字符串化JSON数组 {path: ..., value: ...} 为了鲍勃的活动。

3. mcp_json_eval

  • 行动：读取JSON或NDJSON文件，在带有文件内容的沙盒VM中执行JavaScript代码($1：JSON对象，NDJSON对象数组），lodash(_)，以及jsonpath(jp).如果代码的最后一个表达式为，则返回结果或修改文件（保留原始格式：JSON或NDJSON） { type: 'updateFile', data: <new_data> }。超时30秒。
  • 参数:
    • file_path （string）：JSON或NDJSON文件的路径。
    • js_code （string）：要执行的JavaScript代码。
  • 文件修改：要触发文件写入 最后一个表达式 评估于 js_code 必须 是 ({ type: 'updateFile', data: <new_data> })The <new_data> 如果需要保留格式，则应与预期的结构（JSON的对象，NDJSON的数组）匹配。
  • 退货:
    • 如果最后一个表达式不是更新指令： js_code 执行（如果对象/数组为字符串，否则为原始值）。
    • 如果最后一个表达式是更新指令：成功写入文件时的成功消息（例如。， "Successfully updated json file: ..." 或 "Successfully updated ndjson file: ...").
  • ⚠️ 安全警告⚠️：在沙盒VM中执行用户提供的代码。虽然比生的更安全 eval()，检查代码是否存在潜在的资源耗尽或意外逻辑。使用受信任的代码。
  • 示例：添加“onSale”属性（修改JSON）
    • 目标：添加 onSale: false 每一本书 store.json.
    • JavaScript逻辑:
      // $1 is the JSON object
_.forEach($1.store.book, (book) => {
  book.onSale = false;
});
({ type: 'updateFile', data: $1 }); // Return update object
    • 工具调用：呼叫 mcp_json_eval 随着 file_path="test-data/store.json" 上面的JavaScript逻辑 js_code 参数。
    • 期望输出: "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 随着 file_path="test-data/store.json" 上面的JavaScript逻辑 js_code 参数。
    • 期望输出: 10.99
  • 示例：过滤失败事件（修改NDJSON）
    • 目标：删除以下事件 success 是 false 从 test-data/events.ndjson 并更新文件。
    • 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 （string）：要执行的JavaScript代码。
  • 文件修改：要触发文件写入 最后一个表达式 评估于 js_code 必须 是 ({ type: 'updateMultipleFiles', updates: [{ index: <file_index>, data: <newData> }, ...] }).只有与输入中的有效索引对应的文件 file_paths 可以更新。这 <newData> 应与该索引处文件的原始格式匹配。
  • 退货:
    • 如果最后一个表达式不是多重更新指令： js_code 执行（如果对象/数组为字符串，否则为原始值）。
    • 如果最后一个表达式是多更新指令：一条列出更新文件的成功消息（例如。， "Successfully updated files: ...").
  • ⚠️ 安全警告⚠️：在沙盒VM中执行用户提供的代码。安全考虑因素与 mcp_json_eval 申请。

配置

配置您的客户端（游标、VS代码）以使用以下命令运行服务器 npx这避免了需要绝对路径 服务器命令本身.

使用NPX（推荐）：

  • 关于文件路径的重要说明：使用NPX方法时 file_path 或 file_paths 提供给工具 必须是绝对路径。由于以下原因，相对路径可能无法正确解析 npx 执行命令。

  • 光标(.cursor/mcp.json):

    {
  "mcpServers": {
    "jsonTools": {
      "description": "Tools to query, inspect, and modify local JSON and NDJSON files.",
      "command": "npx",
      "args": [ "mcp-json-tools" ] 
    }
  }
}

  • VS代码(.vscode/mcp.json 或用户设置）：

    {
  "jsonTools": {
    "description": "Tools to query, inspect, and modify local JSON and NDJSON files.",
    "command": "npx",
    "args": [ "mcp-json-tools" ] 
  }
}

替代方案：直接使用Node：

此方法要求您指定 绝对路径 到 mcp-json-tools/index.js 文件内 args 数组在你的 mcp.json 配置（例如。， "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文件。

相关 MCP