Gitctx

🚀 gitctx

gitctx 是一個通過 MCP 為 AI 編碼工具提供高價值 GitHub 上下文的工具。它能讓代理和 IDE 助手有針對性地、及時地訪問 GitHub 倉庫，涵蓋代碼、問題、拉取請求、提交、版本發佈等所有內容。這是 Amp 的 Librarian 的開源替代方案，且受到了它的啟發。

✨ 主要特性

• 專注於 GitHub 探索原語，而非通用的網頁抓取。
• 跨工具調用保持有狀態的倉庫上下文（倉庫、分支、路徑）。
• 為迭代式代碼理解工作流提供良好的默認設置。
• 可與任何支持標準輸入輸出傳輸的 MCP 客戶端配合使用。

📦 安裝指南

從源代碼安裝

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。

💻 使用示例

編碼代理設置

Claude Code

添加 gitctx 作為本地標準輸入輸出 MCP 服務器：

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

後續有用的操作：

claude mcp list
/mcp

注意事項：

• Claude 文檔支持使用 --scope 進行作用域安裝（local、project、user）。
• 對於團隊共享，建議使用項目作用域的 MCP 配置。

OpenAI Codex

通過命令行添加：

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

檢查狀態：

codex mcp --help

另一種通過 config.toml 設置的方式（~/.codex/config.toml 或項目 .codex/config.toml）：

[mcp_servers.gitctx]
command = "gitctx-mcp"
env_vars = ["GITHUB_TOKEN", "GH_TOKEN"]

Cursor

創建項目配置 .cursor/mcp.json 或全局配置 ~/.cursor/mcp.json：

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

注意事項：

• Cursor 文檔描述了基於 mcp.json 的標準輸入輸出/遠程服務器配置。
• 項目配置最適合倉庫本地共享；全局配置最適合個人默認設置。

Amp

通過 Amp 命令行添加 gitctx：

amp mcp add gitctx -- gitctx-mcp

如果你在 Amp 配置（~/.config/amp/settings.json）中管理 MCP 服務器，使用文檔中的 amp.mcpServers 格式：

