Gojq MCP

🚀 gojq - mcp

gojq - mcp 是一款双模式 JSON 查询工具，它既可以作为 MCP（模型上下文协议）服务器 运行，也能作为独立的 CLI 可执行程序，借助 gojq 库使用 jq 语法进行操作。该工具支持完整的 jq 语法，可对 JSON 文件执行查询，还具备全面的验证功能，能有效确保数据的准确性和可用性。

🚀 快速开始

gojq - mcp 有两种运行模式，分别是 MCP 服务器模式和 CLI 模式（即将推出）。以下是不同模式的启动方法：

MCP 服务器模式

默认情况下，该工具以 MCP 服务器模式运行，使用标准输入输出传输，非常适合与像 Claude Desktop 这样的 MCP 客户端集成。

./dist/gojq - mcp

在 Claude Desktop 中进行配置（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
    "mcpServers": {
        "gojq": {
            "command": "/absolute/path/to/dist/gojq - mcp",
            "args": []
        }
    }
}

若要与其他 MCP 客户端配合使用：

{
    "mcpServers": {
        "gojq": {
            "command": "/absolute/path/to/dist/gojq - mcp",
            "transport": "stdio"
        }
    }
}

CLI 模式（即将推出）

未来版本计划支持直接在命令行执行操作：

# 建议用法
./gojq - mcp - file data.json - query '.users[] | select(.age > 30)'

# 短标志
./gojq - mcp - f data.json - q '.[] | .name'

✨ 主要特性

• 🔍 支持完整 jq 语法：可对 JSON 文件执行 jq 查询。
• ✅ 全面验证机制：对文件的存在性、可读性以及 JSON 的有效性进行验证。
• 🔄 双模式运行：既可以作为 MCP 服务器运行，也能作为 CLI 工具使用。
• 🧪 完善的测试用例：核心查询引擎拥有 14 个全面的测试用例。
• 📦 零配置使用：无需复杂配置，开箱即用。

📦 安装指南

从源代码安装

# 克隆仓库
git clone https://github.com/berrydev - ai/gojq - mcp.git
cd gojq - mcp

# 构建二进制文件
make build
# 或者
go build - o dist/gojq - mcp .

使用 Go Install 安装

go install github.com/berrydev - ai/gojq - mcp@latest

💻 使用示例

基础查询

# 获取单个字段
.name

# 访问嵌套字段
.user.address.city

# 数组访问
.users[0].name

数组操作

# 遍历数组
.users[] | .name

# 过滤数组
.users[] | select(.age > 30)

# 转换为新数组
[.users[] | .email]

高级查询

# 多个过滤器
.users[] | select(.age > 25) | select(.active == true) | .name

# 使用内置函数
.users | length

# 获取对象键
keys

# 类型检查
.age | type

📚 详细文档

项目架构

项目结构

gojq - mcp/
├── main.go                 # 应用程序入口点和 MCP 服务器设置
├── main_test.go           # executeJQ 的全面测试
├── go.mod                 # Go 模块定义
├── go.sum                 # 依赖项校验和
├── README.md              # 本文件
├── LICENSE                # MIT 许可证
├── CLAUDE.md              # AI 助手指南
├── Makefile               # 构建自动化
├── examples/              # 示例 JSON 文件
│   └── sample.json
├── tests/                 # 测试基础设施
│   ├── main_test.go       # （未来测试的存根）
│   └── testdata/          # 测试数据
│       ├── valid.json
│       ├── invalid.json
│       └── nested.json
└── dist/                  # 构建输出（git 忽略）
    └── gojq - mcp

核心组件

executeJQ(jqFilter string, jsonData interface{}) (string, error)

该函数是应用程序的核心，使用 gojq 解析并执行 jq 过滤器。

• 特性：
  • 解析 jq 过滤器语法。
  • 对解析后的 JSON 数据执行查询。
  • 直接返回单个结果，多个结果以数组形式返回。
  • 能优雅地处理错误，并提供详细的错误信息。
• 位置：main.go:15 - 54

main()

初始化 MCP 服务器并注册 run_jq 工具。

• 验证顺序：
  1. 检查文件是否存在。
  2. 验证文件是否可读。
  3. 验证 JSON 的有效性。
  4. 执行 jq 过滤器。
• 位置：main.go:56 - 130

MCP 工具接口

工具：run_jq

使用 jq 过滤器语法查询 JSON 文件。

• 成功：包含查询结果的 JSON 格式字符串。
• 错误：描述性错误信息。 示例请求：

{
    "jq_filter": ".users[] | select(.age > 30)",
    "json_file_path": "/absolute/path/to/data.json"
}

示例响应：

{
    "name": "Bob",
    "age": 35,
    "email": "bob@example.com"
}

错误处理

该工具针对以下情况提供详细的错误信息：

• 文件未找到："file does not exist: /path/to/file.json"
• 路径为目录而非文件："path is a directory, not a file: /path/to/dir"
• 权限被拒绝："file is not readable: permission denied"
• 无效的 JSON："file does not contain valid JSON: invalid character..."
• 无效的 jq 过滤器："invalid jq filter: unexpected token..."
• 查询执行错误："jq execution error: ..."

