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

  • 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

• 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

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

1. Clonar el repositorio:

   git clone https://github.com/cyanheads/github-mcp-server.git cd github-mcp-server

2. Instalar dependencias:

   npm install

3. 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

4. Construir el proyecto:

   npm run build

5. Iniciar el servidor:

   node build/index.js

Configuración

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

Configuración del cliente MCP

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

Estructura del proyecto

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

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

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

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.

1. Bifurcar el repositorio

2. Crea tu rama de funciones ( git checkout -b feature/amazing-feature )

3. Confirme sus cambios ( git commit -m 'Add some amazing feature' )

4. Empujar a la rama ( git push origin feature/amazing-feature )

5. Abrir una solicitud de extracción

Licencia

Licencia Apache 2.0