gitctx MCP

gitctx

High-signal GitHub context for AI coding tools via MCP

gitctx 是一个MCP服务器，为代理和IDE助手提供对GitHub存储库的有针对性的最新访问。代码、问题、PR、提交、发布，一切。这是Amp的开源替代品 图书管理员 并受到同样的启发。

为什么选择gitctx

• 聚焦GitHub探索原语，而不是通用的网络抓取
• 跨工具调用（仓库、分支、路径）的有状态存储库上下文
• 迭代代码理解工作流的良好默认值
• 适用于任何支持stdio传输的MCP客户端

功能摘要

• 存储库发现和选择(find_repo)
• 代码库导航：树/列表/读取/搜索/切换分支
• 使用过滤器和元数据进行问题和公关探索
• 提交、指责和发布分析
• 存储库统计和依赖关系图查找
• MCP资源公开当前选定的上下文
• 内存内API缓存以减少重复调用

目录

• 安装
• 快速开始
• 编码代理设置
• MCP客户端配置
• 工具目录
• 资源
• 身份验证和权限
• 操作说明
• 用例
• 常见问题解答/故障排除
• 发展
• 项目结构
• 灵感
• 许可证

安装

来源

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

货物

cargo install gitctx
gitctx-mcp

快速开始

1. 设置GitHub令牌（推荐）：

export GITHUB_TOKEN=ghp_xxx

1. 启动MCP服务器：

gitctx-mcp

1. 配置MCP客户端以生成 gitctx-mcp 超过stdio。

编码代理设置

克劳德代码

添加 gitctx 作为本地stdio MCP服务器：

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

有用的后续行动：

claude mcp list
/mcp

笔记：

• Claude文档支持范围安装(local, project, user)与 --scope.
• 对于团队共享，首选项目范围的MCP配置。

OpenAI Codex

通过CLI添加：

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/mcp.json 或全局配置 ~/.cursor/mcp.json:

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

笔记：

• 光标文档描述 mcp.json-基于stdio/远程服务器的配置。
• 项目配置最适合回购本地共享；全局配置最适合个人默认值。

安培

添加 gitctx 通过Amp CLI：

amp mcp add gitctx -- gitctx-mcp

如果您在Amp配置中管理MCP服务器(~/.config/amp/settings.json)，使用文档 amp.mcpServers 形状：

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

如果添加到工作区设置中，Amp可能需要明确批准：

amp mcp approve gitctx

MCP客户端配置

如果您的客户端支持MCP over stdio，但上面没有列出，请使用以下通用形状：

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

最低要求：

• stdio传输
• 命令 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

没有令牌，公共存储库仍然可以工作，但速率限制较低。

操作说明

• 运输：stdio
• 日志记录：stderr（stdout保留用于MCP协议消息）
• 缓存：内存中用于重复API请求的TTL缓存
• 搜索行为：代码搜索是针对代码模式/文字的，而不是自然语言语义搜索

用例

gitctx 专为编码代理而设计。您用自然语言描述任务，代理决定调用哪些MCP工具。

提示示例

拉取请求和问题

• “查找与身份验证相关的所有未解决的PR，并总结风险领域。”
• “显示标记为的未解决问题 bug 提到限速。"
• “列出过去30天内涉及身份验证或会话代码的合并PR。”
• “总结PR#123上未解决的审核反馈。”

代码库理解

• “将身份验证流与文件引用进行端到端映射。”
• “查找OAuth回调的处理位置并解释错误路径。”
• “显示此仓库的主要入口点和启动顺序。”
• “找到这个项目与Redis对话的所有地方。”

变化与回归分析

• “两者之间发生了什么变化 v1.8.0 和 v1.9.0 这会影响登录吗？"
• “确定过去两周内涉及的承诺 src/auth."
• “归咎于围绕此功能的线条，并总结最近的所有权变更。”
• “比较 main 和 release/1.2 对于突破API的差异。"

