MCP GitHub Client

GitHub MCP服务器

用于GitHub REST API与TypeScript集成的交互式模型上下文协议（MCP）服务器。

特性

• 三个GitHub工具：搜索存储库、获取存储库问题和搜索代码
• SQLite缓存：通过智能缓存减少API调用
• 速率限制：妥善处理GitHub API速率限制
• 不要求进行验证：适用于没有令牌的公共存储库
• TypeScript：全型安全和现代开发经验

工具

1.search_repos（用户名，查询）

按用户名和查询搜索存储库。

• 参数:

- username：GitHub用户名（默认：环境变量GitHub_username或“octocat”） - query：搜索查询（默认：“语言：javascript”）

• 示例：在Python存储库中搜索用户“octocat”

2.get_repo_issues（回购，状态）

获取存储库的未决问题。

• 参数:

- repo：“所有者/仓库”格式的仓库（必填） - state：问题状态-“打开”、“关闭”或“全部”（默认值：“打开”）

• 示例：从“microsoft/vcode”获取未决问题

3.search_code（仓库、查询）

在存储库中搜索代码。

• 参数:

- repo：“所有者/仓库”格式的仓库（必填） - query：代码搜索查询（必填）

• 示例：在“facebook/react”中搜索“TODO”评论

安装

先决条件

• Node.js 18+
• npm或纱线

设置步骤

1. 克隆或创建项目目录:

   mkdir github-mcp-server
   cd github-mcp-server

1. 安装依赖项:

   npm install

1. 设置环境变量 （可选但推荐）：

   # Create .env file
   touch .env

   # Add your GitHub username and token (token increases rate limits)
   echo "GITHUB_USERNAME=your-github-username" >> .env
   echo "GITHUB_TOKEN=ghp_your_token_here" >> .env

获取GitHub代币

1. 前往GitHub设置>开发者设置>个人访问令牌
2. 生成新令牌（经典）
3. 选择范围：

- repo （如果您想访问私有存储库） - public_repo （仅适用于公共存储库） - search （用于搜索功能）

1. 复制令牌并将其添加到您的 .env 文件

备注：服务器使用公共API在没有令牌的情况下工作（60个请求/小时限制）。使用令牌，您每小时会收到5000个请求。

用法

发展模式

npm run dev

生产模式

# Build the project
npm run build

# Start the server
npm start

环境变量

• GITHUB_USERNAME：搜索的默认GitHub用户名
• GITHUB_TOKEN：GitHub个人访问令牌（可选）

查询示例

搜索存储库

// Search for Python repositories by a specific user
{
  "tool": "search_repos",
  "arguments": {
    "username": "octocat",
    "query": "language:python"
  }
}

// Search for repositories with "mcp" in name
{
  "tool": "search_repos", 
  "arguments": {
    "query": "mcp in:name"
  }
}

获取存储库问题

// Get open issues from a popular repository
{
  "tool": "get_repo_issues",
  "arguments": {
    "repo": "microsoft/vscode"
  }
}

// Get all issues (open and closed) from a repository
{
  "tool": "get_repo_issues",
  "arguments": {
    "repo": "facebook/react",
    "state": "all"
  }
}

搜索代码

// Search for TODO comments in a repository
{
  "tool": "search_code",
  "arguments": {
    "repo": "facebook/react",
    "query": "TODO"
  }
}

// Search for specific function definitions
{
  "tool": "search_code",
  "arguments": {
    "repo": "microsoft/vscode",
    "query": "function handleClick"
  }
}

// Search for import statements
{
  "tool": "search_code",
  "arguments": {
    "repo": "nodejs/node",
    "query": "import express"
  }
}

速率限制

服务器包括智能速率限制：

• 无令牌：每小时60个请求
• 带令牌：每小时5000个请求
• 自动处理：达到费率限制时等待
• 缓存优先方法：使用SQLite缓存最小化API调用
• 预警系统：接近速率限制时发出警报

缓存策略

• 搜索端点：10分钟缓存
• 存储库数据：10分钟缓存
• 问题：5分钟缓存
• 通用数据：5分钟缓存

缓存

服务器使用SQLite进行缓存以减少API调用：

• 自动清理：删除过期条目
• 智能TTL：不同端点的缓存时间不同
• 缓存失效：数据过期时自动

缓存文件位置

• 违约： ./cache.db
• 可以在CacheManager构造函数中自定义

错误处理

服务器处理各种错误情况：

• 请求频率超限：自动等待并重试
• 网络错误：优雅的降级，信息丰富
• 无效参数：清除错误消息
• API错误：详细的GitHub API错误响应

日志记录

所有操作都会记录到stderr进行调试：

• 速率限制警告
• 缓存操作
• API请求/响应信息
• 错误详细信息

发展

项目结构

src/
├── server.ts         # Main MCP server
├── github-client.ts  # GitHub API client with rate limiting
└── cache.ts         # SQLite caching layer

建筑

npm run build

清洁

npm run clean

故障排除

常见问题

1. “找不到模块”错误：运行 npm install 安装依赖项
2. 速率限制错误：添加GitHub令牌或等待重置
3. 权限错误：检查cache.db文件是否具有写入权限
4. TypeScript错误：确保你有Node.js 18+和TypeScript 5+

调试模式

设置详细日志记录的环境变量：

DEBUG=github-mcp-server npm run dev

贡献

1. 复刻仓库
2. 创建要素分支
3. 添加新功能的测试
4. 确保所有测试通过
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件