Servidor MCP de GitHub

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona herramientas para interactuar con la API de GitHub. Este servidor permite a los agentes LLM gestionar repositorios, incidencias, solicitudes de incorporación de cambios, ramas, archivos y versiones de GitHub mediante una interfaz estandarizada.

Tabla de contenido

Descripción general
- Arquitectura y componentes
Características
Instalación
- Prerrequisitos
- Configuración
Configuración
Estructura del proyecto
Herramientas
Desarrollo
- Estructura del proyecto
- Guiones
Manejo de errores
Contribuyendo
Licencia

Descripción general

github-mcp-server implementa el Protocolo de Contexto de Modelo (MCP), lo que permite una comunicación estandarizada entre LLM y sistemas externos a través de:

Clientes : Claude Desktop, IDE y otros clientes compatibles con MCP
Servidores : Herramientas y recursos para la gestión de proyectos y la colaboración
Agentes LLM : modelos de IA que aprovechan la capacidad de realizar operaciones de GitHub mediante programación.

Actúa como un puente entre los modelos de IA y la API de GitHub, ofreciendo un conjunto de herramientas bien definidas que siguen patrones consistentes y manejan la autenticación, la validación, el manejo de errores y la limitación de velocidad.

Capacidades clave:

Integración de la API de GitHub : integración segura y perfecta con la API REST de GitHub
Funciones completas de GitHub : gestión completa de repositorios, ramas, problemas, solicitudes de incorporación de cambios y más
Arquitectura de características atómicas : Estructura de código modular bien organizada para facilitar el mantenimiento
Validación de entrada : validación robusta con esquemas Zod para todas las operaciones
Manejo de errores : categorización y generación de informes de errores consistentes
Limitación de velocidad : gestión de límite de velocidad de la API de GitHub integrada
Enfoque en el rendimiento : Operaciones optimizadas y formato de respuesta

Arquitectura y componentes

Arquitectura del sistema central:

Componentes principales:

Capa de protocolo MCP : gestiona la comunicación con los asistentes de IA
Capa de validación : garantiza la integridad de los datos mediante la validación del esquema.
Servicio GitHub : Integración principal con la API REST de GitHub
Limitador de velocidad : evita que se agote el límite de velocidad de la API
Módulos de funciones : Operaciones de GitHub específicas del dominio
Manejo de errores : sistema integral de registro y manejo de errores

Características

Gestión de repositorios

Crear, enumerar, obtener : cree nuevos repositorios, enumere repositorios de usuarios y obtenga información detallada del repositorio
Validación y configuración : validar la configuración del repositorio y administrar las opciones de configuración

Gestión de sucursales

Crear, eliminar, enumerar : gestión completa del ciclo de vida de las sucursales con validación segura
Soporte para ramas protegidas : filtrado y operaciones para ramas protegidas

Gestión de problemas

Crear y listar : crea problemas detallados con etiquetas y enumera problemas con opciones de filtrado
Seguimiento de estado : Filtrar por estado del problema (abierto, cerrado, todos)

Gestión de solicitudes de extracción

Crear, actualizar, fusionar, enumerar : gestión completa del ciclo de vida de las solicitudes de extracción
Integración de revisiones y comentarios : agregue revisiones y comentarios a las solicitudes de extracción
Opciones de fusión : Compatibilidad con diferentes estrategias de fusión (fusión, squash, rebase)

Gestión de archivos

Crear y actualizar archivos : agregue y modifique el contenido del repositorio con mensajes de confirmación
Compatibilidad con codificación Base64 : maneja contenido de archivos tanto de texto como binarios

Gestión de versiones

Crear lanzamientos : crea lanzamientos etiquetados con opciones personalizables
Soporte para borradores y prelanzamientos : Soporte para flujos de trabajo de borradores y prelanzamientos

Instalación

Prerrequisitos

Node.js (v16 o más reciente)
Un token de acceso personal de GitHub con los permisos adecuados

Configuración

Clonar el repositorio:
git clone https://github.com/cyanheads/github-mcp-server.git cd github-mcp-server
Instalar dependencias:
npm install
Crea un archivo .env en la raíz del proyecto con tu token de GitHub:
GITHUB_TOKEN=your_github_personal_access_token LOG_LEVEL=info SERVER_NAME=github-mcp-server
Construir el proyecto:
npm run build
Iniciar el servidor:
node build/index.js

Configuración

El servidor se puede configurar a través de variables de entorno:

Variable de entorno	Descripción	Por defecto
`GITHUB_TOKEN`	Token de acceso personal de GitHub (obligatorio)	-
`LOG_LEVEL`	Nivel de registro (depuración, información, advertencia, error, fatal)	información
`SERVER_NAME`	Nombre del servidor MCP	servidor github-mcp
`SERVER_VERSION`	Versión del servidor MCP	0.1.0
`API_TIMEOUT_MS`	Tiempo de espera para llamadas API en milisegundos	10000
`RATE_LIMITING_ENABLED`	Si la limitación de velocidad está habilitada	verdadero
`RATE_LIMITING_MIN_REMAINING`	Solicitudes mínimas restantes antes de la limitación	100
`RATE_LIMITING_RESET_BUFFER_MS`	Amortiguador de tiempo para agregar al tiempo de restablecimiento del límite de velocidad	5000

Configuración del cliente MCP

Añade a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/path/to/github-mcp-server/build/index.js"],
      "env": {
        "GITHUB_TOKEN": "your_github_personal_access_token",
        "LOG_LEVEL": "info",
        "SERVER_NAME": "github-mcp-server"
      }
    }
  }
}

Estructura del proyecto

Este proyecto sigue un patrón de arquitectura orientado a características atómicas:

