Gitctx

🚀 gitctx

MCPを介したAIコーディングツール用の高品質GitHubコンテキスト

gitctx は、エージェントやIDEアシスタントに対象のGitHubリポジトリへの最新アクセスを提供するMCPサーバーです。コード、イシュー、PR、コミット、リリースなど、あらゆるものにアクセスできます。これは、Ampの Librarian のオープンソース代替案であり、同じようなアイデアから着想を得ています。

🚀 クイックスタート

インストール

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

git clone https://github.com/winfunc/gitctx.git
cd gitctx
cargo build --release
./target/release/gitctx-mcp

Cargoを使用したインストール

cargo install gitctx
gitctx-mcp

初期設定

1. GitHubトークンを設定する（推奨）:

export GITHUB_TOKEN=ghp_xxx

2. MCPサーバーを起動する:

gitctx-mcp

3. MCPクライアントを設定して、gitctx-mcp をstdio経由で起動する。

✨ 主な機能

• 一般的なウェブスクレイピングではなく、焦点を絞ったGitHub探索プリミティブ
• ツール呼び出し間での状態付きリポジトリコンテキスト（リポジトリ、ブランチ、パス）
• 反復的なコード理解ワークフローに適したデフォルト設定
• stdioトランスポートをサポートする任意のMCPクライアントと互換性がある

機能の概要

• リポジトリの探索と選択 (find_repo)
• コードベースのナビゲーション: ツリー表示/リスト表示/ファイル読み取り/検索/ブランチ切り替え
• フィルターとメタデータを使用したイシューとPRの探索
• コミット、責任追跡、リリース分析
• リポジトリ統計と依存関係グラフの参照
• 現在選択されているコンテキストを公開するMCPリソース
• 繰り返しのAPI呼び出しを減らすためのメモリ内APIキャッシュ

📦 インストール

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

git clone https://github.com/winfunc/gitctx.git
cd gitctx
cargo build --release
./target/release/gitctx-mcp

Cargoを使用したインストール

cargo install gitctx
gitctx-mcp

💻 使用例

基本的な使用法

# GitHubトークンの設定
export GITHUB_TOKEN=ghp_xxx
# MCPサーバーの起動
gitctx-mcp

高度な使用法

Claude Codeの設定

claude mcp add --transport stdio --env GITHUB_TOKEN=${GITHUB_TOKEN} gitctx -- gitctx-mcp

OpenAI Codexの設定

codex mcp add gitctx --env GITHUB_TOKEN=${GITHUB_TOKEN} -- gitctx-mcp

Cursorの設定

