# 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

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

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

| 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

```text
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

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

npm install
```

---

# Configuración

## Variables de entorno

Crear un archivo `.env`

```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

```bash
npm run dev
```

Ejecuta el servidor MCP utilizando TSX.

---

## Compilación

```bash
npm run build
```

Compila el proyecto TypeScript.

---

## Testing

```bash
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

```text
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

```text
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

```text
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

```text
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

```text
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

```bash
npm run test
```

---

# Casos de Uso

## Gestión de repositorios

```text
Crea un repositorio privado llamado proyecto-mcp
```

## Gestión de tareas

```text
Abre un issue para corregir el bug de autenticación
```

## Automatización de commits

```text
Agrega un archivo config.json y realiza un commit
```

## Consulta de proyectos

```text
Muéstrame todos mis repositorios
```

---

# Troubleshooting

## GITHUB_TOKEN no configurado

Verificar que exista:

```env
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