GitHub MCP Server

Un proyecto que permite a un asistente de IA comunicarse con GitHub mediante herramientas seguras y estructuradas.

En palabras sencillas: en lugar de que la IA adivine cómo funciona GitHub, este proyecto le ofrece un menú de acciones claro — como "listar mis repos", "mostrar issues abiertos" o "leer un archivo". La IA elige la acción correcta, este servidor habla con GitHub, y la respuesta llega en un formato limpio que la IA puede entender.

¿Qué problema resuelve esto?

Los chatbots son buenos con el lenguaje, pero no tienen acceso automático a tu cuenta de GitHub.

Este proyecto construye un puente:

1. Haces una pregunta en lenguaje natural («Muéstrame los issues abiertos en microsoft/vscode»).

2. Un modelo de IA (a través de Groq) decide qué herramienta de GitHub usar.

3. El servidor MCP ejecuta esa herramienta contra la API real de GitHub.

4. Los resultados se limpian (se normalizan) y se devuelven a la IA.

5. La IA explica el resultado en un lenguaje sencillo y claro.

MCP es el Model Context Protocol. Piénsalo como un enchufe estándar: cualquier cliente de IA compatible puede conectarse a este servidor y usar sus herramientas.

Related MCP server: GitHub MCP Server

Vista general (arquitectura)

You
  ↓
AI Agent (client/agent.py)  ← talks to Groq LLM
  ↓
MCP Server (notebooks/server.py)  ← menu of GitHub tools
  ↓
GitHub Client  ← HTTP calls with your token
  ↓
GitHub REST API
  ↓
GitHub

Regla de diseño (importante)

Las herramientas se mantienen ligeras:

1. Verifican la entrada (¿el nombre del repositorio es válido?).

2. Llaman al cliente de GitHub.

3. Normalizan la respuesta para darle una forma estable.

4. Devuelven esos datos limpios al agente.

Todos los detalles confusos de GitHub quedan dentro de la capa del cliente, no repartidos por las herramientas.

Carpetas del proyecto (para qué sirve cada parte)

Qué puedes hacer con las herramientas

El servidor expone muchas acciones de GitHub. Agrupadas de forma sencilla:

Leer (seguro de explorar)

• Listar tus repositorios

• Obtener detalles de un repositorio

• Listar / obtener issues y pull requests

• Obtener las mediante para una PR (diff)

• Listar ramas, commits y etiquetas

• Buscar código en un repositorio

• Leer el contenido de un archivo

• Listar ejecuciones de flujos de trabajo de GitHub Actions

Escribir modifica GitHub)

• Crear issues, comentarios, pull requests, ramas y etiquetas

• Actualizar issues, añadir/eliminar etiquetas

• Reabrir issues

Destructivo (puede causar problemas — protegido)

Estas necesitan confirmación extra por defecto:

• merge_pull_request

• delete_file

• create_repository

• create_or_update_file

• close_issue

Para estas, el agente normalmente debe:

1. Llamarlas con dry_run=true → solo previsualizar

2. Llamarlas de nuevo con confirm=true → realizar la acción

Puedes hacerlas más o menos estrictas con la configuración de entorno (más abajo).

Respuestas normalizadas (por qué a los agentes les gustan)

Las respuestas de GitHub son enormes y cambian a menudo. Este proyecto devuelve formas estables.

Las herramientas de listado siempre tienen esa pinta:

{
  "count": 20,
  "items": [ ... ],
  "page": 1,
  "per_page": 20,
  "has_next": true,
  "has_prev": false,
  "next_page": 2,
  "prev_page": null,
  "last_page": 5
}

Para obtener la página siguiente, vuelve a llamar a la misma herramienta con page=2 (o page=next_page).

Ejemplo de issue:

{
  "number": 42,
  "title": "Bug in login",
  "state": "open",
  "author": "some-user",
  "labels": ["bug"],
  "comments": 3,
  "html_url": "https://github.com/...",
  "is_pull_request": false
}

Además: get_issues filtra los pull requests (la API de issues de GitHub los mezcla con los issues).

Características de seguridad

Variables de entorno (opcional):

• GITHUB_MCP_DESTRUCTIVE_MODE → confirm / allow / deny

• GITHUB_MCP_DESTRUCTIVE_ALLOWLIST → nombres de herramientas destructivas separados por comas

