mcp-agent-sol

Un servidor MCP que da a una IA acceso de lectura a los issues y pull requests de GitHub, y un agente (Claude Agent SDK) que lo usa para redactar project updates automáticamente.

 "update de owner/repo de octubre"
            │
            ▼
 ┌──────────────────────┐   herramientas MCP   ┌─────────────────────┐   HTTPS   ┌────────────┐
 │  agent.py            │ ───────────────────▶ │  server.py          │ ────────▶ │ GitHub API │
 │  Claude Agent SDK    │ ◀─────────────────── │  MCP Python SDK     │ ◀──────── │            │
 │  decide y redacta    │       JSON           │  search_issues      │           └────────────┘
 └──────────────────────┘                      │  get_issue          │
                                               └─────────────────────┘

Cómo funciona

1. agent.py arranca server.py como subproceso y se conecta a él por stdio usando el protocolo MCP.

2. El servidor anuncia sus herramientas (nombre, descripción, parámetros). Claude las ve como cualquier otra herramienta.

3. Claude lee tu petición y decide qué buscar, por ejemplo search_issues(repo, "is:pr is:merged merged:2022-10-01..2022-10-31").

4. El servidor traduce la llamada a la API REST de GitHub, recorta la respuesta a los campos útiles y la devuelve como JSON.

5. Claude repite los pasos 3–4 las veces que haga falta (hecho, en curso, pendiente, riesgos) y redacta el informe.

La separación es la idea clave: el servidor sabe cómo acceder a GitHub; el agente decide qué hacer. Por eso el servidor sirve también para otros clientes (Claude Code, Claude Desktop, modelos locales).

Related MCP server: AI Project Explorer

Instalación

Requisitos: Python ≥ 3.10 y un token de GitHub.

git clone https://github.com/Soller211/mcp-agent-sol && cd mcp-agent-sol
uv sync                                   # o: python -m venv .venv && .venv/bin/pip install -e .

Token de GitHub: se usa GITHUB_TOKEN; si no existe, el de la CLI gh (gh auth login). Recomendado: un token de solo lectura, ver Seguridad.

Claude: el agente usa tu sesión de Claude Code o la variable ANTHROPIC_API_KEY. Cada informe consume tokens (unos $0.05–0.10 con el modelo por defecto).

Uso del agente

uv run python agent.py "update de Soller211/customTenisDev de octubre 2022"
uv run python agent.py "update semanal de owner/repo" > update.md
uv run python agent.py "¿qué bugs abiertos tiene owner/repo?"

El informe sale por stdout; las llamadas a herramientas y el coste, por stderr. Ejemplo real:

→ search_issues({'query': 'is:pr is:merged merged:2026-09-20..2026-09-27', ...})
→ search_issues({'query': 'is:issue closed:2026-09-20..2026-09-27', ...})
→ search_issues({'query': 'is:pr is:open', ...})
→ search_issues({'query': 'is:issue is:open', ...})
→ get_issue({'number': 18})
→ get_issue({'number': 15})
→ get_issue({'number': 14})
[8 turnos · $0.0628]
# Update: Soller211/customTenisDev (2026-09-20 → 2026-09-27)
**Resumen:** Esta semana se cerró 1 issue de documentación (README) y no se mergeó ningún PR. No hay PRs abiertos. Quedan 5 issues abiertos: 2 bugs, 2 mejoras y 1 bloqueado, que es la integración de la pasarela de pago y está esperando las credenciales del proveedor.

## ✅ Hecho
- [#19](...) Actualizar README con capturas y cómo ejecutar el proyecto (`documentation`), cerrado el 2026-09-27.
...
## ⚠️ Riesgos / bloqueos
- [#18](...) Pasarela de pago bloqueada: según el último comentario, está "esperando credenciales del proveedor de pagos".

El agente solo abre el detalle (get_issue) de lo que parece bloqueado o es un bug: el número de llamadas se adapta a los datos.

Cambiar de modelo: ANTHROPIC_MODEL=claude-sonnet-5 uv run python agent.py "...".

Usar solo el servidor MCP

Claude Code:

claude mcp add github-updates -- /ruta/absoluta/.venv/bin/python /ruta/absoluta/server.py

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "github-updates": {
      "command": "/ruta/absoluta/.venv/bin/python",
      "args": ["/ruta/absoluta/server.py"]
    }
  }
}

