OpenGrok MCP Server

OpenGrok MCP Server

OpenGrok でインデックス化されたあらゆるコードベースを対象とするコードインテリジェンス — 検索、読み取り、blame、シンボルナビゲーション、差分、コミット履歴、コールグラフ、依存関係マップ、ガイド付き調査に対応します。Code Mode と AST を考慮したコード読み取りにより、トークン効率を最適化しています。

クイックスタート

オプション 1 — VS Code 拡張機能

VS Code Marketplace から OpenGrok MCP をインストールするか、拡張機能パネルで「OpenGrok」を検索してください。初回起動時に設定パネルが開きます。OpenGrok のエンドポイント、ユーザー名、パスワードを入力し、Save Settings をクリックして、プロンプトが表示されたら再読み込みしてください。

この拡張機能はビジュアルな設定 UI を提供し、MCP サーバーのプロセスを自動的に管理します。Python、外部の Node.js のインストール、手動での環境設定は不要です。

オプション 2 — npm / npx CLI

npm install -g opengrok-mcp-server
opengrok-mcp setup      # interactive wizard: URL, credentials, MCP client registration

インストールせずに実行するには、次のコマンドを使用します。

npx opengrok-mcp-server setup

その他の CLI コマンド：

opengrok-mcp status      # health check: validates connectivity and detects installed MCP clients
opengrok-mcp setup --test                     # test the stored connection without the wizard
opengrok-mcp setup --set contextBudget=generous  # update one stored setting non-interactively
opengrok-mcp export-audit --format json --output audit.jsonl  # export the audit log
opengrok-mcp version     # print version and exit
opengrok-mcp help        # show all commands

あらゆる MCP 対応クライアント（CLI または IDE）で動作します。設定形式とトラブルシューティングについては、MCP_CLIENTS.md をご覧ください。

認証情報は OS のキーチェーン（macOS Keychain、Windows Credential Manager、Linux libsecret）に保存されます。ヘッドレス環境では、AES-256-GCM で暗号化されたファイルが代わりに使用されます。

ヒント

自動更新 — 拡張機能は 24 時間に 1 回 GitHub で新しいリリースを確認し、利用可能な場合は通知します。オンデマンドで確認するには、OpenGrok: Check for Updates を使用してください。

問題

大規模なコードベースを扱うエンジニアは、AI コーディングアシスタントを使う際に特有のギャップに直面します。モデルのコンテキストウィンドウに含まれるのは、現在開いているファイル、会話、手動で共有された情報です。しかし、本番環境のコードベースには、構造、履歴、モジュール間の関係があり、それらはすべてそのウィンドウの外に存在しています。

あるモジュールで定義され、ほかの 70 のモジュールから呼び出されるシンボル。動作を理解するには、その関数を形作った 3 つのコミットを確認する必要がある関数。十数個のディレクトリにまたがるインクルードチェーン。リファクタリングの前に、どのコンポーネントがサービスに依存しているかを示すコールグラフ。

コードインデックスにアクセスできないと、モデルは推測でこうしたギャップを埋めます。ファイルパスを捏造し、関数シグネチャをでっち上げ、変更を誤った作者に帰属させます。モデルの誤りは、知能が足りないためではなく、孤立しているために生じます。

OpenGrok は、すでに人間のエンジニア向けにこの問題を解決しています。数十のプログラミング言語のソースをインデックス化し、コミット済みの履歴全体にわたる全文検索インデックスを保持し、REST API を通じて定義の検索、参照グラフ、blame、ディレクトリの走査、ファイル履歴を提供します。問題は、AI ツールからそこにアクセスする方法がなかったことです。

仕組み

┌──────────────────────────────────────────────────────┐
│  AI Client  (Claude, Copilot, Cursor, Codex …)       │
└─────────────────────┬────────────────────────────────┘
                      │  MCP  (stdio or HTTP)
┌─────────────────────▼────────────────────────────────┐
│  OpenGrok MCP Server  (Node.js)                      │
│  opengrok_api  ──── full API spec, once per session  │
│  opengrok_execute ─ run JavaScript in sandbox        │
│                                                      │
│  OpenGrok client ── search · symbols · blame · diffs │
└─────────────────────┬────────────────────────────────┘
                      │  HTTP (REST + web fallback)
┌─────────────────────▼────────────────────────────────┐
│  OpenGrok                                       │
│  search · symbols · call graphs · index health       │
└──────────────────────────────────────────────────────┘

サーバーは、2 つの主要なツールを公開します。opengrok_api は、セッション開始時に API 仕様全体を提供します。それ以降のすべての操作は opengrok_execute を介して行われます。AI は env.opengrok.* オブジェクト（search、getFileContent、getFileAnnotate、getFileHistory、browseDir、getFileSymbols）を使った JavaScript プログラムを作成し、1 回の実行として送信します。