Recuerda: nunca compartas secretos en los registros.

Registro (para depuración)

El servidor escribe registros JSON solo a stderr.

¿Por qué stderr? MCP usa stdout para el protocolo. Si impriméramos los registros ahí, la conexión con la IA se rompería.

Los registros incluyen cosas como:

• método y ruta de petición

• estado HTTP

• duración

• límite de velocidad restante

Nunca registran:

• tu token de GitHub

• cabeceras Authorization

• valores que parecen secretos (PATs, tokens de tipo bearer, etc.)

Ejemplo de una línea de registro:

{"ts":"2026-08-23T12:00:00+00:00","level":"INFO","event":"github_request","method":"GET","path":"/repos/microsoft/vscode/issues","status_code":200,"duration_ms":120.5}

El agente de IA (client/agent.py)

El agente:

1. Inicia el servidor MCP como un subproceso (notebooks/server.py).

2. Le pide al servidor la lista de herramientas.

3. Envía tu pregunta y las herramientas a Groq.

4. Si Groq quiere usar una herramienta, el agente la llama a través de MCP.

5. Devuelve el resultado de la herramienta a Groq para que dé la respuesta final.

Comandos útiles (desde la carpeta del proyecto, con el entorno virtual activo):

# See all registered tools
python client/agent.py --list-tools

# Only show which tool the AI would pick (no GitHub write)
python client/agent.py --dry-run "list my github repos"

# One real question, then exit
python client/agent.py --once "show open issues for microsoft/vscode"

# Interactive chat
python client/agent.py

# Check tool-picking quality on many sample prompts
python client/test_tool_picking.py

Límites de bucles (opcional):

python client/agent.py --max-rounds 5 --once "..."

O en .env:

AGENT_MAX_TOOL_ROUNDS=8
AGENT_MAX_TOOL_CALLS=16
AGENT_MAX_CONSECUTIVE_ERRORS=3

Variables de entorno

Obligatorias para el servidor MCP

Obligatorias para el agente (chat / selección de herramientas)

Opcionales

Copia .env.example → .env y completa con los valores reales. Consulta la SETUP.md para el tutorial completo.

Tecnologías utilizadas (para los curiosos)

• Python 3.13+ (el proyecto se desarrolló en 3.13)

• MCP (librería mcp) — protocolo de servidor de herramientas

• httpx — cliente HTTP para GitHub

• Pydantic — esquemas / validación

• python-dotenv — cargar .env

• Cliente compatible con OpenAI → Groq para el agente

• Jupyter (opcional) — cuaderno de aprendizaje

Cómo instalarlo y ejecutarlo

Sigue la guía paso a paso:

👉 SETUP.md — instala Python, configura las claves y .env, y prueba tus primeras herramientas.

Versión corta (si ya sabes Python):

cd "path\to\Github-MCP-server"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env
# edit .env with your tokens
python client/agent.py --list-tools
python client/agent.py --once "list my github repos"

Ruta de aprendizaje (recomendada)

1. Lee este README (ya estás aquí)

2. Sigue el SETUP.md hasta que funcione --list-tools

3. Lee docs/ARCHITECTURE_HLD_LLD.md para los flujos de diseño de alto y bajo nivel

4. Prueba --dry-run y --once con preguntas de solo lectura

5. Ejecuta el plan de pruebas manual de 50 escenarios: tests/MANUAL_TESTING_50_SCENARIOS.md

   • Selección aleatoria: python client/run_manual_scenarios.py

6. Abre notebooks/01_github_mcp_server.ipynb para ver cómo se construyó el servidor

7. Solo entonces prueba las herramientas de escritura/destrucción con dry_run y confirm

Solución de problemas (rápida)

Recordatorios de seguridad

• Nunca subas .env a Git.

• Nunca compartas el GITHUB_TOKEN en chats, capturas de pantalla o issues.

• Usa un token de GitHub con solo los permisos necesarios.

• Mantén GITHUB_MCP_DESTRUCTIVE_MODE=confirm o deny salvo en un entorno completamente confiable.

• Evita publicar salida de depuración de server_1.py que pueda contener datos antiguos; usa server.py.

Licencia / propiedad

Este es un proyecto personal/de aprendizaje de IA generativa para un servidor MCP de GitHub y un agente de chat. Ajusta la propiedad y la licencia según tus necesidades antes de publicarlo de forma pública.# GitHub MCP Server