/src
  /configuration             // Application configuration
  /dependencyInjection       // Tool registry and DI container
  /features                  // Feature modules organized by domain
    /repositoryManagement
      /resources             // Read operations
      /modifications         // Write operations
    /branchManagement
    /issueManagement
    /pullRequestManagement
    /fileManagement
    /releaseManagement
  /services                  // External service integrations
    /githubAccess            // GitHub API client and utilities
  /types                     // Core type definitions
  /utilities                 // Helper functions and utilities

Cada dominio de características se divide en:

Recursos : Operaciones de lectura que no modifican datos
Modificaciones : escribe operaciones que crean, actualizan o eliminan datos.

Cada operación está contenida en su propio directorio con:

Archivo de implementación de la operación
Archivo de definiciones de tipos
Exportar archivo de índice

Herramientas

GitHub MCP Server proporciona un conjunto completo de herramientas para interactuar con GitHub:

Herramientas de gestión de repositorios

Herramienta	Descripción
`get_repository`	Obtenga información detallada sobre un repositorio específico. Parámetros: `owner` , `repo`
`list_repositories`	Lista de repositorios para el usuario autenticado. Parámetros: `type` (opcional), `sort` (opcional).
`create_repository`	Crear un nuevo repositorio de GitHubParámetros: `name` , `description` (opcional), `private` (opcional)

Herramientas de gestión de sucursales

Herramienta	Descripción
`list_branches`	Listar ramas en un repositorioParámetros: `owner` , `repo` , `protected` (opcional), `per_page` (opcional)
`create_branch`	Crear una nueva ramaParámetros: `owner` , `repo` , `branch` , `sha`
`delete_branch`	Eliminar una ramaParámetros: `owner` , `repo` , `branch`

Herramientas de gestión de problemas

Herramienta	Descripción
`create_issue`	Crear un nuevo problema en un repositorioParámetros: `owner` , `repo` , `title` , `body` (opcional), `labels` (opcional)
`list_issues`	Enumerar problemas en un repositorioParámetros: `owner` , `repo` , `state` (opcional), `labels` (opcional)

Herramientas de gestión de solicitudes de extracción

Herramienta	Descripción
`create_pull_request`	Crear una nueva solicitud de extracción Parámetros: `owner` , `repo` , `title` , `head` , `base` , `body` (opcional)
`merge_pull_request`	Fusionar una solicitud de extracción Parámetros: `owner` , `repo` , `pull_number` , `commit_title` (opcional), `commit_message` (opcional), `merge_method` (opcional)
`update_pull_request`	Actualizar una solicitud de extracción existenteParámetros: `owner` , `repo` , `pull_number` , `title` (opcional), `body` (opcional), `state` (opcional), `base` (opcional), `maintainer_can_modify` (opcional)
`list_pull_requests`	Enumerar solicitudes de extracción en un repositorioParámetros: `owner` , `repo` , `state` (opcional), `head` (opcional), `base` (opcional), `sort` (opcional), `direction` (opcional)

Herramientas de gestión de archivos

Herramienta	Descripción
`update_file`	Crear o actualizar un archivo en un repositorioParámetros: `owner` , `repo` , `path` , `message` , `content` , `sha` (opcional), `branch` (opcional)

Herramientas de gestión de versiones

Herramienta	Descripción
`create_release`	Crear un nuevo lanzamientoParámetros: `owner` , `repo` , `tag_name` , `name` (opcional), `body` (opcional), `draft` (opcional), `prerelease` (opcional)

Desarrollo

Estructura del proyecto

El proyecto sigue estrictas convenciones de nomenclatura y estructura de directorio:

Nombre de archivo: action.entity.type.ts (por ejemplo, create.repository.operation.ts )
Cada módulo tiene un propósito claramente definido
Los tipos se ubican junto con su implementación.
Todas las exportaciones se centralizan a través de archivos de índice

Guiones

npm run build - Construir el proyecto
npm run watch : vigila los cambios y reconstruye
npm run inspector : ejecuta la herramienta de inspección MCP
npm run clean : limpieza de artefactos de compilación
npm run rebuild : limpia y reconstruye el proyecto
npm run tree : genera una representación del árbol de directorios

Manejo de errores

El servidor implementa una estrategia integral de manejo de errores:

Objetos de error estandarizados : formato de error consistente con categorización
Validación de entrada : prevalidación mediante esquemas Zod
Protección de limitación de velocidad : gestión automática de los límites de velocidad de la API de GitHub
Categorías de errores :
- Errores de red (problemas de conectividad)
- Errores de autenticación (problemas con el token)
- Errores de validación (entrada no válida)
- Errores de la API de GitHub (problemas específicos de la API)
- Errores del sistema (fallos inesperados)
Registro detallado : registro estructurado de todas las operaciones y errores

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

Bifurcar el repositorio
Crea tu rama de funciones ( git checkout -b feature/amazing-feature )
Confirme sus cambios ( git commit -m 'Add some amazing feature' )
Empujar a la rama ( git push origin feature/amazing-feature )
Abrir una solicitud de extracción

Licencia

Licencia Apache 2.0

Integrations

Servidor MCP de GitHub

Tabla de contenido

Descripción general

Arquitectura y componentes

Características

Gestión de repositorios

Gestión de sucursales

Gestión de problemas

Gestión de solicitudes de extracción

Gestión de archivos

Gestión de versiones

Instalación

Prerrequisitos

Configuración

Configuración

Configuración del cliente MCP

Estructura del proyecto

Herramientas

Herramientas de gestión de repositorios

Herramientas de gestión de sucursales

Herramientas de gestión de problemas

Herramientas de gestión de solicitudes de extracción

Herramientas de gestión de archivos

Herramientas de gestión de versiones

Desarrollo

Estructura del proyecto

Guiones

Manejo de errores

Contribuyendo

Licencia