Servidor de Model Context Protocol (MCP) de GitHub con Evaluación de Llamada de Herramientas

Un servidor FastMCP de GitHub de grado de producción que expone operaciones de lectura y escritura con confirmación, junto con un arnés de evaluación de 30 casos que puntúa la selección de herramientas, la precisión de argumentos y la seguridad de confirmación destructiva.

Resumen Ejecutivo y Matriz de Evaluación

La llamada de herramientas de agentes LLM requiere límites de seguridad estrictos. Este servidor MCP aplica control de confirmación a nivel de servidor en todas las acciones mutantes: las solicitudes no confirmadas devuelven vistas previas de ejecución en seco en lugar de ejecutar mutaciones en GitHub.

Rendimiento de Referencia (30 Escenarios Etiquetados)

Evaluado contra un punto de referencia de 30 casos que prueba llamadas de herramientas estándar, consultas subespecificadas/ambiguas y acciones destructivas con confirmación:

Related MCP server: github-mcp-tool

Arquitectura de Herramientas y Operaciones

flowchart TD
    A[User Request] --> B[LLM Tool-Calling Engine]
    B --> C{Tool Category}
    
    C -- Read Tool --> D[Execute GitHub API Call Directly]
    D --> E[Return API Payload]
    
    C -- Write / Destructive --> F{confirm == true ?}
    F -- Yes --> G[Execute State Mutation on GitHub]
    G --> H[Return Success / Number / URL]
    
    F -- No --> I[Return Dry-Run Preview of Mutation]

Herramientas Disponibles

Operaciones de Lectura (Ejecución Inmediata)

• list_issues(owner, repo, state): Lista los problemas abiertos/cerrados en un repositorio.

• get_issue(owner, repo, issue_number): Recupera metadatos detallados de un solo problema.

• list_pull_requests(owner, repo, state): Lista las solicitudes de extracción en un repositorio.

• get_pull_request(owner, repo, pr_number): Recupera detalles y capacidad de fusión de una PR.

• search_code(query, owner, repo): Busca en el código de GitHub globalmente o limitado a un repositorio.

Operaciones Destructivas (Con Confirmación)

• create_issue(owner, repo, title, body, confirm=False): Crea un problema solo cuando se confirma; de lo contrario, devuelve una vista previa.

• close_issue(owner, repo, issue_number, confirm=False): Cierra un problema solo cuando se confirma; de lo contrario, devuelve una vista previa.

• add_comment(owner, repo, issue_number, body, confirm=False): Comenta en un problema/PR solo cuando se confirma; de lo contrario, devuelve una vista previa.

• merge_pull_request(owner, repo, pr_number, confirm=False): Fusiona una PR solo cuando se confirma; de lo contrario, devuelve una vista previa.

Estructura del Proyecto

├── app/
│   ├── __init__.py          # Public MCP server & client exports
│   ├── server.py            # FastMCP server definition & tool routing
│   └── github_client.py     # GitHub REST API client with dry-run previews
├── eval/
│   ├── __init__.py          # Evaluation package
│   ├── tool_schemas.py      # OpenAI-compatible function definitions & prompt
│   ├── test_set.json        # 30 labeled evaluation test cases
│   └── run_eval.py          # Benchmark harness scoring tool, args, and confirm flags
├── requirements.txt         # Dependencies (mcp, requests, openai)
├── WRITEUP.md               # Detailed evaluation report & iteration analysis
└── README.md

Inicio Rápido y Uso

1. Instalación

git clone https://github.com/vishalmurugan1986/github-mcp-server.git
cd github-mcp-server

pip install -r requirements.txt

2. Configuración del Entorno

export NVIDIA_API_KEY="nvapi-your-key-here"
# Optional: real GitHub write access
export GITHUB_TOKEN="ghp_your_personal_access_token"

3. Ejecución del Servidor MCP

python -m app.server

Conecta un cliente MCP (como Claude Desktop o agentes personalizados) a través de E/S estándar.

4. Ejecución del Conjunto de Evaluación de Llamada de Herramientas

python -m eval.run_eval

Los resultados se guardan en eval/results.json y se imprimen con desgloses completos de métricas.

Principios de Diseño de Seguridad

1. Confirmación de Defensa en Profundidad: En lugar de depender únicamente de instrucciones de prompt, los controles de confirmación están codificados directamente en app/github_client.py. Una solicitud no confirmada no puede causar una mutación accidental.

2. Rechazo de Ambigüedad: Se instruye al modelo para que rechace la ejecución y haga preguntas aclaratorias siempre que los repositorios, números de problema o parámetros no estén especificados, evitando alucinaciones de marcadores de posición.