{
  "mcpServers": {
    "gitctx": {
      "type": "stdio",
      "command": "gitctx-mcp",
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

Ampの設定

amp mcp add gitctx -- gitctx-mcp

📚 ドキュメント

ツールカタログ

gitctx は現在、23のMCPツールを公開しています。

典型的なワークフロー

1. 最初に find_repo を呼び出してリポジトリを選択する。
2. list_dir、get_tree、read_file/read_files を使用して構造とコンテキストを確立する。
3. 特定の質問に答えるために、焦点を絞ったツール (search_code, search_issues, search_prs, list_commits) を使用する。
4. より深い調査のために、詳細ツール (get_pr, get_commit, blame_file, get_release) を使用する。

リソース

サーバーは1つのMCPリソースを公開しています。

• gitctx://context/current: 現在のリポジトリ/セッションコンテキスト（選択されたリポジトリ、ブランチ、パス、認証ステータス）

認証と権限

トークンの解決順序:

1. GITHUB_TOKEN
2. GH_TOKEN
3. ~/.config/gitctx/token.json

完全な機能を利用するための推奨トークンスコープ:

• repo
• read:org
• read:user

トークンがなくても、公開リポジトリは動作しますが、レート制限が厳しくなります。

運用に関する注意事項

• トランスポート: stdio
• ロギング: stderr（stdoutはMCPプロトコルメッセージ用に予約されています）
• キャッシュ: 繰り返しのAPIリクエスト用のメモリ内TTLキャッシュ
• 検索動作: コード検索はコードパターン/リテラル用であり、自然言語の意味検索ではありません

ユースケース

gitctx はコーディングエージェント用に設計されています。自然言語でタスクを記述すると、エージェントがどのMCPツールを呼び出すかを決定します。

プロンプトの例

プルリクエストとイシュー

• "認証に関連するすべてのオープンPRを見つけ、リスクエリアをまとめる。"
• "レート制限に言及している bug ラベル付きのオープンイシューを表示する。"
• "過去30日間にマージされた、認証またはセッションコードに影響を与えたPRをリストする。"
• "PR #123の未解決のレビューフィードバックをまとめる。"

コードベースの理解

• "認証フローをファイル参照付きでエンドツーエンドでマッピングする。"
• "OAuthコールバックが処理される場所を見つけ、エラーパスを説明する。"
• "このリポジトリの主要なエントリポイントと起動シーケンスを表示する。"
• "このプロジェクトがRedisと通信するすべての場所を見つける。"

変更と回帰分析

• "v1.8.0 と v1.9.0 の間で、ログインに影響を与える可能性のある変更を特定する。"
• "過去2週間に src/auth に影響を与えたコミットを特定する。"
• "この関数の周辺の行の責任を追跡し、最近の所有権の変更をまとめる。"
• "main と release/1.2 を比較して、API互換性を破る違いを特定する。"

依存関係とリリースチェック

• "主要な依存関係をリストし、潜在的に高リスクな推移的依存関係をフラグ付けする。"
• "最新のリリース以降に導入された依存関係の変更を表示する。"
• "リリースの頻度と注目すべきリリースノートのテーマをまとめる。"
• "jsonwebtoken が使用されている場所を見つけ、トークンの検証方法を説明する。"

セキュリティと信頼性

• "ハードコードされたシークレット、トークン、または疑わしい資格情報パターンを見つける。"
• "認可チェックが欠けているエンドポイントを特定する。"
• "弱い暗号化パターンを検索し、結果をまとめる。"
• "セキュリティまたは信頼性に関連するTODO/FIXMEコメントを見つける。"

プロンプトのヒント

• 可能な場合は、リポジトリを明示的に指定する（例: owner/repo）。
• 範囲の境界（パス、ブランチ、タグ、日付範囲、PR番号）を指定する。
• 必要な場合は、構造化された出力を要求する（例: 要約 + ファイル参照 + リスク）。
• 具体的な意図を優先する: "見つけてまとめる" は、漠然とした "調査する" よりも効果的です。

複合的なワンショットプロンプト

これらは意図的に幅広いプロンプトであり、コーディングエージェントが多くのMCPツールをバックグラウンドで調整し、1つの統合された回答を返す必要があります。

• "owner/repo で、認証のリリース準備状況の概要を作成する: 現在の認証コードパスを分析し、認証関連のオープンイシュー、前回のリリース以降のマージされたPR、認証ファイルのコミット変更、およびリリースノートの差分を確認する。トップリスク、信頼度、および正確なファイル/PR/イシュー参照を返す。"
• "owner/repo について、v1.9.0 と main の間に最近のログイン回帰が導入されたかどうかを調査する: リリースを比較し、認証コミットを調査し、関連するPRディスカッションをレビューし、オープンバグレポートと相関させ、最も可能性の高い根本原因コミットを理由付きで特定する。"
• "owner/repo のセキュリティポスチャーのスナップショットを作成する: 機密性の高い認証/セッション/トークンコードを見つけ、最近のセキュリティ関連のコミットとPRコメントを確認し、未解決の高優先度イシューをまとめ、グラフからの依存関係リスクをマッピングする。最後に、優先順位付けされた対策リストを提示する。"
• "一度に、owner/repo の過去60日間のデータアクセス動作の変更をまとめる: コードレベルの差分、重要なPR、関連するイシュー、注目すべきリリース、および重要なファイルに触れたメンテナを確認する。移行の影響スコアとサポートする証拠を提供する。"

FAQ / トラブルシューティング

MCPクライアントが起動するが、ツールが利用できない

• コマンドが gitctx-mcp を指していることを確認する。
• クライアントがstdioトランスポートを使用していることを確認する。
• 手動でターミナルで起動して、起動することを確認する:

gitctx-mcp

リポジトリが選択されていないというエラーが表示される

• コンテキストが設定されるまではこれは正常な動作です。
• 最初に find_repo を呼び出してから、他のツールを実行する。

GitHub APIリクエストがレート制限される

• MCPクライアントを起動する前にトークンをエクスポートする:

export GITHUB_TOKEN=ghp_xxx

• 完全なアクセス権を得るには、スコープに repo、read:org、read:user を含める。

プライベートリポジトリにアクセスできない

• トークンのスコープに repo が含まれていることを確認する。
• トークンがターゲットのリポジトリ/組織にアクセスできるアカウントに属していることを確認する。
• 環境変数を更新した後、MCPクライアントを再起動する。

search_code が予期しない結果を返す

• search_code はリテラルコードパターンを期待しており、自然言語クエリではありません。
• 特定の識別子、シンボル、または文字列（例: 関数/クラス名）を使用する。

デバッグ時にサーバーが反応しないように見える

• ログはデザイン上stderrに出力されます。
• 明示的なロギングで実行する:

RUST_LOG=gitctx_mcp=debug,rmcp=warn gitctx-mcp

gitctx-mcp コマンドが見つからない

• Cargoでインストールした場合は、CargoのバイナリパスがシェルのPATHに含まれていることを確認する。
• 典型的なパス:

export PATH="$HOME/.cargo/bin:$PATH"

🔧 技術詳細

開発

cargo check
cargo clippy
cargo test --lib --bins

ローカルでのサーバー実行

RUST_LOG=gitctx_mcp=debug,rmcp=warn gitctx-mcp

プロジェクト構造

gitctx/
├── src/
│   ├── mcp/              # MCPサーバー、ツールルーター、リソース
│   ├── github/           # GitHub API統合
│   ├── auth/             # トークンの読み込みと検証
│   ├── cache.rs          # メモリ内APIキャッシュ
│   ├── context.rs        # 共有探索コンテキスト
│   ├── xml_format.rs     # 構造化ツール出力のフォーマット
│   └── mcp_main.rs       # MCPバイナリのエントリポイント
├── Cargo.toml
└── README.md

インスピレーション

gitctx は、Amp CodeのLibrarianによって普及したワークフローカテゴリをモデルにしています。これは、GitHubコードベースを迅速に検索し理解するための特殊なエージェント機能であり、リポジトリや依存関係をまたがって機能します。

参考:

• Amp Chronicle: “The Librarian” (2025年10月20日): https://ampcode.com/news/librarian

📄 ライセンス

MITライセンス。詳細は LICENSE を参照してください。