Gojq MCP

🚀 gojq-mcp

gojq-mcpは、gojqライブラリを介してjq構文を使用する、MCP（Model Context Protocol）サーバーとして動作することも、スタンドアロンのCLI実行可能ファイルとして動作することもできるデュアルモードのJSONクエリツールです。

✨ 主な機能

• 🔍 jqクエリの実行：jq構文を完全にサポートし、JSONファイルに対してjqクエリを実行できます。
• ✅ 包括的な検証：ファイルの存在、読み取り可能性、およびJSONの有効性を検証します。
• 🔄 デュアルモード動作：MCPサーバーまたはCLIツールとして実行できます。
• 🧪 十分にテストされている：コアクエリエンジンには14の包括的なテストケースがあります。
• 📦 ゼロコンフィギュレーション：すぐに使用できます。

📚 目次

• インストール
• 使い方
  • MCPサーバーモード
  • CLIモード（近日公開）
• アーキテクチャ
• MCPツールインターフェイス
• 開発
• リリースとデプロイメント
• テスト
• サンプル
• ベストプラクティス
• コントリビュート
• ライセンス

📦 インストール

ソースからのインストール

# リポジトリをクローンする
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

💻 使い方

MCPサーバーモード

デフォルトモードでは、stdioトランスポートを使用して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'

🔧 アーキテクチャ

プロジェクト構造

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/                  # ビルド出力 (gitignored)
    └── 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（Intel）、arm64（Apple Silicon）
• 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. リリースページにアクセスする
2. 目的のバージョンを見つける
3. 自分のプラットフォームに適したバイナリをダウンロードする
4. 実行可能にする（Linux/macOS）：chmod +x gojq-mcp-*

バージョンの命名

セマンティックバージョニングに従います。

• メジャーバージョン (v2.0.0)：破壊的な変更
• マイナーバージョン (v1.1.0)：新機能、下位互換性あり
• パッチバージョン (v1.0.1)：バグ修正、下位互換性あり
• プレリリース (v1.0.0-beta, v1.0.0-alpha.1)：テスト用バージョン

継続的インテグレーション

このプロジェクトには、2つの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 ✅ エラーハンドリング：無効なフィルター、存在しないキー ✅ エッジケース：空の配列、アイデンティティフィルター、null値 ✅ 複雑なシナリオ：ネストされたデータ構造、複数の結果

テストファイル：

• main_test.go：コアのexecuteJQ関数のテスト
• tests/testdata/：テストデータ（有効、無効、ネストされたJSON）

💡 サンプル

基本的なクエリ

# 単一のフィールドを取得する
.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

サンプルデータ

完全なサンプルデータセットについては、examples/sample.jsonを参照してください。

📝 ベストプラクティス

MCPサーバー開発のためのベストプラクティス

1. json_file_pathを指定する際には、常に絶対パスを使用してください。
2. 入力を早期に検証してください：ツールは処理する前にファイルを検証します。
3. エラーを適切に処理してください：ツールからのエラーレスポンスをチェックしてください。
4. クエリを段階的にテストしてください：簡単なクエリから始めて、複雑さを増やしてください。
5. アイデンティティフィルター（.）を使用して、まずデータ構造を調べてください。

jqクエリのためのベストプラクティス

1. 簡単なクエリから始めてください：.を使用して完全な構造を確認してください。
2. keysを使用して、利用可能なフィールドを見つけてください。
3. パイプ操作を使用して、複雑なクエリを作成してください：|でチェーンします。
4. select()を使用して、配列を適切にフィルターしてください。
5. type関数を使用して、データ型を確認してください。

統合のためのベストプラクティス

1. 設定を変更した後は、MCPクライアントを再起動してください。
2. MCPサーバーの設定では、絶対パスを使用してください。
3. サーバーがMCPクライアントに表示されない場合は、ログを確認してください。
4. デプロイする前に、go run .で手動でテストしてください。
5. go get -uとgo mod tidyを使用して、依存関係を最新の状態に保ってください。

📦 依存関係

• gojq - jqの純粋なGo実装
• mcp-go - Model Context Protocolサーバーフレームワーク

👥 コントリビュート

コントリビューションは大歓迎です！ 以下の手順に従ってください。

1. リポジトリをフォークする
2. 機能ブランチを作成する (git checkout -b feature/amazing-feature)
3. 変更をコミットする (git commit -m 'Add amazing feature')
4. ブランチにプッシュする (git push origin feature/amazing-feature)
5. プルリクエストを作成する

開発ガイドライン

• 新機能に対してテストを書いてください。
• Goの規約に従い、go fmtを実行してください。
• APIの変更に対してドキュメントを更新してください。
• コミットを集中的かつアトミックに保ってください。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています - 詳細についてはLICENSEファイルを参照してください。

📚 リソース

• jqマニュアル - 完全なjq構文リファレンス
• MCPドキュメント - Model Context Protocol仕様
• gojqドキュメント - gojqライブラリの詳細