Un proyecto que permite a un asistente de IA comunicarse con GitHub usando herramientas seguras y estructuradas.

En palabras sencillas: en lugar de que la IA adivine cómo funciona GitHub, este proyecto le ofrece un menú de acciones claro — como "listar mis repositorios", "mostrar los issues abiertos" o "leer un archivo". La IA elige la acción correcta, este servidor conversa con GitHub y la respuesta regresa en un formato limpio que la IA puede entender.

¿Qué problema resuelve?

Los bots de chat son buenos con el lenguaje, pero no tienen acceso automático en vivo a tu cuenta de GitHub.

Este proyecto construye un puente:

1. Haces una pregunta en inglés normal ("Mostrar issues abiertos en microsoft/vscode").

2. Un modelo de IA (a través de Groq) decide qué herramienta de GitHub usar.

3. El servidor MCP ejecuta esa herramienta contra la API real de GitHub.

4. Los resultados se limpian (se normalizan) y se devuelven a la IA.

5. La IA te explica el resultado en un lenguaje sencillo.

MCP significa Model Context Protocol. Piénsalo como un enchufe estándar: cualquier cliente de IA compatible puede conectarse a este servidor y usar sus herramientas.

Visión general (arquitectura)

You
  ↓
AI Agent (client/agent.py)  ← talks to Groq LLM
  ↓
MCP Server (notebooks/server.py)  ← menu of GitHub tools
  ↓
GitHub Client  ← HTTP calls with your token
  ↓
GitHub REST API
  ↓
GitHub

Regla de diseño (importante)

Las herramientas se mantienen delgadas:

1. Verificar la entrada (¿el nombre del repositorio es válido?).

2. Llamar al cliente de GitHub.

3. Normalizar la respuesta a una forma estable.

4. Devolver esos datos limpios al agente.

Todos los detalles desordenados de GitHub permanecen dentro de la capa del cliente, no dispersos entre las herramientas.

Carpetas del proyecto (para qué sirve cada parte)

Qué puedes hacer con las herramientas

El servidor expone muchas acciones de GitHub. Agrupadas de manera sencilla:

Leer (seguro para explorar)

• Listar tus repositorios

• Obtener detalles de un repositorio

• Listar / obtener issues y solicitudes de cambio

• Obtener diferencias de PR

• Listar ramas, commits, etiquetas

• Buscar código en un repositorio

• Leer el contenido de archivos

• Listas de ejecuciones de flujo de trabajo de GitHub Actions

Escribir (cambia GitHub)

• Crear issues, comentarios, PRs, ramas, etiquetas

• Actualizar issues, agregar/eliminar etiquetas

• Reabrir issues

Destructivas (pueden dañar cosas — protegidas)

Estas requieren confirmación adicional por defecto:

• merge_pull_request

• delete_file

• create_repository

• create_or_update_file

• close_issue

Para estas, el agente normalmente debería:

1. Llamar con dry_run=true → solo avance

2. Llamar de nuevo con confirm=true → hacerlo de verdad

Puedes ajustar esto con la configuración de entorno (consulta más abajo).

Respuestas normalizadas (por qué los agentes la prefieren)

Las respuestas de GitHub son gigantes y cambian a menudo. Este proyecto devuelve formas estables.

Las herramientas de listado siempre se ven así:

{
  "count": 20,
  "items": [ ... ],
  "page": 1,
  "per_page": 20,
  "has_next": true,
  "has_prev": false,
  "next_page": 2,
  "prev_page": null,
  "last_page": 5
}

Para obtener la siguiente página, llama nuevamente a la misma herramienta con page=2 (o page=next_page).

Ejemplo de issue:

{
  "number": 42,
  "title": "Bug in login",
  "state": "open",
  "author": "some-user",
  "labels": ["bug"],
  "comments": 3,
  "html_url": "https://github.com/...",
  "is_pull_request": false
}

Además: get_issues filtra los pull requests (la API de issues de GitHub los mezcla).

Características de seguridad

Variables de entorno (opcionales):

GITHUB_MCP_DESTRUCTIVE_MODE=confirm
GITHUB_MCP_DESTRUCTIVE_ALLOWLIST=merge_pull_request,delete_file

Registro (para depurar)

El servidor escribe registros JSON solo en stderr.

