Servidor MCP de Gestión de Proyectos GitHub

Servidor MCP (Model Context Protocol) personalizado que permite a los asistentes de IA gestionar programáticamente tableros de GitHub Project V2 mediante el Model Context Protocol. Construido con Python 3.12 y FastMCP, se comunica a través del transporte stdio y se ejecuta dentro de un contenedor Docker independiente.

Ubicación

project/
├── mcp/                    ← This directory (root-level, independent of the app)
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── server.py           # FastMCP entry point
│   ├── config.py
│   ├── auth.py
│   ├── capabilities.py     # Tool → permission mapping
│   ├── profiles.py         # Multi-target profile system
│   ├── tools/              # MCP tool definitions
│   ├── services/           # Business logic
│   ├── clients/            # GraphQL + gh CLI clients
│   ├── models/             # Pydantic models
│   ├── graphql/            # Query/mutation strings
│   ├── tests/              # Unit + contract tests
│   ├── scripts/            # Validation, preflight, secret scanning
│   │   ├── validate.sh     # ← Run before every push
│   │   ├── preflight.sh    # Environment prerequisites
│   │   ├── scan_secrets.sh # Token pattern detection
│   │   └── smoke_build.sh  # Minimal build verification
│   ├── profiles/           # Target config (.env files, no secrets)
│   ├── docs/               # Detailed documentation
│   ├── LICENSE             # MIT
│   ├── CONTRIBUTING.md
│   └── SECURITY.md

Nota: Este servidor MCP es un componente independiente con su propio Dockerfile, dependencias y ciclo de vida.

Related MCP server: GitHub Projects MCP Server

Cómo Funciona

MCP Client → docker run --rm -i github-project-mcp:latest → stdin/stdout JSON-RPC → GitHub API

1. El cliente MCP invoca una herramienta (ej: create_project_item)

2. Se ejecuta docker run --rm -i github-project-mcp:latest python server.py

3. El servidor valida la autenticación y espera comandos por stdin

4. El cliente envía JSON-RPC por stdin y recibe respuestas por stdout

5. Al finalizar, el contenedor se destruye automáticamente (--rm)

Docker — Construir y Gestionar

Construir la imagen

# Desde la raíz del proyecto
docker build -t github-project-mcp:latest ./mcp

Docker Compose (desarrollo local)

La forma más sencilla de configurar y ejecutar el MCP localmente:

# 1. Crear tu configuración local (una sola vez)
cp mcp/.env.example mcp/.env
# Editar mcp/.env con tu GITHUB_TOKEN y target (org/repo/project)

# 2. Construir y verificar
cd mcp/
make build
make verify

Objetivos de Makefile

Todos los objetivos se ejecutan dentro de Docker — sin dependencias del host.

cd mcp/
make help         # Mostrar todos los targets disponibles
make build        # Construir imagen Docker
make verify       # Validar auth + scopes + config
make test         # Ejecutar unit tests
make validate     # CI completo (build + syntax + tests + tools + secrets)
make tools        # Contar herramientas registradas (>= 100)
make syntax       # Verificar sintaxis Python
make secrets      # Escanear credenciales en código
make shell        # Shell interactivo dentro del contenedor
make clean        # Eliminar imágenes

Nota: Si make no está disponible en el host, los objetivos pueden invocarse directamente con Docker. Ejemplo: docker run --rm --env-file .env github-project-mcp:latest python3 scripts/verify_setup.py

Cada colaborador clona el repositorio, crea su .env, y el MCP funciona sin instalar nada más que Docker.

Verificar que la imagen existe

docker images | grep github-project-mcp

Probar manualmente (prueba de humo)

docker run --rm -i \
  -e GITHUB_TOKEN="<your_token>" \
  github-project-mcp:latest \
  python server.py

El servidor imprimirá en stderr: github-project-management MCP server ready. Authentication validated successfully. Luego espera JSON-RPC por stdin. Pulsa Ctrl+C para salir.

Reconstruir después de cambios

docker build -t github-project-mcp:latest ./mcp --no-cache

Script de gestión

El script ./scripts/dev/start.sh admite un argumento mcp para gestionar la imagen:

./scripts/dev/start.sh mcp build      # Construir/reconstruir la imagen
./scripts/dev/start.sh mcp test       # Ejecutar smoke test
./scripts/dev/start.sh mcp status     # Verificar si la imagen existe

Nota: El MCP no es un servicio persistente. No necesita up/down/restart. Se lanza bajo demanda cada vez que el cliente utiliza una herramienta.

Integración con IDE

El MCP es compatible con cualquier cliente que admita el protocolo MCP sobre stdio. La configuración varía según el IDE — el patrón general es:

{
  "mcpServers": {
    "github-project-management": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GITHUB_TOKEN",
        "--env-file", "mcp/.env",
        "github-project-mcp:latest",
        "python", "server.py"
      ]
    }
  }
}

Para la configuración específica por IDE, consulta docs/SETUP.md.

Herramientas Registradas (100)

Operaciones Principales

Gestión de Issues

Operaciones de Tablero

Planificación y Flujos de Trabajo

Metadatos

Arquitectura

Tool Layer (FastMCP tool definitions)
    ↓
Service Layer (business logic, orchestration)
    ↓