依赖性和发布检查

• “列出顶级依赖项，并标记潜在的高风险可传递依赖项。”
• “显示最新版本后引入的依赖关系更改。”
• “总结发布节奏和值得注意的发布说明主题。”
• “查找位置 jsonwebtoken 以及如何验证令牌。"

安全性与可靠性

• 查找硬编码的秘密、令牌或可疑的凭据模式
• “识别缺少授权检查的端点。”
• “搜索弱加密模式并总结发现。”
• “查找与安全性或可靠性相关的TODO/FIXME注释。”

提示提示

• 在可能的情况下明确提及存储库（例如： owner/repo).
• 给出范围边界（路径、分支、标签、日期范围、PR编号）。
• 需要时要求结构化输出（例如：摘要+文件引用+风险）。
• 更喜欢具体的意图：“发现和总结”比模糊的“调查”更有效

复合单次射击提示

这些是有意的宽泛提示，编码代理应在幕后编排许多MCP工具并返回一个完整的答案。

• “In owner/repo，为身份验证生成发布准备简报：分析当前的身份验证代码路径、打开与身份验证相关的问题、自上次发布以来合并的PR、提交身份验证文件中的流失以及发布说明的增量。返回最高风险、置信水平和确切的文件/PR/问题参考。"
• “为了 owner/repo，调查最近是否引入了登录回归 v1.9.0 和 main：比较版本，检查认证提交，审查相关的PR讨论，与开放的bug报告相关联，并确定最可能的根本原因提交及其理由。"
• “为创建安全态势快照 owner/repo：查找敏感的身份验证/会话/令牌代码，检查最近与安全相关的提交和PR注释，总结未解决的高优先级问题，并从图中映射依赖风险。以优先补救列表结束。"
• “一次性总结过去60天数据访问行为的变化 owner/repo：代码级差异、关键PR、链接问题、值得注意的版本以及维护人员接触关键文件。提供迁移影响评分和支持证据。"

常见问题解答/故障排除

MCP客户端已启动，但没有可用的工具

• 确认命令点 gitctx-mcp.
• 确保客户端使用stdio传输。
• 在终端中手动启动以验证其是否启动：

gitctx-mcp

我收到错误，说没有选择存储库

• 在设置上下文之前，这是预期的。
• 呼叫 find_repo 首先，然后运行其他工具。

GitHub API请求是有费率限制的

• 在启动MCP客户端之前导出令牌：

export GITHUB_TOKEN=ghp_xxx

• 要获得完全访问权限，请包括以下范围： repo, read:org, read:user.

私有存储库不可访问

• 确保令牌范围包括 repo.
• 确认令牌属于有权访问目标repo/org的帐户。
• 更新环境变量后重新启动MCP客户端。

search_code 返回意外结果

• search_code 需要文字代码模式，而不是自然语言查询。
• 使用特定的标识符、符号或字符串（例如函数/类名）。

调试时服务器显示为静音

• 日志按设计会转到stderr。
• 使用显式日志记录运行：

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

gitctx-mcp 找不到命令

• 如果与Cargo一起安装，请确保货箱路径在您的shell 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 server, tool router, resources
│   ├── github/           # GitHub API integrations
│   ├── auth/             # Token loading and validation
│   ├── cache.rs          # In-memory API cache
│   ├── context.rs        # Shared exploration context
│   ├── xml_format.rs     # Structured tool output formatting
│   └── mcp_main.rs       # MCP binary entrypoint
├── Cargo.toml
└── README.md

灵感

gitctx 以Amp Code的库管理员推广的工作流类别为蓝本：这是一种专门的代理功能，用于快速搜索和理解GitHub代码库，包括跨存储库和依赖关系。

参考：

• Amp Chronicle：《图书馆员》（2025年10月20日）：https://ampcode.com/news/librarian

许可证

MIT许可证。看 许可证.