English | 中文

PR-Agent MCP Server

A MCP (Model Context Protocol) server that exposes pr-agent CLI commands as MCP tools, with optional Gitea webhook integration for automatic PR review. Supports both SSE and StreamableHTTP transports, and can run locally or in Docker.

Características

• Herramientas MCP: Exponer los comandos de pr-agent (review, describe, improve, ask, reflect, update_changelog, generate_labels) como herramientas MCP.

• Transportes: SSE (/sse) y StreamableHTTP (/mcp), seleccionables mediante --transport sse|streamable-http|both.

• Webhook de Gitea: Activar automáticamente las acciones de review, describe y improve cuando se abre un nuevo PR en Gitea.

• Verificación de Firma HMAC: Validación opcional de la firma del webhook para seguridad.

• Inyección de Configuración: Carga automáticamente las credenciales desde ~/.secrets.toml y las inyecta en el entorno del subproceso de pr-agent.

Estructura del Proyecto

pr-agent-mcp/
├── server.py            # Main MCP server and webhook handler
├── run.ps1              # PowerShell startup script (local run)
├── requirements.txt     # Python dependencies
├── Dockerfile           # Multi-stage Docker image definition
├── docker-compose.yml   # Docker Compose service definition
├── push.ps1             # Build & push image to registry
├── .dockerignore        # Exclude files from Docker build context
├── buggy_samples.py     # Intentional bug samples for pr-agent testing
├── test.http            # HTTP test requests (VS Code REST Client / similar)
├── README.md
├── README.zh-CN.md
└── .gitignore

Requisitos Previos

• Docker con Docker Compose (recomendado) o Python 3.11+ (usa tomllib)

• Instancia de Gitea (para integración con webhook, opcional)

• ~/.secrets.toml con tus credenciales de proveedor (ver abajo)

Configurar credenciales

Crea ~/.secrets.toml en tu directorio de usuario con tus credenciales de proveedor y LLM:

[gitea]
url = "http://your-gitea-instance:3000"
token = "your-gitea-personal-access-token"

[openai]
key = "sk-your-openai-api-key"

La variable de entorno SECRETS_TOML_PATH anula la ubicación predeterminada (~/.secrets.toml). Esto es utilizado por la imagen Docker para localizar el archivo montado por bind.

Despliegue con Docker (recomendado)

1. Construir e iniciar localmente

docker compose up -d --build

Esto:

1. Construye la imagen (multi-etapa: instala las dependencias de pr-agent y mcp en un venv, instala git en tiempo de ejecución).

2. Monta tu directorio de usuario como solo lectura en el contenedor en /host-home para que pueda leer ~/.secrets.toml.

3. Mapea el puerto 9000 del host al puerto 9000 del contenedor.

4. Inicia el servidor con ambos transportes SSE y StreamableHTTP.

El contenedor monta ${USERPROFILE} (todo el directorio de usuario) en lugar del archivo único .secrets.toml. Montar un archivo del host que no existe hace que Docker cree un directorio en su lugar, causando IsADirectoryError — montar el directorio padre evita este problema.

2. Subir la imagen a un registro privado

# Build + tag + push to the default registry (10.10.11.194:1000/pr-agent-mcp:latest)
.\push.ps1

# Push to another registry / with a version tag / skip rebuild
.\push.ps1 -Registry "192.168.1.100:5000" -Tag "v1.0.0" -NoBuild

3. Ejecutar en otra máquina (por ejemplo, un servidor de pruebas)

Copia docker-compose.yml a la máquina de destino y cambia build: . por image: 10.10.11.194:1000/pr-agent-mcp:latest, luego:

docker pull 10.10.11.194:1000/pr-agent-mcp:latest
docker compose up -d

O ejecuta directamente sin un archivo compose:

docker run -d \
  --name pr-agent-mcp \
  -p 9000:9000 \
  -v $env:USERPROFILE:/host-home:ro \
  -e SECRETS_TOML_PATH=/host-home/.secrets.toml \
  --restart unless-stopped \
  10.10.11.194:1000/pr-agent-mcp:latest

Gestionar el contenedor

# View logs
docker compose logs -f

# Stop & remove
docker compose down

# Restart
docker compose restart

Ejecución Local (sin Docker)

1. Instalar dependencias

python -m venv mcp_env
mcp_env\Scripts\activate
pip install -r requirements.txt

requirements.txt solo contiene mcp (el framework MCP). pr-agent NO es una dependencia de Python de este servidor — se llama como un subproceso a través de la ruta configurada en server.py (o la variable de entorno PR_AGENT_EXE). Asegúrate de que pr-agent ya esté instalado en algún lugar de la máquina.

2. (Opcional) Configurar secreto del webhook

Establece WEBHOOK_SECRET en server.py con el mismo secreto configurado en los ajustes del webhook de Gitea. Déjalo vacío para deshabilitar la verificación de firma (no recomendado para producción).

3. Iniciar el servidor

.\run.ps1

O directamente:

python server.py
python server.py --transport sse        # SSE only
python server.py --transport streamable-http  # StreamableHTTP only

Endpoints

Herramientas MCP

Configuración del Webhook de Gitea

1. En tu repositorio de Gitea, ve a Configuración → Webhooks → Añadir Webhook.

2. Establece la URL de destino en http://<your-server>:9000/webhook.

3. Establece el método HTTP en POST y el tipo de contenido en application/json.

4. Opcionalmente, establece un secreto (debe coincidir con WEBHOOK_SECRET en server.py).

5. Selecciona el evento Pull Request con la acción Opened.

Cuando se abre un PR, el servidor ejecutará automáticamente las acciones review, describe e improve y publicará los resultados como comentarios en el PR.

Pruebas

Usa el archivo test.http incluido con VS Code REST Client o un cliente HTTP similar para probar manualmente el endpoint del webhook.

buggy_samples.py contiene errores intencionales en múltiples categorías (seguridad, lógica, concurrencia, manejo de errores) para probar las capacidades de detección de revisión de código de pr-agent.

Licencia

Privado — solo uso interno.