PyGithub MCP Server

PyGithub MCP 服务

一个模型上下文协议服务，通过 PyGithub 提供与 GitHub API 交互的工具。此服务可让 AI 助手执行 GitHub 操作，例如管理议题、代码库和拉取请求。

功能

• 模块化工具架构：

  • 可配置要启用或禁用的工具组
  • 按领域组织（议题、代码库等）
  • 可通过文件或环境变量灵活配置
  • 采用模块化设计，职责分明
  • 遵循一致的模式，易于扩展

• 完整的 GitHub 议题管理：

  • 创建和更新议题
  • 获取议题详情并列出代码库议题
  • 添加、列出、更新和删除评论
  • 管理议题标签
  • 处理受指派人和里程碑

• 智能参数处理：

  • 为可选参数动态构建 kwargs
  • 正确转换 GitHub 对象的类型
  • 验证所有输入参数
  • 为无效输入提供清晰的错误消息

• 稳健的实现：

  • 通过 PyGithub 面向对象地与 GitHub API 交互
  • 集中管理 GitHub 客户端
  • 妥善处理错误和速率限制
  • 通过 MCP 工具提供简洁的 API 抽象
  • 全面支持分页
  • 提供详细日志，便于调试

文档

docs/guides 目录中提供了全面的指南：

• error-handling.md：错误类型、处理模式和最佳实践
• security.md：身份验证、访问控制和内容安全
• tool-reference.md：详细的工具文档和示例

如需了解使用 PyGithub MCP 服务的详细信息，请参阅这些指南。

使用示例

议题操作

1. 创建议题

{
  "owner": "username",
  "repo": "repository",
  "title": "Issue Title",
  "body": "Issue description",
  "assignees": ["username1", "username2"],
  "labels": ["bug", "help wanted"],
  "milestone": 1
}

2. 获取议题详情

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1
}

3. 更新议题

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "title": "Updated Title",
  "body": "Updated description",
  "state": "closed",
  "labels": ["bug", "wontfix"]
}

评论操作

1. 添加评论

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "body": "This is a comment"
}

2. 列出评论

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "per_page": 10
}

3. 更新评论

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "comment_id": 123456789,
  "body": "Updated comment text"
}

标签操作

1. 添加标签

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "labels": ["enhancement", "help wanted"]
}

2. 移除标签

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "label": "enhancement"
}

所有操作都会智能处理可选参数：

• API 调用中仅包含已提供的参数
• 将基本类型转换为 GitHub 对象（例如，将里程碑编号转换为 Milestone 对象）
• 为无效参数提供清晰的错误消息
• 在适用时自动处理分页

安装

1. 创建并激活虚拟环境：

uv venv
source .venv/bin/activate

2. 安装依赖项：

uv pip install -e .

配置

基本配置

将服务添加到 MCP 设置中（例如 claude_desktop_config.json 或 cline_mcp_settings.json）：

{
  "mcpServers": {
    "github": {
      "command": "/path/to/repo/.venv/bin/python",
      "args": ["-m", "pygithub_mcp_server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

工具组配置

此服务支持通过配置选择性地启用或禁用工具组。你可以通过两种方式进行配置：

1. 配置文件

创建 JSON 配置文件（例如 pygithub_mcp_config.json）：

{
  "tool_groups": {
    "issues": {"enabled": true},
    "repositories": {"enabled": true},
    "pull_requests": {"enabled": false},
    "discussions": {"enabled": false},
    "search": {"enabled": true}
  }
}

然后在环境中指定此文件：

export PYGITHUB_MCP_CONFIG=/path/to/pygithub_mcp_config.json

2. 环境变量

或者，使用环境变量配置工具组：

export PYGITHUB_ENABLE_ISSUES=true
export PYGITHUB_ENABLE_REPOSITORIES=true
export PYGITHUB_ENABLE_PULL_REQUESTS=false

默认情况下，仅启用 issues 工具组。有关更多配置选项，请参阅 README.config.md。

开发

测试

项目包含全面的测试套件：

# Run all tests
pytest

# Run tests with coverage report
pytest --cov

# Run specific test file
pytest tests/test_operations/test_issues.py

# Run tests matching a pattern
pytest -k "test_create_issue"

注意：目前有许多测试失败，正在调查中。这是一个已知问题，相关工作正在积极推进。

使用 MCP Inspector 测试

在开发期间使用 MCP Inspector 测试 MCP 工具：

source .venv/bin/activate  # Ensure venv is activated
npx @modelcontextprotocol/inspector -e GITHUB_PERSONAL_ACCESS_TOKEN=your-token-here uv run pygithub-mcp-server

使用 MCP Inspector 的 Web UI 来：

• 试用可用工具
• 使用真实的 GitHub 代码库进行测试
• 验证成功和错误情形
• 记录可正常工作的载荷

项目结构

tests/
├── unit/                # Fast tests without external dependencies
│   ├── config/          # Configuration tests
│   ├── tools/           # Tool registration tests
│   └── ...              # Other unit tests
└── integration/         # Tests with real GitHub API
    ├── issues/          # Issue tools tests
    └── ...              # Other integration tests

src/
└── pygithub_mcp_server/
    ├── __init__.py
    ├── __main__.py
    ├── server.py        # Server factory (create_server)
    ├── version.py
    ├── config/          # Configuration system
    │   ├── __init__.py
    │   └── settings.py  # Configuration management
    ├── tools/           # Modular tool system
    │   ├── __init__.py  # Tool registration framework
    │   └── issues/      # Issue tools
    │       ├── __init__.py
    │       └── tools.py # Issue tool implementations
    ├── client/          # GitHub client functionality
    │   ├── __init__.py
    │   ├── client.py    # Core GitHub client
    │   └── rate_limit.py # Rate limit handling
    ├── converters/      # Data transformation
    │   ├── __init__.py
    │   ├── parameters.py # Parameter formatting
    │   ├── responses.py # Response formatting
    │   ├── common/      # Common converters
    │   ├── issues/      # Issue-related converters
    │   ├── repositories/ # Repository converters
    │   └── users/       # User-related converters
    ├── errors/          # Error handling
    │   ├── __init__.py
    │   └── exceptions.py # Custom exceptions
    ├── operations/      # GitHub operations
    │   ├── __init__.py
    │   └── issues.py
    ├── schemas/         # Data models
    │   ├── __init__.py
    │   ├── base.py
    │   ├── issues.py
    │   └── ...
    └── utils/           # General utilities
        ├── __init__.py
        └── environment.py # Environment utilities

故障排除

1. 服务无法启动：

   • 验证 MCP 设置中的 venv Python 路径
   • 确保已在 venv 中安装所有依赖项
   • 检查 GITHUB_PERSONAL_ACCESS_TOKEN 是否已设置且有效

2. 构建错误：

   • 使用 uv build 并添加 --no-build-isolation 标志
   • 确保使用的是 Python 3.10+
   • 验证是否已安装所有依赖项

3. GitHub API 错误：

   • 检查令牌权限及有效性
   • 查看 pygithub_mcp_server.log 以获取详细错误跟踪信息
   • 验证是否超出速率限制

依赖项

• Python 3.10+
• MCP Python SDK
• Pydantic
• PyGithub
• UV 包管理器

许可证

MIT