Servidor MCP de PyGithub

Un servidor de Protocolo de Contexto de Modelo que proporciona herramientas para interactuar con la API de GitHub a través de PyGithub. Este servidor permite a los asistentes de IA realizar operaciones de GitHub, como la gestión de incidencias, repositorios y solicitudes de extracción.

Características

Arquitectura de herramientas modulares:
- Grupos de herramientas configurables que se pueden habilitar o deshabilitar
- Organización específica del dominio (problemas, repositorios, etc.)
- Configuración flexible mediante archivos o variables de entorno
- Separación clara de preocupaciones con diseño modular
- Fácil extensión con patrones consistentes
Gestión completa de problemas de GitHub:
- Crear y actualizar problemas
- Obtenga detalles del problema y enumere los problemas del repositorio
- Agregar, enumerar, actualizar y eliminar comentarios
- Administrar etiquetas de problemas
- Gestionar asignados y hitos
Manejo inteligente de parámetros:
- Construcción dinámica de kwargs para parámetros opcionales
- Conversión de tipos adecuada para objetos de GitHub
- Validación de todos los parámetros de entrada
- Borrar mensajes de error para entradas no válidas
Implementación robusta:
- Interacciones de la API de GitHub orientadas a objetos a través de PyGithub
- Gestión centralizada de clientes de GitHub
- Manejo adecuado de errores y limitación de velocidad
- Abstracción de API limpia mediante herramientas MCP
- Soporte completo de paginación
- Registro detallado para depuración

Documentación

Hay guías completas disponibles en el directorio docs/guides:

error-handling.md: Tipos de errores, patrones de manejo y mejores prácticas
security.md: Autenticación, control de acceso y seguridad de contenido
tool-reference.md: Documentación detallada de herramientas con ejemplos

Consulte estas guías para obtener información detallada sobre el uso del servidor MCP de PyGithub.

Ejemplos de uso

Operaciones de emisión

Creando un problema

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

Obtener detalles del problema

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

Actualización de un problema

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

Operaciones de comentarios

Agregar un comentario

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

Comentarios del listado

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

Actualizar un comentario

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

Operaciones de etiquetas

Agregar etiquetas

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

Quitar una etiqueta

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

Todas las operaciones manejan parámetros opcionales de forma inteligente:

Solo incluye los parámetros proporcionados en las llamadas API
Convierte tipos primitivos en objetos de GitHub (por ejemplo, número de hito en objeto Milestone)
Proporciona mensajes de error claros para parámetros no válidos
Maneja la paginación automáticamente cuando corresponde

Instalación

Crear y activar un entorno virtual:

uv venv
source .venv/bin/activate

Instalar dependencias:

uv pip install -e .

Configuración

Configuración básica

Agregue el servidor a su configuración de MCP (por ejemplo, claude_desktop_config.json o 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"
      }
    }
  }
}

Configuración del grupo de herramientas

El servidor permite habilitar o deshabilitar grupos de herramientas de forma selectiva mediante la configuración. Puede configurarlo de dos maneras:

1. Archivo de configuración

Cree un archivo de configuración JSON (por ejemplo, pygithub_mcp_config.json ):

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

Luego especifique este archivo en su entorno:

export PYGITHUB_MCP_CONFIG=/path/to/pygithub_mcp_config.json

2. Variables de entorno

Alternativamente, utilice variables de entorno para configurar grupos de herramientas:

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

De forma predeterminada, solo está habilitado el grupo de herramientas issues . Consulte README.config.md para obtener opciones de configuración más detalladas.

Desarrollo

Pruebas

El proyecto incluye un conjunto completo de pruebas:

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

Nota: Muchas pruebas están fallando y se encuentran bajo investigación. Este es un problema conocido en el que se está trabajando activamente.

Pruebas con MCP Inspector

Pruebe las herramientas MCP durante el desarrollo utilizando el 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

Utilice la interfaz web de MCP Inspector para:

Experimente con las herramientas disponibles
Prueba con repositorios reales de GitHub
Verificar casos de éxito y error
Documentar las cargas útiles de trabajo

Estructura del proyecto

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

Solución de problemas

El servidor no se puede iniciar:
- Verificar la ruta de Python de venv en la configuración de MCP
- Asegúrese de que todos los requisitos estén instalados en venv
- Compruebe que GITHUB_PERSONAL_ACCESS_TOKEN esté configurado y sea válido
Errores de compilación:
- Utilice el indicador --no-build-isolation con la compilación uv
- Asegúrese de que se esté utilizando Python 3.10+
- Verificar que todas las dependencias estén instaladas
Errores de la API de GitHub:
- Comprobar los permisos y la validez del token
- Revise pygithub_mcp_server.log para obtener seguimientos de errores detallados
- Verificar que no se hayan excedido los límites de velocidad

Dependencias

Python 3.10+
SDK de Python para MCP
Pydantic
PyGithub
Gestor de paquetes UV

Licencia

Instituto Tecnológico de Massachusetts (MIT)

PyGithub MCP Server

Integrations