Probarlo a mano con el MCP Inspector: npx @modelcontextprotocol/inspector@0.15.0 .venv/bin/python server.py (ciérralo con Ctrl+C al terminar: puede lanzar comandos). En WSL, abre http://localhost:6274 en el navegador de Windows (con 127.0.0.1 la conexión puede ser rechazada).

Herramientas

Modelos locales (Qwen, vLLM, Ollama)

No probado en este repo todavía; son las vías conocidas.

El servidor es independiente del modelo: cualquier cliente MCP lo puede usar. Ejemplo con Qwen-Agent y un vLLM local:

from qwen_agent.agents import Assistant

bot = Assistant(
    llm={"model": "Qwen/Qwen3-30B-A3B", "model_server": "http://localhost:8000/v1", "api_key": "EMPTY"},
    function_list=[{"mcpServers": {"github": {"command": ".venv/bin/python", "args": ["server.py"]}}}],
)

El agente habla el formato de la API de Anthropic. Para usarlo con un modelo local, pon delante un proxy que lo traduzca, como LiteLLM:

litellm --model hosted_vllm/Qwen/Qwen3-30B-A3B --api_base http://localhost:8000/v1 --port 4000
export ANTHROPIC_BASE_URL=http://localhost:4000 ANTHROPIC_API_KEY=local ANTHROPIC_MODEL=hosted_vllm/Qwen/Qwen3-30B-A3B
uv run python agent.py "update semanal de owner/repo"

Modelos pequeños (7B–14B) suelen fallar al encadenar llamadas a herramientas; usa uno de ~30B o más con buen tool calling.

Seguridad

La IA decide qué herramientas llamar, pero solo dentro de lo que este código permite:

• Solo lectura. El servidor solo hace GET a api.github.com (sin redirecciones) y el agente solo tiene search_issues y get_issue: sin Bash, sin escritura de archivos (tools=[]).

• Entradas validadas. repo debe tener formato owner/nombre (bloquea rutas como a/b/../../user), y query no admite repo:/org:/user:, OR/AND/NOT ni paréntesis, que permitirían buscar fuera del repo.

• Aislado de tu configuración. setting_sources=[] y strict_mcp_config=True: el agente ignora ~/.claude, .claude/ del proyecto (y sus hooks) y otros servidores MCP.

• Contenido no confiable. Issues y comentarios los escribe cualquiera y pueden intentar prompt injection. El prompt le indica tratarlos como datos; al ser de solo lectura, lo peor posible es un informe engañoso. Revisa el informe antes de publicarlo.

Usa un token de mínimo privilegio. El token de gh suele tener permisos de escritura y administración. Crea un fine-grained token con acceso solo a los repos que quieras y permisos Issues: Read y Pull requests: Read, y expórtalo:

export GITHUB_TOKEN=github_pat_...

Así, aunque el código cambiara, GitHub no permitiría escribir ni leer otros repos.

Lo que el agente envía al modelo (títulos, cuerpos y comentarios de issues) sale de tu máquina hacia Anthropic, o hacia el servidor del modelo que configures.

Límites y siguientes pasos

• Una sola página de búsqueda (máx. 100 resultados por consulta). Siguiente paso: paginación.

• La búsqueda de GitHub permite ~30 peticiones/minuto con token. Siguiente paso si se usa a escala: caché.

• Solo lectura. Siguiente paso posible: herramienta para publicar el informe como comentario en un issue.

• Los informes los redacta un LLM: revísalos antes de compartirlos.

Desarrollo

uv run pytest -q

Licencia

MIT