GitHub Agent MCP Server

Servidor MCP (Model Context Protocol) desarrollado en Node.js y TypeScript que permite a agentes de IA interactuar con GitHub mediante lenguaje natural.

Descripción

GitHub Agent MCP Server es una implementación de un servidor MCP diseñado para integrarse con herramientas compatibles con Model Context Protocol como Antigravity.

El servidor expone herramientas (Tools) que permiten a un modelo de lenguaje ejecutar operaciones comunes sobre GitHub utilizando la API oficial a través de Octokit.

La solución implementa validación de entradas mediante Zod, manejo de errores, autenticación segura mediante variables de entorno, retry automático con Exponential Backoff y pruebas unitarias utilizando Vitest.

Características

• Creación de repositorios en GitHub.

• Creación de Issues.

• Listado de repositorios del usuario autenticado.

• Creación y actualización de archivos mediante commits.

• Listado de Issues por repositorio.

• Validación robusta de parámetros con Zod.

• Comunicación mediante MCP usando stdio.

• Integración con GitHub API mediante Octokit.

• Reintentos automáticos ante errores temporales de red.

• Testing automatizado con Vitest.

• Configuración mediante variables de entorno.

Arquitectura

graph LR
    Usuario --> Antigravity
    Antigravity --> LLM
    LLM --> MCPServer
    MCPServer --> GitHubAPI

Related MCP server: GitHub MCP Server

Flujo de ejecución

1. El usuario realiza una solicitud en lenguaje natural.

2. El LLM interpreta la intención.

3. El LLM selecciona la Tool adecuada.

4. El MCP Server valida los parámetros utilizando Zod.

5. Se ejecuta la operación correspondiente mediante Octokit.

6. GitHub API devuelve la respuesta.

7. El MCP Server transforma la respuesta en un formato amigable para el LLM.

Tecnologías Utilizadas

Estructura del Proyecto

src/
├── github/
│   ├── client.ts
│   └── operations.ts
│
├── schemas/
│   └── index.ts
│
├── tools/
│   ├── create-repository.ts
│   ├── create-issue.ts
│   ├── create-commit.ts
│   ├── list-repositories.ts
│   └── list-issues.ts
│
├── utils/
│   ├── retry.ts
│   └── logging.ts
│
├── errors/
│   └── index.ts
│
├── server.ts
└── types.ts

tests/
├── tools.test.ts
├── github.test.ts
└── errors.test.ts

Requisitos

• Node.js 18 o superior

• npm

• GitHub Personal Access Token

• MCP Inspector

• Antigravity

Instalación

git clone <repositorio>
cd github-agent-mcp-server

npm install

Configuración

Variables de entorno

Crear un archivo .env

GITHUB_TOKEN=tu_token_de_github

Permisos requeridos

El token debe incluir los siguientes scopes:

• repo

• user

• admin:org

Obtener un GitHub Personal Access Token

1. Ingresar a GitHub.

2. Ir a Settings.

3. Developer Settings.

4. Personal Access Tokens.

5. Tokens (Classic).

6. Generate New Token.

7. Asignar permisos:

   • repo

   • user

   • admin:org

8. Copiar el token.

9. Guardarlo en el archivo .env.

Scripts Disponibles

Desarrollo

npm run dev

Ejecuta el servidor MCP utilizando TSX.

Compilación

npm run build

Compila el proyecto TypeScript.

Testing

npm run test

Ejecuta todas las pruebas unitarias mediante Vitest.

Tools Disponibles

create_repository

Crea un nuevo repositorio en GitHub.

Parámetros

Ejemplo

Crea un repositorio llamado backend-mcp con descripción "Servidor MCP para GitHub"

create_issue

Crea un Issue en un repositorio.

Parámetros

Ejemplo

Crea un issue en mi repositorio api-rest con título "Error de autenticación"

list_repositories

Lista los repositorios del usuario autenticado.

Parámetros

Ejemplo

Muéstrame mis repositorios de GitHub

create_commit

Crea o actualiza un archivo realizando un commit.

Parámetros

Ejemplo

Crea un archivo README.md en mi repositorio y realiza un commit

list_issues

Lista los issues de un repositorio.

Parámetros

| Parámetro | Tipo | | --------- | ------ | ------ | --- | | owner | string | | repo | string | | state | open | closed | all |

Ejemplo

Muéstrame los issues abiertos del repositorio backend-api

Validación de Datos

El proyecto utiliza Zod para validar todos los parámetros recibidos por las Tools.

Algunas reglas implementadas:

• Nombres de repositorio entre 3 y 100 caracteres.

• Restricción de caracteres inválidos.

• Campos obligatorios para creación de Issues.

• Validación de paginación.

• Validación de ramas y archivos para commits.

Los errores de validación son devueltos al usuario mediante mensajes descriptivos.

Manejo de Errores

La aplicación captura errores provenientes de:

• Validaciones inválidas.

• GitHub API.

• Problemas de autenticación.

• Recursos inexistentes.

• Errores temporales de red.

Las respuestas se transforman en mensajes entendibles para el usuario final.

Retry Automático

El proyecto implementa una estrategia de Exponential Backoff con Jitter.

Características:

• Hasta 3 reintentos automáticos.

• Delay incremental.

• Jitter aleatorio para evitar sincronización de peticiones.

• Exclusión de errores permanentes como:

  • 404

  • 422

Testing

El proyecto incluye pruebas unitarias utilizando Vitest.

Cobertura

Schemas

• Validación de repositorios válidos.

• Validación de repositorios inválidos.

• Validación de creación de issues.

Operaciones GitHub

• Creación de repositorios.

• Creación de issues.

• Listado de repositorios.

Manejo de errores

• Simulación de error 404.

• Simulación de errores de red.

• Verificación de respuestas amigables.

Ejecutar pruebas

npm run test

Casos de Uso

Gestión de repositorios

Crea un repositorio privado llamado proyecto-mcp

Gestión de tareas

Abre un issue para corregir el bug de autenticación

Automatización de commits

Agrega un archivo config.json y realiza un commit

Consulta de proyectos

Muéstrame todos mis repositorios

Troubleshooting

GITHUB_TOKEN no configurado

Verificar que exista:

GITHUB_TOKEN=tu_token

Error 403

Causa:

• Token sin permisos suficientes.

Solución:

• Verificar scopes repo, user y admin:org.

Error 404

Causa:

• Repositorio inexistente.

• Owner incorrecto.

Solución:

• Revisar nombre del repositorio.

MCP no aparece en Antigravity

Verificar:

• Configuración del servidor.

• Ruta correcta de ejecución.

• Compilación exitosa.

Mejoras Futuras

• Soporte para Pull Requests.

• Gestión de ramas.

• Eliminación de repositorios.

• Creación de Releases.

• Gestión de Organizations.

• Mayor cobertura de pruebas.

• Logging estructurado.

• Métricas y monitoreo.

Autor

Proyecto desarrollado como parte del Proyecto Integrador 5 de Especialización Backend.

Licencia

MIT License

Copyright (c) 2026