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 庫詳情