中間結果はサンドボックス内にとどまり、最終的な return 値だけがコンテキストウィンドウに返されます。シンボルを見つけ、定義を読み、誰が変更したかを確認し、呼び出し元をたどるという一連の調査が、各結果をその都度コンテキスト経由でやり取りするのではなく、1 つのスクリプトで完了します。複雑な調査では、トークンを通常 80～95％節約できます。

すべての env.opengrok.* 呼び出しは、サンドボックスコード内では同期的に見えます。QuickJS WASM VM は、SharedArrayBuffer + Atomics チャネル（データ領域 8 MB、呼び出しごとのタイムアウト 62 秒、実行時間のハード上限 62 秒）を介して、非同期 HTTP 呼び出しを透過的に中継しながら、Node.js のイベントループをブロックしません。

メモリバンク — 2 つのファイルが、ターンやセッションの再起動をまたいで保持されます。現在の調査状態を記録する active-task.md（4 KB）と、追記専用の調査結果を記録する investigation-log.md（32 KB）です。サンドボックス内では、env.opengrok.readMemory() / env.opengrok.writeMemory() を使います。詳しくは、以下のメモリバンクのリファレンスを参照してください。

リファレンス

// Example opengrok_execute code
const refs = env.opengrok.search("handleCrash", { searchType: "refs", maxResults: 5 });
const first = refs.results[0];
const content = env.opengrok.getFileContent(first.project, first.path, {
  startLine: first.matches[0].lineNumber - 5,
  endLine: first.matches[0].lineNumber + 10,
});
return { callerFile: first.path, code: content.content };

リソースサーバーモードでは、このサーバーは独自の IdP が発行した JWT を検証します。組み込みの /token エンドポイントはありません。OPENGROK_JWT_ISSUER が設定されている場合、他の発行者のトークンは拒否されます。RFC 9728 の保護リソースメタデータは /.well-known/oauth-protected-resource で提供されます。

RBAC ロール

不明なトークンやトークンがない場合は、403 Forbidden で拒否されます。認証が設定されていない場合、未認証のリクエストには admin が付与されます（ローカル開発モード）。

CORS

ブラウザーベースのクライアントには、オリジンの許可リスト（カンマ区切りの OPENGROK_ALLOWED_ORIGINS）が適用されます。認証が設定されていない場合、ローカル開発用にループバックオリジン（localhost、127.0.0.1、[::1]）が許可されます。認証（OPENGROK_HTTP_AUTH_TOKEN または RBAC トークン）を設定すると、ループバックは暗黙的に許可されなくなります。ローカルオリジンも含め、許可するすべてのオリジンを明示的に列挙してください。

VS Code との統合

メモ

VS Code はワークスペースごとにツールの認可を管理します。別のリポジトリを開いた場合は、Copilot のツールパネルで OpenGrok のチェックボックスを再度オンにしてください。

設定パネルと VS Code の設定 UI では、同じ設定を管理できます。ガイド付きセットアップ、シークレット、テスト、再読み込みの確認にはパネルを使用してください。ワークスペースごとのオーバーライド、Settings Sync、スクリプトでのデフォルト設定には、settings.json の opengrok-mcp.* 設定を使用してください。Code Mode を推奨します。無効にすると、従来の標準ツールが使用され、新しい Code Mode 専用の機能は利用できません。

トラブルシューティング

ヒント

opengrok-mcp status を実行すると、接続を確認し、設定済みの MCP クライアントを確認できます。

警告

VS Code の再読み込み後や拡張機能の更新後、一時的にツールが Copilot のツール一覧から消えることがあります。ツールアイコンをクリックして「Update Tools」を選択し、続けて Developer: Reload Window を実行すると、ツールが再表示されます。

接続に失敗する — OPENGROK_BASE_URL を確認してください。VPN またはプロキシがエンドポイントをブロックしていないことを確認してください。

401 Unauthorized — OpenGrok: Open Configuration を実行して、認証情報を再入力してください。

自己署名 SSL 証明書エラー — VS Code の設定で opengrok-mcp.verifySsl を false に設定するか、MCP クライアントの設定で OPENGROK_VERIFY_SSL=false に設定してください。

クエリが遅い、またはタイムアウトする — file_type フィルタリングを使って対象範囲を絞るか、特定のプロジェクトを指定してください。opengrok_index_health でインデックスの状態を確認してください。

詳細ログ — OPENGROK_LOG_LEVEL=debug を設定してください。

OpenGrok の互換性

さらに詳しく

クライアントのセットアップ · アーキテクチャ · セキュリティ · コントリビューション · 変更履歴

ライセンス情報

このシステムは、PolyForm Noncommercial License 1.0.0 に基づいて配布されています。

• ✅ 許可される用途： 個人利用、趣味のプロジェクト、学術研究、教育
• ❌ 禁止される用途： 商用、業務、エンタープライズ、または有料でのあらゆる利用

商用ライセンス： エンタープライズ環境（社内ツール、CI パイプライン、業務インフラ）でこの拡張機能を使用するには、商用ライセンスが必須です。 エンタープライズ向けの料金については、[email protected] までお問い合わせください。

利用規約の全文は LICENSE-COMMERCIAL.md をご覧ください。