PyGithub MCP Server

Interaja com a API do GitHub usando PyGithub para gerenciar repositórios, issues e pull requests.

GitHub
1
Experimente este MCPPatrocinado

Documentação

Servidor MCP PyGithub

Um servidor Model Context Protocol que fornece ferramentas para interagir com a API do GitHub por meio do PyGithub. Este servidor permite que assistentes de IA executem operações do GitHub, como gerenciar issues, repositórios e pull requests.

Recursos

  • Arquitetura de Ferramentas Modular:

    • Grupos de ferramentas configuráveis que podem ser habilitados/desabilitados
    • Organização por domínio específico (issues, repositórios, etc.)
    • Configuração flexível por meio de arquivo ou variáveis de ambiente
    • Separação clara de responsabilidades com design modular
    • Extensão fácil com padrões consistentes

  • Gerenciamento Completo de Issues do GitHub:

    • Criar e atualizar issues
    • Obter detalhes de issues e listar issues do repositório
    • Adicionar, listar, atualizar e excluir comentários
    • Gerenciar rótulos de issues
    • Lidar com responsáveis e marcos

  • Tratamento Inteligente de Parâmetros:

    • Construção dinâmica de kwargs para parâmetros opcionais
    • Conversão adequada de tipos para objetos do GitHub
    • Validação de todos os parâmetros de entrada
    • Mensagens de erro claras para entradas inválidas

  • Implementação Robusta:

    • Interações com a API do GitHub orientadas a objetos via PyGithub
    • Gerenciamento centralizado do cliente GitHub
    • Tratamento adequado de erros e limitação de taxa
    • Abstração limpa da API por meio de ferramentas MCP
    • Suporte abrangente a paginação
    • Registro detalhado para depuração

Documentação

Guias abrangentes estão disponíveis no diretório docs/guides:

  • error-handling.md: Tipos de erro, padrões de tratamento e melhores práticas
  • security.md: Autenticação, controle de acesso e segurança de conteúdo
  • tool-reference.md: Documentação detalhada das ferramentas com exemplos

Consulte esses guias para obter informações detalhadas sobre o uso do Servidor MCP PyGithub.

Exemplos de Uso

Operações com Issues

  1. Criando uma Issue
{
  "owner": "username",
  "repo": "repository",
  "title": "Issue Title",
  "body": "Issue description",
  "assignees": ["username1", "username2"],
  "labels": ["bug", "help wanted"],
  "milestone": 1
}
  1. Obtendo Detalhes da Issue
{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1
}
  1. Atualizando uma Issue
{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "title": "Updated Title",
  "body": "Updated description",
  "state": "closed",
  "labels": ["bug", "wontfix"]
}

Operações com Comentários

  1. Adicionando um Comentário
{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "body": "This is a comment"
}
  1. Listando Comentários
{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "per_page": 10
}
  1. Atualizando um Comentário
{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "comment_id": 123456789,
  "body": "Updated comment text"
}

Operações com Rótulos

  1. Adicionando Rótulos
{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "labels": ["enhancement", "help wanted"]
}
  1. Removendo um Rótulo
{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "label": "enhancement"
}

Todas as operações lidam com parâmetros opcionais de forma inteligente:

  • Inclui apenas os parâmetros fornecidos nas chamadas de API
  • Converte tipos primitivos em objetos do GitHub (por exemplo, número do marco em objeto Milestone)
  • Fornece mensagens de erro claras para parâmetros inválidos
  • Lida com paginação automaticamente quando aplicável

Instalação

  1. Crie e ative um ambiente virtual:
uv venv
source .venv/bin/activate
  1. Instale as dependências:
uv pip install -e .

Configuração

Configuração Básica

Adicione o servidor às suas configurações do MCP (por exemplo, claude_desktop_config.json ou 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"
      }
    }
  }
}

Configuração de Grupos de Ferramentas

O servidor suporta habilitar ou desabilitar seletivamente grupos de ferramentas por meio da configuração. Você pode configurar isso de duas maneiras:

1. Arquivo de Configuração

Crie um arquivo de configuração JSON (por exemplo, pygithub_mcp_config.json):

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

Em seguida, especifique este arquivo no seu ambiente:

export PYGITHUB_MCP_CONFIG=/path/to/pygithub_mcp_config.json

2. Variáveis de Ambiente

Alternativamente, use variáveis de ambiente para configurar grupos de ferramentas:

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

Por padrão, apenas o grupo de ferramentas issues está habilitado. Consulte README.config.md para opções de configuração mais detalhadas.

Desenvolvimento

Testes

O projeto inclui uma suíte de testes abrangente:

# 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"

Observação: Muitos testes estão falhando atualmente e sob investigação. Este é um problema conhecido que está sendo trabalhado ativamente.

Testes com o MCP Inspector

Teste as ferramentas MCP durante o desenvolvimento usando o MCP Inspector:

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

Use a interface web do MCP Inspector para:

  • Experimentar as ferramentas disponíveis
  • Testar com repositórios reais do GitHub
  • Verificar casos de sucesso e erro
  • Documentar payloads funcionais

Estrutura do Projeto

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

Solução de Problemas

  1. O servidor não inicia:

    • Verifique o caminho do Python do venv nas configurações do MCP
    • Garanta que todos os requisitos estejam instalados no venv
    • Verifique se GITHUB_PERSONAL_ACCESS_TOKEN está definido e é válido

  2. Erros de build:

    • Use a flag --no-build-isolation com uv build
    • Garanta que Python 3.10+ esteja sendo usado
    • Verifique se todas as dependências estão instaladas

  3. Erros da API do GitHub:

    • Verifique as permissões e a validade do token
    • Revise pygithub_mcp_server.log para rastreamentos detalhados de erros
    • Verifique se os limites de taxa não foram excedidos

Dependências

  • Python 3.10+
  • SDK Python do MCP
  • Pydantic
  • PyGithub
  • Gerenciador de pacotes UV

Licença

MIT