JinDaGe - mcp-server-github-repo MCP Details

article

README

🚀 MCP GitHub 仓库服务器

MCP GitHub 仓库服务器基于模型上下文协议（MCP），可让AI助手便捷地浏览与读取指定GitHub仓库内的文件，实现对仓库内容的高效访问。

🚀 快速开始

配置环境变量

服务器运行依赖以下环境变量，请按需配置：

GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token
GITHUB_OWNER=repository_owner
GITHUB_REPO=repository_name
GITHUB_BRANCH=branch_name  # 可选

安装依赖

npm install

构建服务器

npm run build

开发模式

若需自动重建开发，可执行：

npm run watch

与Claude Desktop集成

在Claude Desktop中使用时，需添加服务器配置：

配置位置

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-server-github-repo": {
      "command": "/path/to/mcp-server-github-repo/build/index.js"
    }
  }
}

✨ 主要特性

资源访问

灵活文件访问：可通过URI访问仓库中的任意文件。
内容导航：支持列出仓库内容并导航目录。
分支特定访问：支持分支特定的文件访问。
纯文本输出：文件内容以纯文本格式提供。

资源URI规范

基本URL格式：https://api.github.com/repos/{owner}/{repo}/contents/{path}
类型支持：支持文件和目录，文件使用 text/plain MIME类型，目录使用 application/x-directory MIME类型。

📦 安装指南

与Claude Desktop一起使用时，按上述配置位置添加服务器配置即可完成安装。

💻 使用示例

基础用法

通过基本URL格式访问仓库资源，例如访问特定文件：

https://api.github.com/repos/owner/repo/contents/path/to/file.txt

高级用法

若要访问特定分支的文件，可在URL中指定分支：

https://api.github.com/repos/owner/repo/contents/path/to/file.txt?ref=branch_name

📚 详细文档

API 实现

服务器实现了三个主要MCP端点：

ListResources - 列出仓库中的文件和目录
ReadResource - 获取特定文件的内容

认证机制

服务器使用GitHub个人访问令牌进行认证，请确保您的令牌具有适当的权限以访问仓库内容。

错误处理

服务器包含以下错误处理机制：

环境变量缺失
GitHub API错误
无效路径（例如尝试将目录读取为文件）
认证失败

调试方法

由于MCP服务器通过stdio通信，调试可能具有挑战性。可使用MCP Inspector进行调试：

npm run inspector

这将提供一个访问浏览器中的调试工具的URL。

🔧 技术细节

服务器借助GitHub API实现对仓库资源的访问，通过环境变量配置仓库信息和认证令牌。在处理请求时，根据不同的MCP端点和资源URI，调用相应的GitHub API接口获取资源，并对返回结果进行处理和格式化。同时，服务器包含完善的错误处理机制，以应对各种可能的异常情况。

📄 许可证

本项目采用MIT许可证。

演示

demo

⚠️ 重要提示

请保持GitHub个人访问令牌的安全，考虑使用权限最小的令牌，并注意仓库大小限制，以免影响访问大型仓库。

💡 使用建议

在开发过程中，可使用 npm run watch 命令进行带自动重建的开发，提高开发效率。调试时，使用MCP Inspector可更方便地进行问题排查。

mcp-server-github-repo