ghcontext：使用实时 GitHub 上下文增强你的 LLM

"但是我的 GitHub 仓库昨天更改了..." - 再也不用担心你的 AI 助手中的信息过时了。

ghcontext (GitHub Context Provider) 弥合了 GitHub 和大型语言模型之间的差距，通过标准化的模型上下文协议 (MCP) 为 AI 助手提供对仓库信息的实时访问。

<p align="center"> <img src="docs/images/ghcontext-diagram.png" alt="ghcontext 架构" width="600"/> </p>

🔥 为什么选择 ghcontext？

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

✨ 主要特性

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

🚀 快速开始

关于 token 的说明

ghcontext 需要 GitHub token 进行身份验证。 你有责任安全地管理你的 token，并且你应该只授予它你的用例真正需要的权限范围。 例如，如果你只需要读取公共仓库，你可以创建一个具有 public_repo 权限范围的 token。 ghcontext 不需要对你的仓库的写入权限。

安装

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

# 直接运行，无需安装 (需要 GitHub token)
npx ghcontext --GITHUB_TOKEN your_github_token

# 或者使用 pnpm
pnpm dlx ghcontext --GITHUB_TOKEN your_github_token

这是提供给 claude agent 的首选方法，因为它不需要任何安装，你可以直接从命令行运行它。

方法 2：从 npm 全局安装

# 使用 npm 全局安装
npm install -g ghcontext

# 或者使用 pnpm
pnpm add -g ghcontext

# 使用你的 GitHub token 运行 ghcontext (需要)
ghcontext --GITHUB_TOKEN your_github_token

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

# 克隆仓库
git clone https://github.com/yourusername/ghcontext.git
cd ghcontext

# 安装依赖
pnpm install

# 使用 GitHub token 启动服务器 (需要)
pnpm start --GITHUB_TOKEN your_github_token

与 LLM 一起使用

将你的 MCP 兼容 LLM 连接到 ghcontext 服务器端点：

http://localhost:3000/api/mcp

你的 LLM 现在可以访问以下工具：

• 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 服务器    │◄─────►│  GitHub API  │◄─────►│  GitHub.com    │
│  (TypeScript)   │       │    客户端    │       │                │
└────────┬────────┘       └──────────────┘       └────────────────┘
         │
         │
┌────────▼────────┐       ┌──────────────┐
│ 上下文          │       │   缓存       │
│ 处理器          │◄─────►│   系统       │
└─────────────────┘       └──────────────┘

• MCP 服务器： 处理模型上下文协议通信
• GitHub API 客户端： 管理 GitHub REST 和 GraphQL API 交互
• 上下文处理器： 提取和组织相关信息
• 缓存系统： 提高性能并减少 API 负载

🧠 为什么重要

传统的 AI 助手在以下方面存在问题：

• 仓库知识过时
• 对项目结构理解不完整
• 无法看到最近的更改和更新

ghcontext 通过为 LLM 提供直接访问 GitHub 最新信息的途径来解决这些问题，使你的 AI 助手更准确、更有帮助，并且与你不断发展的代码库更加同步。

🛠️ 开发

# 构建项目
pnpm run build

# 运行测试
pnpm test

# Lint 你的代码
pnpm run lint

# 格式化你的代码
pnpm run format

📦 发布到 npm

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

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

   # 对于补丁版本（错误修复）
   npm version patch
   
   # 对于次要版本（新功能，无重大更改）
   npm version minor
   
   # 对于主要版本（重大更改）
   npm version major
   

2. 发布到 npm：

   # prepublishOnly 脚本将自动运行 linting、测试和构建
   npm publish
   

3. 将标签推送到 GitHub：

   git push --follow-tags
   

📝 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

---

<p align="center"> <i>ghcontext：因为你的 AI 助手应该像你一样理解你的代码。</i> </p>