GitHub MCP Server

Servidor MCP en Node.js y TypeScript que permite a un agente compatible ejecutar operaciones sobre GitHub mediante lenguaje natural.

Arquitectura

Usuario -> Antigravity (Host) -> MCP Client -> MCP Server -> Octokit -> GitHub API

Un chatbot mantiene principalmente una conversacion. Un asistente AI ayuda usando capacidades adicionales. Un AI Agent interpreta un objetivo, decide que acciones necesita y utiliza tools para alcanzarlo.

MCP (Model Context Protocol) estandariza la comunicacion entre un Host de IA, un cliente MCP y servidores que exponen tools o fuentes de datos. En este proyecto el transporte es stdio: los mensajes del protocolo usan stdin/stdout y los logs usan stderr.

Related MCP server: GitHub MCP Server

Tecnologias

• Node.js 18 o superior

• TypeScript con strict: true

• @modelcontextprotocol/sdk

• @octokit/rest

• zod

• dotenv

• Vitest

Instalacion

npm install
npm run build

Configuracion

Copia .env.example como .env y completa el token localmente:

GITHUB_TOKEN=tu_token_de_github

.env esta excluido por .gitignore y nunca debe commitearse.

El token debe tener solo los permisos necesarios. Para repositorios privados, los fine-grained tokens deben permitir acceso al repositorio y contenidos/issues segun la operacion. Un PAT clasico puede requerir repo. El permiso user solo es necesario para operaciones de usuario adicionales y admin:org no es necesario para las cinco tools actuales salvo que la organizacion imponga ese escenario. No se incluyen tokens en ejemplos, tests, logs ni respuestas MCP.

Scripts

npm run dev       # Ejecuta TypeScript directamente
npm run build     # Compila a dist/
npm start         # Ejecuta el JavaScript compilado
npm test          # Ejecuta los tests unitarios

Tools MCP

create_repository

Crea un repositorio nuevo en la cuenta autenticada.

Inputs: name, description.

Devuelve el nombre completo y la URL del repositorio.

create_issue

Crea un issue en un repositorio existente.

Inputs: owner, repo, title, body.

Devuelve numero, titulo y URL del issue.

list_repositories

Lista los repositorios del usuario autenticado.

Inputs opcionales: page, per_page.

Devuelve una lista resumida con nombre completo y URL.

create_commit

Crea o actualiza un archivo y genera el commit mediante la Contents API.

Inputs: owner, repo, path, message, content; branch es opcional.

La tool consulta primero el archivo. Si existe, usa su SHA; si GitHub responde 404, crea el archivo sin SHA.

list_issues

Lista los issues abiertos de un repositorio y excluye pull requests.

Inputs: owner, repo; page y per_page son opcionales.

Manejo de errores

Los errores se clasifican como ValidationError, AuthenticationError, GitHubAPIError o NetworkError. Las respuestas MCP contienen mensajes accionables y no reenvian mensajes tecnicos que puedan exponer credenciales.

Las operaciones reintentan hasta tres veces solo ante rate limiting, errores 5xx o errores de red recuperables. Los errores de validacion, autenticacion y recursos inexistentes no se reintentan.

Tests

Los tests no llaman a GitHub real. Usan clientes de Octokit simulados y cubren:

• Schemas validos e invalidos de repositorios e issues.

• Creacion de repositorios e issues.

• Listado de repositorios e issues abiertos.

• Creacion de archivos nuevos.

• Actualizacion de archivos existentes usando SHA.

• Transformacion de errores.

• Retry con backoff.

Ejecuta npm test para correr la suite completa.

MCP Inspector

Compila el proyecto y ejecuta el servidor mediante el Inspector:

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Configura GITHUB_TOKEN en el entorno antes de iniciar el Inspector. Verifica que aparezcan las cinco tools, sus descripciones y schemas. Para una prueba real usa un repositorio de prueba y evita operaciones destructivas.

Antigravity y VS Code

El archivo .vscode/mcp.json contiene una configuracion stdio sin credenciales versionadas. Usa npm run build antes de iniciar el servidor desde el Host. La configuracion ejecuta dist/index.js y toma GITHUB_TOKEN del entorno local.

Para otro Host compatible con MCP, registra el comando equivalente:

{
  "type": "stdio",
  "command": "node",
  "args": ["dist/index.js"],
  "env": { "GITHUB_TOKEN": "${env:GITHUB_TOKEN}" }
}

Comprueba que el Host detecte create_repository, create_issue, list_repositories, create_commit y list_issues.

Estructura

src/
  errors/       Errores clasificados y sanitizacion
  github/       Cliente Octokit y operaciones GitHub
  schemas/      Schemas Zod y tipos inferidos
  tools/        Handlers MCP individuales
  utils/        Retry, logging, respuestas y ensamblado del servidor
  index.ts      Entrada y transporte stdio
tests/          Tests unitarios con mocks

Seguridad

• No hardcodear tokens.

• No commitear .env.

• No imprimir tokens ni headers de autorizacion.

• Mantener logs en stderr para no contaminar el protocolo.

• Aplicar el principio de minimo privilegio al PAT.

• Revisar los cambios antes de ejecutar tools que escriben en GitHub.