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

Flujo de ejecución

El usuario realiza una solicitud en lenguaje natural.
El LLM interpreta la intención.
El LLM selecciona la Tool adecuada.
El MCP Server valida los parámetros utilizando Zod.
Se ejecuta la operación correspondiente mediante Octokit.
GitHub API devuelve la respuesta.
El MCP Server transforma la respuesta en un formato amigable para el LLM.

---

Tecnologías Utilizadas

| Tecnología | Propósito | | ------------------ | -------------------------------- | | Node.js | Runtime de ejecución | | TypeScript | Tipado estático | | MCP SDK | Implementación del protocolo MCP | | Octokit | Cliente oficial de GitHub API | | Zod | Validación de esquemas | | Vitest | Testing unitario | | dotenv | Gestión de variables de entorno | | zod-to-json-schema | Conversión de esquemas para MCP |

---

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

Ingresar a GitHub.
Ir a Settings.
Developer Settings.
Personal Access Tokens.
Tokens (Classic).
Generate New Token.
Asignar permisos:

repo
user
admin:org

Copiar el token.
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

| Parámetro | Tipo | | ----------- | ------- | | name | string | | description | string | | private | boolean |

Ejemplo

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

---

create_issue

Crea un Issue en un repositorio.

Parámetros

| Parámetro | Tipo | | --------- | ------ | | owner | string | | repo | string | | title | string | | body | string |

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

| Parámetro | Tipo | | --------- | ------ | | page | number | | per_page | number |

Ejemplo

Muéstrame mis repositorios de GitHub

---

create_commit

Crea o actualiza un archivo realizando un commit.

Parámetros

| Parámetro | Tipo | | --------- | ------ | | owner | string | | repo | string | | path | string | | message | string | | content | string | | branch | string |

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

GitHub Agent MCP Server