STARWARCLOUD STARWAR.AI
返回市场
麦普-极速

麦普-极速

作者：247arjun3 星标更新：2025-07-27
安装使用来源：spider==github.com

项目介绍

MCP Server for JQ

npm 版本 npm 下载量

这是一个提供围绕 jq 命令行工具的封装的模型上下文协议（MCP）服务器，用于查询和操作 JSON 数据。

功能

  • JSON 查询：使用 jq 语法查询 JSON 文件和数据
  • 数据格式化：解析和格式化 JSON 数据
  • 复杂操作：支持复杂的 jq 过滤器和操作
  • 文件处理：对大型 JSON 文件进行流式处理
  • 验证：JSON 验证和键提取
  • 安全性：带有输入验证的安全子进程执行

先决条件

  • Node.js 18 或更高版本
  • 在您的系统上安装 jq 命令行工具

安装 jq

macOS:

brew install jq

Ubuntu/Debian:

sudo apt-get install jq

Windows: 从 https://jqlang.github.io/jq/download/ 下载

安装

方法 1：NPM 安装（推荐）

# 全局安装
npm install -g @247arjun/mcp-jq

# 或者在项目中本地安装
npm install @247arjun/mcp-jq

方法 2：从源代码安装

# 克隆仓库
git clone https://github.com/247arjun/mcp-jq.git
cd mcp-jq

# 安装依赖
npm install

# 构建项目
npm run build

# 可选：全局链接
npm link

方法 3：直接从 GitHub 安装

# 直接从 GitHub 安装
npm install -g git+https://github.com/247arjun/mcp-jq.git

配置

Claude Desktop 设置

添加到您的 Claude Desktop 配置文件：

位置：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%/Claude/claude_desktop_config.json

配置：

{
  "mcpServers": {
    "mcp-jq": {
      "command": "mcp-jq",
      "args": []
    }
  }
}

替代方案：使用 npx（无需全局安装）

{
  "mcpServers": {
    "mcp-jq": {
      "command": "npx",
      "args": ["@247arjun/mcp-jq"]
    }
  }
}

本地开发设置

{
  "mcpServers": {
    "mcp-jq": {
      "command": "node",
      "args": ["/绝对路径/to/mcp-jq/build/index.js"]
    }
  }
}

添加配置后，请重启 Claude Desktop 以加载 MCP 服务器。

可用工具

1. jq_query

使用 jq 语法查询 JSON 数据。

参数：

  • json_data (字符串)：要查询的 JSON 数据
  • filter (字符串)：jq 过滤表达式
  • raw_output (布尔值，可选)：返回原始输出而不是 JSON (默认: false)

示例：

{
  "json_data": "{\"users\": [{\"name\": \"John\", \"age\":  30}]}",
  "filter": ".users[0].name"
}

2. jq_query_file

使用 jq 语法查询 JSON 文件。

参数：

  • file_path (字符串)：JSON 文件路径
  • filter (字符串)：jq 过滤表达式
  • raw_output (布尔值，可选)：返回原始输出而不是 JSON (默认: false)

示例：

{
  "file_path": "./data/users.json",
  "filter": ".users | length"
}

3. jq_format

格式化和美化 JSON 数据。

参数：

  • json_data (字符串)：要格式化的 JSON 数据

示例：

{
  "json_data": "{\"name\":\"John\",\"age\":30}"
}

4. jq_validate

验证字符串是否为有效的 JSON。

参数：

  • json_data (字符串)：要验证的 JSON 数据

示例：

{
  "json_data": "{\"name\": \"John\", \"age\": 30}"
}

5. jq_keys

从 JSON 对象或对象数组中获取所有键。

参数：

  • json_data (字符串)：要提取键的 JSON 数据
  • recursive (布尔值，可选)：递归获取键 (默认: false)

示例：

{
  "json_data": "{\"user\": {\"name\": \"John\", \"details\": {\"age\": 30}}}",
  "recursive": true
}

使用示例

从 JSON 中查询用户名

{
  "tool": "jq_query",
  "json_data": "{\"users\": [{\"name\": \"John\"}, {\"name\": \"Jane\"}]}",
  "filter": ".users[].name"
}

格式化 JSON 数据

{
  "tool": "jq_format",
  "json_data": "{\"name\":\"John\",\"age\":30,\"city\":\"NYC\"}"
}

查询 JSON 文件

{
  "tool": "jq_query_file",
  "file_path": "./data/config.json",
  "filter": ".database.host"
}

开发

构建和运行

# 开发模式自动重建
npm run dev

# 生产构建
npm run build

# 启动服务器
npm start

测试

# 运行测试
npm test

项目结构

mcp-jq/
├── src/
│   └── index.ts          # 主服务器实现
├── build/                # 编译后的 JavaScript (构建后)
├── examples/             # 测试用的样本 JSON 文件
│   ├── users.json
│   └── company.json
├── package.json          # 项目依赖和脚本
├── tsconfig.json         # TypeScript 配置
├── install.sh           # 安装脚本
├── test.js              # 测试脚本
└── README.md            # 本文档

验证

测试服务器是否正常工作：

# 测试已构建的服务器
node build/index.js

# 应显示: "JQ MCP Server running on stdio"
# 按 Ctrl+C 退出

故障排除

常见问题

  1. "命令未找到" 错误

    • 确保 mcp-jq 已全局安装：npm install -g @247arjun/mcp-jq
    • 或使用 npx："command": "npx", "args": ["@247arjun/mcp-jq"]

  2. "权限被拒绝" 错误

    • 检查文件权限：chmod +x build/index.js
    • 重新构建项目：npm run build

  3. MCP 服务器未出现在 Claude 中

    • 验证配置文件中的 JSON 语法
    • 完全重启 Claude Desktop
    • 检查命令路径是否正确

  4. "jq 命令未找到"

    • 使用上述说明在您的系统上安装 jq
    • 验证安装：jq --version

调试

通过设置环境变量启用详细日志记录：

# 开发模式
DEBUG=1 node build/index.js

# 使用示例输入测试
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {}}' | node build/index.js

安全注意事项

  • 使用 spawn 而不是 shell 执行安全子进程
  • 对所有 jq 命令和文件路径进行输入验证
  • 不执行任意 shell 命令
  • 对文件操作进行路径验证和清理
  • 使用 Zod 模式进行输入验证