ghcontext: Supercharge Your LLMs with Real-time GitHub Context

ghcontext：借助实时 GitHub 上下文，全面提升大模型能力

“可是我的 GitHub 仓库昨天才更新……”——再也不用担心 AI 助手的信息过时了。

ghcontext（GitHub 上下文提供程序）弥合了 GitHub 与大模型之间的差距，通过标准化的 Model Context Protocol（MCP），让 AI 助手能够实时访问仓库信息。

🔥 为什么选择 ghcontext？

• 准确的实时信息： 大模型通常掌握着过时的仓库信息。ghcontext 可提供最新的 API 文档、README 内容和代码库结构——也支持私有仓库。
• 深入理解： 帮助大模型理解项目架构、设计原则和 API 使用模式。
• 无缝集成： 兼容任何支持 MCP 的模型，包括 Claude、GPT 等。
• 高效便捷： 智能缓存可减少 API 调用，同时确保信息及时更新。

✨ 主要功能

• 提取 API 文档： 自动识别并提取 README 和专用文档文件中的 API 文档
• 分析仓库结构： 提供代码库组织结构图
• 获取 README 内容： 直接从 GitHub 获取最新文档
• 搜索文件内容： 查找并提取特定文件或代码片段
• 搜索仓库： 查找符合特定条件的仓库

🚀 快速开始

关于令牌的说明

ghcontext 需要 GitHub 令牌进行身份验证。你需要负责安全地管理令牌，并且只授予使用场景真正需要的权限范围。 例如，如果你只需读取公开仓库，可以创建一个带有 public_repo 权限范围的令牌。ghcontext 不需要对仓库的写入权限。

安装

方法 1：使用 npx 运行，无需安装

# Run directly without installation (GitHub token is REQUIRED)
npx ghcontext --GITHUB_TOKEN your_github_token

# OR using pnpm
pnpm dlx ghcontext --GITHUB_TOKEN your_github_token

这是提供给 Claude Agent 的首选方式，因为无需安装，可直接从命令行运行。

方法 2：从 npm 全局安装

# Install globally using npm
npm install -g ghcontext

# OR using pnpm
pnpm add -g ghcontext

# Run ghcontext with your GitHub token (REQUIRED)
ghcontext --GITHUB_TOKEN your_github_token

方法 3：手动安装（开发）

# Clone the repository
git clone https://github.com/yourusername/ghcontext.git
cd ghcontext

# Install dependencies
pnpm install

# Start the server with GitHub token (REQUIRED)
pnpm start --GITHUB_TOKEN your_github_token

与大模型搭配使用

将兼容 MCP 的大模型连接到 ghcontext 服务端点：

http://localhost:3000/api/mcp

现在，你的大模型就可以使用以下工具：

• get-repository-info：获取仓库的详细信息
• get-repository-readme：获取当前 README 内容
• get-repository-api-docs：提取 API 文档
• search-repository-files：在仓库中查找文件
• get-file-content：获取特定文件的内容

🔍 示例场景

向支持 MCP 的 AI 助手提问：

“axios 库中有哪些方法可用于处理请求拦截器？”

你的助手不会给出过时或泛泛的信息，而是可以：

1. 使用 get-repository-api-docs 获取最新的 axios API 文档
2. 分析当前文档中的拦截器方法
3. 为你提供准确且最新的信息

🧰 架构

ghcontext 采用模块化设计：

┌─────────────────┐       ┌──────────────┐       ┌────────────────┐
│   MCP Server    │◄─────►│  GitHub API  │◄─────►│  GitHub.com    │
│  (TypeScript)   │       │    Client    │       │                │
└────────┬────────┘       └──────────────┘       └────────────────┘
         │
         │
┌────────▼────────┐       ┌──────────────┐
│ Context         │       │   Caching    │
│ Processors      │◄─────►│   System     │
└─────────────────┘       └──────────────┘

• MCP 服务： 处理 Model Context Protocol 通信
• GitHub API 客户端： 管理 GitHub REST 和 GraphQL API 交互
• 上下文处理器： 提取并整理相关信息
• 缓存系统： 提升性能并减少 API 负载

🧠 为什么这很重要

传统 AI 助手难以应对以下问题：

• 对代码仓库的了解已过时
• 对项目结构的理解不完整
• 无法查看近期的更改和更新

ghcontext 通过让大模型直接获取 GitHub 上的最新信息，解决了这些问题，让你的 AI 助手更加准确、实用，并能更好地跟上不断演进的代码库。

🛠️ 开发

# Build the project
pnpm run build

# Run tests
pnpm test

# Lint your code
pnpm run lint

# Format your code
pnpm run format

📦 发布到 npm

如果你是此软件包的维护者，需要发布新版本：

1. 更新 package.json 中的版本：

   # For patch releases (bug fixes)
   npm version patch
   
   # For minor releases (new features, no breaking changes)
   npm version minor
   
   # For major releases (breaking changes)
   npm version major
   

2. 发布到 npm：

   # The prepublishOnly script will run linting, tests, and build automatically
   npm publish
   

3. 将标签推送到 GitHub：

   git push --follow-tags
   

📝 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

---

ghcontext：让你的 AI 助手像你一样了解你的代码。