{
  "amp.mcpServers": {
    "gitctx": {
      "command": "gitctx-mcp",
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

如果在工作區設置中添加，Amp 可能需要明確批准：

amp mcp approve gitctx

MCP 客戶端配置

如果你的客戶端支持通過標準輸入輸出使用 MCP，但未在上述列表中，使用以下通用格式：

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

最低要求：

• 標準輸入輸出傳輸
• 命令 gitctx-mcp
• 轉發 GITHUB_TOKEN（或 GH_TOKEN）環境變量

📚 詳細文檔

工具目錄

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）進行更深入的檢查。

資源

服務器公開了一個 MCP 資源：

• gitctx://context/current：當前倉庫/會話上下文（所選倉庫、分支、路徑、認證狀態）

認證和權限

令牌解析順序：

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

推薦的完整功能令牌範圍：

• repo
• read:org
• read:user

沒有令牌時，公共倉庫仍然可以使用，但速率限制較低。

操作注意事項

• 傳輸：標準輸入輸出
• 日誌記錄：標準錯誤輸出（標準輸出保留用於 MCP 協議消息）
• 緩存：內存中的 TTL 緩存，用於重複的 API 請求
• 搜索行為：代碼搜索針對代碼模式/字面量，而非自然語言語義搜索

使用場景

gitctx 專為編碼代理設計。你用自然語言描述任務，代理決定調用哪些 MCP 工具。

提示示例

拉取請求和問題

• "查找所有與身份驗證相關的開放拉取請求，並總結風險區域。"
• "顯示標記為 bug 且提及速率限制的開放問題。"
• "列出過去 30 天內涉及身份驗證或會話代碼的已合併拉取請求。"
• "總結拉取請求 #123 上未解決的審查反饋。"

代碼庫理解

• "端到端映射身份驗證流程，並提供文件引用。"
• "查找 OAuth 回調處理的位置，並解釋錯誤路徑。"
• "顯示此倉庫的主要入口點和啟動序列。"
• "定位此項目與 Redis 交互的所有位置。"

變更和迴歸分析

• "v1.8.0 和 v1.9.0 之間哪些變更可能影響登錄？"
• "識別過去 2 周內涉及 src/auth 的提交。"
• "找出此函數週圍行的責任人，並總結最近的所有權變更。"
• "比較 main 和 release/1.2 之間的 API 破壞性差異。"

依賴和版本檢查

• "列出頂級依賴項，並標記潛在高風險的傳遞依賴項。"
• "顯示最新版本發佈後引入的依賴項變更。"
• "總結版本發佈節奏和顯著的版本說明主題。"
• "查找 jsonwebtoken 的使用位置以及令牌的驗證方式。"

安全和可靠性

• "查找硬編碼的秘密、令牌或可疑的憑證模式。"
• "識別缺少授權檢查的端點。"
• "搜索弱加密模式並總結結果。"
• "定位與安全或可靠性相關的 TODO/FIXME 註釋。"

提示技巧

• 儘可能明確提及倉庫（例如：owner/repo）。
• 給出範圍邊界（路徑、分支、標籤、日期範圍、拉取請求編號）。
• 需要時請求結構化輸出（例如：總結 + 文件引用 + 風險）。
• 優先使用具體意圖：“查找並總結” 比模糊的 “調查” 效果更好。

複合一次性提示

這些是有意寬泛的提示，編碼代理應在幕後協調多個 MCP 工具，並返回一個綜合答案。

• "在 owner/repo 中，為身份驗證生成一份版本發佈準備簡報：分析當前的身份驗證代碼路徑、開放的與身份驗證相關的問題、自上次版本發佈以來的已合併拉取請求、身份驗證文件中的提交變動以及版本說明差異。返回頂級風險、置信度級別以及確切的文件/拉取請求/問題引用。"
• "對於 owner/repo，調查 v1.9.0 和 main 之間是否引入了最近的登錄迴歸問題：比較版本發佈、檢查身份驗證提交、審查相關的拉取請求討論、關聯開放的錯誤報告，並確定最可能的根本原因提交及理由。"
• "為 owner/repo 創建一個安全態勢快照：查找敏感的身份驗證/會話/令牌代碼、檢查最近與安全相關的提交和拉取請求評論、總結未解決的高優先級問題，並從圖中映射依賴項風險。最後提供一個優先級修復列表。"
• "一次性總結 owner/repo 在過去 60 天內數據訪問行為的變更：代碼級別的差異、關鍵拉取請求、關聯的問題、顯著的版本發佈以及涉及關鍵文件的維護者。提供遷移影響評分和支持證據。"

常見問題解答 / 故障排除

MCP 客戶端啟動，但沒有可用工具

• 確認命令指向 gitctx-mcp。
• 確保客戶端使用標準輸入輸出傳輸。
• 在終端手動啟動以驗證是否可以正常啟動：

gitctx-mcp

出現錯誤提示未選擇倉庫

• 在設置上下文之前，這是預期的。
• 首先調用 find_repo，然後運行其他工具。

GitHub API 請求受到速率限制

• 在啟動 MCP 客戶端之前導出令牌：

export GITHUB_TOKEN=ghp_xxx

• 為了獲得完整訪問權限，包含範圍：repo、read:org、read:user。

無法訪問私有倉庫

• 確保令牌範圍包含 repo。
• 確認令牌屬於有權訪問目標倉庫/組織的賬戶。
• 更新環境變量後重啟 MCP 客戶端。

search_code 返回意外結果

• search_code 期望的是字面代碼模式，而非自然語言查詢。
• 使用特定的標識符、符號或字符串（例如函數/類名）。

調試時服務器看起來無響應

• 日誌按設計輸出到標準錯誤輸出。
• 使用顯式日誌記錄運行：

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

找不到 gitctx-mcp 命令

• 如果使用 Cargo 安裝，確保 Cargo 二進制路徑在你的 shell 路徑中。
• 典型路徑：

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。