`¿Por qué no hacerlo en stdout? MCP** usa stdout para el protocolo. Si imprimiéramos logs ahí, la conexión de la IA se rompería.

Los registros que incluyen cosas como:

• método y ruta de la solicitud

• estado HTTP

• duración

• límite de velocidad restante

Nunca registran:

• tu token de GitHub

• cabeceras de Authorization

• valores que parecen secretos (PAT, tokens de portador, etc.)

Ejemplo de línea de registro:

{"ts":"2026-08-23T12:00:00+00:00","level":"INFO","event":"github_request","method":"GET","path":"/repos/microsoft/vscode/issues","status_code":200,"duration_ms":120.5}

El agente de IA (client/agent.py)

El agente:

1. Inicia el servidor MCP como subproceso (notebooks/server.py).

2. Pide al servidor la lista de herramientas.

3. Envía tu pregunta + herramientas a Groq.

4. Si Groq quiere una herramienta, el agente la llama mediante MCP.

5. Envía el resultado de la herramienta a Groq para una respuesta final.

Comandos útiles (desde la carpeta del proyecto, con el entorno virtual activo):

# See all registered tools
python client/agent.py --list-tools

# Only show which tool the AI would pick (no GitHub write)
python client/agent.py --dry-run "list my github repos"

# One real question, then exit
python client/agent.py --once "show open issues for microsoft/vscode"

# Interactive chat
python client/agent.py

# Check tool-picking quality on many sample prompts
python client/test_tool_picking.py

Límites de bucle (opcionales):

python client/agent.py --max-rounds 5 --once "..."

O en .env:

AGENT_MAX_TOOL_ROUNDS=8
AGENT_MAX_TOOL_CALLS=16
AGENT_MAX_CONSECUTIVE_ERRORS=3

Variables de entorno

Requeridas para el servidor MCP

Requeridas para el agente (chat / selección de herramientas)

| Variable | Propósito | | | ---------------- | --------------------------------- | | GROQ_API_KEY | Clave de API para Groq (LLM) |

Opcionales

copia .env.example → .env y rellena con valores reales. Consulte SETUP.md para el instrucciones completas.

Stack técnico (para los curiosos)

• Python 3.13+ (el proyecto se desarrolló en la 3.13)

• MCP (mcp paquete de Python) — protocolo de servidor de herramientas

• httpx — cliente HTTP para GitHub

• Pydantic — esquemas / validación

• python-dotenv — cargar .env

• Cliente compatible con OpenAI → Groq para el agente

• Jupyter (opcional) — cuaderno de aprendizaje

Cómo configurar y ejecutar

Sigue la guía paso a paso:

👉 SETUP.md — instala Python, crea claves, configura .env y ejecuta tus primeros comandos.

Versión corta (si ya sabes Python):

cd "path\to\Github-MCP-server"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env
# edit .env with your tokens
python client/agent.py --list-tools
python client/agent.py --once "list my github repos"

ruta de aprendizaje (recomendada)

1. leer este README (estás aquí).

2. completar SETUP.md hasta que funcione --list-tools.

3. consulta docs/ARCHITECTURE_HLD_LLD.md para los flujos de ALTA + diseño de bajo nivel.

4. prueba --dry-compete y --once con preguntas sencillas de solo lectura.

5. Ejecuta el plan de pruebas manual de 50 escenarios: tests/MANUAL_TESTING_50_SCENARIOS.md

   • Selección automática: python client/run_manual_scenarios.py

6. Abre notebooks/01_github_mcp_server.ipynb para ver cómo se construyó cada salida capa.

7. Solo después intenta probar métodos de escritura/destructivos con dry_run + confirm.

Soluciones de problemas (rápidas)

Recordatorios de seguridad

• Nunca guardes .env.

• Nunca pegues tus tokens de GitHub o Groq en chats, capturas de pantalla o issues de GitHub.

• Prefiere un token de GitHub con solo los permisos que necesitas.

• mantén GITHUB_MCP_DESTRUCTIVE_MODE=confirm (o deny) a menos que el entorno sea totalmente de confianza.

• No comparta la salida de depuración de server_1.py si alguna vez imprimió tokens en experimentos antiguos — usa server.py.

Licencia / propiedad

Este es un proyecto personal / de aprendizaje de IA Gen para un GitHub MCP Server / una agencia. Ajusta la propiedad y la licencia; prepáralo antes de publicarlo.