开发相关

前提条件

• Go 1.21 或更高版本。
• Make（可选，用于使用 Makefile 命令）。

构建

# 使用 Makefile
make build

# 直接使用 go
go build - o dist/gojq - mcp .

运行

# MCP 服务器模式（默认）
make run - server
# 或者
./dist/gojq - mcp

# CLI 模式（实现后）
make run - cli

清理

make clean

发布与部署

创建发布版本

该项目使用 GitHub Actions 来自动构建并发布多平台版本，当你推送版本标签时会触发此操作。 创建发布版本的步骤：

1. 提交更改：

git add .
git commit - m "Prepare release v1.0.0"
git push origin main

2. 创建并推送版本标签：

# 创建遵循语义化版本控制的标签
git tag v1.0.0

# 推送标签以触发构建工作流
git push origin v1.0.0

3. 等待构建完成：GitHub Actions 会自动执行以下操作：

• 为所有支持的平台构建二进制文件。
• 使用标签创建 GitHub 发布版本。
• 将所有二进制文件附加到发布版本中。
• 从提交历史记录中生成发布说明。

支持的平台

每个发布版本都包含以下平台的二进制文件：

• Linux：amd64、arm64
• macOS：amd64（英特尔）、arm64（苹果硅芯片）
• Windows：amd64

二进制文件命名约定

二进制文件命名格式为：gojq - mcp - {version} - {os} - {arch} 例如，版本 v1.0.0 会生成以下文件：

• gojq - mcp - v1.0.0 - linux - amd64
• gojq - mcp - v1.0.0 - linux - arm64
• gojq - mcp - v1.0.0 - darwin - amd64
• gojq - mcp - v1.0.0 - darwin - arm64
• gojq - mcp - v1.0.0 - windows - amd64.exe

下载发布版本

1. 访问 [发布页面](https://github.com/berrydev - ai/gojq - mcp/releases)。
2. 找到你需要的版本。
3. 下载适合你平台的二进制文件。
4. （Linux/macOS）设置可执行权限：chmod +x gojq - mcp - *

版本命名

遵循 语义化版本控制：

• 主版本（v2.0.0）：包含重大更改。
• 次版本（v1.1.0）：添加新特性，向后兼容。
• 补丁版本（v1.0.1）：修复 bug，向后兼容。
• 预发布版本（v1.0.0 - beta、v1.0.0 - alpha.1）：用于测试。

持续集成

该项目包含两个 GitHub Actions 工作流：

• 测试工作流（.github/workflows/test.yml）：
  • 在推送到 main/master 分支和拉取请求时运行。
  • 在 Go 1.24 和 1.25（所有当前支持的版本）上进行测试。
  • 确保在支持的 Go 版本之间的兼容性。
• 构建工作流（.github/workflows/build.yml）：
  • 仅在版本标签（例如：v*）触发。
  • 为所有支持的平台构建。
  • 创建附带二进制文件的 GitHub 发布版本。
  • 所有构建使用 Go 1.25。

测试

该项目为核心 executeJQ 函数提供了全面的测试。

运行测试

# 运行所有测试
make test

# 详细输出运行
go test - v ./...

# 运行特定测试
go test - v - run TestExecuteJQ_SimpleQuery

测试覆盖范围

14 个测试用例涵盖以下方面： ✅ 基本查询：.name、.age、嵌套访问 ✅ 数组操作：访问、映射、过滤 ✅ 高级过滤器：select()、管道操作 ✅ 内置函数：keys、length、type ✅ 错误处理：无效过滤器、不存在的键 ✅ 边缘情况：空数组、恒等过滤器、空值 ✅ 复杂场景：嵌套数据结构、多个结果 测试文件：

• main_test.go：核心 executeJQ 函数测试
• tests/testdata/：测试数据（有效、无效、嵌套 JSON）

🔧 技术细节

依赖项

• gojq - jq 的纯 Go 实现
• [mcp - go](https://github.com/mark3labs/mcp - go) - 模型上下文协议服务器框架

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

最佳实践

MCP 服务器开发

1. 指定 json_file_path 时始终使用绝对路径。
2. 尽早验证输入：工具在处理文件前会进行验证。
3. 优雅处理错误：检查工具的错误响应。
4. 逐步测试查询：从简单查询开始，逐步增加复杂度。
5. 使用恒等过滤器（.）先检查数据结构。

jq 查询

1. 从简单开始：使用 . 测试以查看完整结构。
2. 使用 keys：使用 keys 函数发现可用字段。
3. 管道操作：通过 | 链式操作构建复杂查询。
4. 谨慎选择：使用 select() 过滤数组。
5. 检查类型：使用 type 函数验证数据类型。

集成

1. 配置更改后重启 MCP 客户端。
2. 在 MCP 服务器配置中使用绝对路径。
3. 如果服务器未在 MCP 客户端中显示，检查日志。
4. 部署前使用 go run . 手动测试。
5. 使用 go get - u 和 go mod tidy 保持依赖项更新。

资源

• jq 手册 - 完整的 jq 语法参考
• MCP 文档 - 模型上下文协议规范
• gojq 文档 - gojq 库详情