safe-runbook-mcp

Un servidor MCP con control de políticas para runbooks operativos. Permite que una IA inspeccione y ejecute comandos conocidos sin darle un shell sin restricciones.

Por qué existe

Los agentes de IA son útiles para operaciones, pero entregarles una terminal es una decisión de gran confianza. Este proyecto mantiene la parte útil (diagnósticos y mantenimiento repetibles) dentro de un límite pequeño y revisable:

Cliente de IA → inspeccionar plan → comprobaciones de políticas → aprobación humana opcional → comando exacto

Related MCP server: AgentPay MCP Server

Modelo de seguridad

• Los runbooks son JSON con control de versiones; la IA no puede inventar un comando.

• La ejecución está desactivada por defecto.

• Los ejecutables deben estar explícitamente en la lista de permitidos.

• Las variables se validan con expresiones regulares y se convierten en argumentos completos del proceso.

• Los comandos se ejecutan con shell: false dentro de un espacio de trabajo confinado con realpath.

• Los planes mutantes y destructivos requieren un token de aprobación HMAC de corta duración creado fuera de MCP.

• El token está vinculado al runbook y al hash exacto del plan, por lo que los cambios en las entradas lo invalidan.

• Los procesos tienen límites de tiempo y salida; los secretos declarados se redactan.

También se proporcionan anotaciones de herramientas MCP para los clientes, mientras que las comprobaciones del lado del servidor siguen siendo la autoridad.

Stack

TypeScript 7, Node.js 22, MCP TypeScript SDK v2, Zod 4, Vitest 4, Biome 2, Docker y GitHub Actions. El proyecto es de código abierto y no tiene dependencia de API de pago.

Inicio rápido

npm install
npm run cli -- list
npm run cli -- plan docker-service-status --var service=api
npm test

La ejecución debe habilitarse explícitamente:

RUNBOOK_EXECUTION_ENABLED=true npm run cli -- run disk-usage

Para un runbook mutante, genera la aprobación fuera de la conexión MCP y usa las mismas variables para la aprobación y la ejecución:

export RUNBOOK_EXECUTION_ENABLED=true
export RUNBOOK_APPROVAL_SECRET='replace-with-a-long-random-secret'

TOKEN=$(npm run --silent cli -- approve restart-compose-service --var service=api)
npm run cli -- run restart-compose-service --var service=api --approval "$TOKEN"

Conectar un cliente MCP

Compila una vez y luego añade este servidor stdio a un cliente compatible con MCP. Reemplaza las rutas con rutas absolutas de tu máquina.

{
  "mcpServers": {
    "safe-runbooks": {
      "command": "node",
      "args": ["/absolute/path/safe-runbook-mcp/dist/server.js"],
      "env": {
        "RUNBOOK_DIRECTORY": "/absolute/path/safe-runbook-mcp/runbooks",
        "RUNBOOK_WORKSPACE": "/workspace/to/manage",
        "RUNBOOK_EXECUTION_ENABLED": "false"
      }
    }
  }
}

El servidor expone:

• list_runbooks — descubre los runbooks disponibles y sus niveles de riesgo.

• inspect_runbook — resuelve las variables y devuelve el plan exacto junto con su hash.

• execute_runbook — ejecuta el plan ya definido después de las comprobaciones de políticas.

• runbook://catalog — recurso de catálogo de solo lectura.

Los registros van a stderr porque stdout está reservado para el tráfico JSON-RPC de MCP.

Añadir un runbook

Crea un archivo JSON en runbooks/:

{
  "id": "service-status",
  "title": "Inspect a service",
  "description": "Read one Compose service state.",
  "risk": "diagnostic",
  "variables": {
    "service": {
      "description": "Compose service name",
      "pattern": "[a-zA-Z0-9][a-zA-Z0-9_-]{0,62}",
      "required": true
    }
  },
  "steps": [
    {
      "id": "status",
      "title": "Read status",
      "executable": "docker",
      "args": ["compose", "ps", "{{service}}"]
    }
  ]
}

Elige diagnostic, mutating o destructive. Las variables deben ocupar un argumento completo como "{{service}}"; la interpolación de cadenas se rechaza intencionalmente.

Docker

docker build -t safe-runbook-mcp .
docker run --rm -i \
  -v "$PWD:/workspace:ro" \
  -e RUNBOOK_WORKSPACE=/workspace \
  -e RUNBOOK_DIRECTORY=/app/runbooks \
  safe-runbook-mcp

Mantén la ejecución desactivada para un montaje de solo lectura. Si un runbook necesita Docker, monta solo el socket o contexto remoto requerido después de revisar ese límite de confianza.

Desarrollo

npm run check
npm run typecheck
npm test
npm run build

Consulta CONTRIBUTING.md para el flujo de trabajo de ramas y AGENTS.md para las reglas del repositorio que usan los agentes de codificación.

Referencias

• Paquetes del SDK de TypeScript de MCP

• Crear un servidor MCP

• Servir a través de stdio

Licencia

MIT