Client Layer (GraphQL + gh CLI + caching)
    ↓
GitHub APIs (GraphQL v4 + REST v3)

Estrategia de Delegación

Variables de Entorno

Solución de Problemas

El MCP no conecta

# Verificar que la imagen existe
docker images | grep github-project-mcp

# Si no existe, construir
docker build -t github-project-mcp:latest ./mcp

# Verificar token
echo $GITHUB_TOKEN | head -c 20

Reconectar MCP

Si el MCP se desconecta del IDE, utiliza la opción de reconexión del cliente MCP correspondiente.

Error de autenticación

• Verificar que GITHUB_TOKEN está disponible en el entorno del contenedor

• Los tokens github_pat_* (de grano fino) necesitan permisos: Issues (RW), Projects (RW), Metadata (R)

• Los tokens clásicos necesitan scopes: repo, project, read:org

Documentación Relacionada

Ubicaciones de origen y sincronización

Este directorio (mcp/) es la fuente canónica de verdad para el paquete MCP.

El repositorio contiene una copia sincronizada en:

• app/backend/app/mcp/github_project/ — integrada en el backend para las compilaciones de Docker

Flujo de sincronización

1. Realiza todos los cambios aquí en mcp/ primero.

2. Copia los archivos modificados a la ruta integrada:

   cp mcp/<file> app/backend/app/mcp/github_project/<file>

3. Verifica con la comprobación automatizada:

   ./mcp/scripts/check_sync.sh

El script de sincronización compara todos los archivos .py compartidos (excluyendo __init__.py, que es intencionadamente diferente en la copia del backend, y archivos solo de infraestructura como Dockerfile y requirements.txt). CI ejecuta esta comprobación en cada push — la divergencia hace fallar la compilación.

Archivos intencionadamente diferentes en la copia del backend

El conjunto de pruebas del backend ejercita la copia integrada; la validación de sintaxis debe compilar ambos árboles.

Comportamiento de ejecución reforzado

Todos los ajustes utilizan el prefijo GH_PROJECT_ y se validan al inicio:

La caché de metadatos se escribe de forma atómica, utiliza permisos solo para el propietario (0600), rechaza marcas de tiempo futuras y no se reutiliza cuando la organización o el número de proyecto difieren. Los diagnósticos de CLI y GraphQL redactan valores similares a tokens y están limitados antes de devolverse al cliente MCP.

Validación solo con Docker

Ejecuta la validación sin herramientas de Python en el host:

# Compile both source copies through a Python container
tar -C . -cf - mcp app/backend/app/mcp \
  | docker run --rm -i python:3.12-slim sh -c \
    'mkdir -p /tmp/factib && tar -xf - -C /tmp/factib && \
     python -m compileall -q /tmp/factib/mcp /tmp/factib/app/backend/app/mcp'

# Run the backend MCP tests using the existing backend image
tar -C . -cf - app/backend/app app/backend/tests/mcp \
  | docker run --rm -i -e PYTHONPATH=/tmp/factib/app/backend backend:latest sh -c \
    'mkdir -p /tmp/factib && tar -xf - -C /tmp/factib && cd /tmp/factib/app/backend && \
     pytest -q --confcutdir=/tmp/factib/app/backend/tests/mcp tests/mcp'

Validación Local (Antes del Push)

Ejecuta siempre antes de crear un PR o enviar cambios. Esto replica el pipeline de CI localmente y detecta problemas antes de que lleguen a GitHub Actions.

Inicio Rápido

# Full validation (builds image + runs all checks):
./mcp/scripts/validate.sh

# Quick mode (reuses cached image, skips rebuild):
./mcp/scripts/validate.sh --quick

# Auto-fix known issues (e.g., BOM characters):
./mcp/scripts/validate.sh --fix

Qué Comprueba

Scripts Disponibles

Problemas Comunes y Soluciones

El registro completo de 200 elementos, incluido el trabajo implementado y planificado, está en docs/HARDENING_200.md.

Suite de capacidades ampliada: 60 herramientas adicionales

El servidor expone más de 100 herramientas en total: las 40 herramientas operativas originales más 60 capacidades específicas de tools/capability_suite.py.

Las herramientas que podrían causar mutaciones amplias devuelven un plan dry_run por defecto. Las herramientas de comentarios directos realizan una operación de comentario visible por invocación. El catálogo de capacidades verifica 60 adiciones únicas en el momento de la importación, y la validación de Docker confirma 100 herramientas FastMCP registradas en ambas copias del código fuente.

Distribución

Imagen Docker

El servidor MCP se distribuye como una imagen Docker independiente. Compílala localmente:

docker build -t github-project-mcp:latest ./mcp

Canal de CI/CD

El flujo de trabajo mcp-ci.yaml se ejecuta automáticamente en:

• Push a main cuando cambian archivos bajo mcp/

• Pull requests que afectan rutas de mcp/

Etapas del canal:

1. Compilación — Verificación de compilación de la imagen Docker

2. Verificación de sintaxis — Análisis AST de todos los archivos Python

3. Pruebas unitarias — Ejecución de la suite de pytest

4. Verificación del recuento de herramientas — Garantiza ≥100 herramientas registradas

Versionado

Este servidor MCP sigue Semantic Versioning. Consulta CHANGELOG.md para ver el historial de versiones.