JinDaGe - gitctx MCP Details

article

README

🚀 gitctx

gitctx 是一个通过 MCP 为 AI 编码工具提供高价值 GitHub 上下文的工具。它能让代理和 IDE 助手有针对性地、及时地访问 GitHub 仓库，涵盖代码、问题、拉取请求、提交、版本发布等所有内容。这是 Amp 的 Librarian 的开源替代方案，且受到了它的启发。

Screenshot 2026-02-14 at 12 48 59 AM

✨ 主要特性

专注于 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

🚀 快速开始

设置 GitHub 令牌（推荐）：

export GITHUB_TOKEN=ghp_xxx

启动 MCP 服务器：

gitctx-mcp

配置你的 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 工具。

| 类别 | 工具 | |------|------| | 仓库上下文 | find_repo、switch_branch、get_tree | | 代码导航 | list_dir、read_file、read_files、search_code | | 问题 | search_issues、get_issue、list_issue_comments | | 拉取请求 | search_prs、get_pr、list_pr_comments | | 提交 | list_commits、get_commit、compare_commits、blame_file | | 版本发布 | list_releases、get_release、compare_releases | | 洞察 | get_contributors、get_repo_stats、get_dependency_graph |

典型工作流程

首先调用 find_repo 选择一个仓库。
使用 list_dir、get_tree 和 read_file/read_files 建立结构和上下文。
使用聚焦工具（search_code、search_issues、search_prs、list_commits）回答特定问题。
使用详细工具（get_pr、get_commit、blame_file、get_release）进行更深入的检查。

资源

服务器公开了一个 MCP 资源：

gitctx://context/current：当前仓库/会话上下文（所选仓库、分支、路径、认证状态）

认证和权限

令牌解析顺序：

GITHUB_TOKEN
GH_TOKEN
~/.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。