safe-runbook-mcp
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: govmcp
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: falsedentro 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 testLa ejecución debe habilitarse explícitamente:
RUNBOOK_EXECUTION_ENABLED=true npm run cli -- run disk-usagePara 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-mcpManté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 buildConsulta 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
Licencia
MIT
Available Tools
3 toolsexecute_runbookExecute an approved runbookADestructive
Execute only commands declared in a version-controlled runbook. Requires the global execution gate; mutating plans also require an out-of-band approval token.
Inputs: id (required), variables, approvalToken.
inspect_runbookInspect a resolved runbook planARead-onlyIdempotent
Validate variables and return the exact commands, plan hash, risk, and approval requirement without executing.
Inputs: id (required), variables.
list_runbooksList safe runbooksARead-onlyIdempotent
List version-controlled runbooks and their risk levels. Does not execute anything.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: inspect validates and previews, execute runs commands, and list enumerates available runbooks. There is no overlap or ambiguity between them.
All three tool names follow a consistent verb_noun pattern: inspect, execute, and list all pair with 'runbook'. The naming is uniform and predictable.
With only three tools, the server is lean but covers the essential operations for runbook management: discover, preview, and execute. It is slightly minimal but appropriate for a focused purpose.
The server provides the core lifecycle for runbooks: list, inspect, and execute. Missing are update/delete operations, but since runbooks are version-controlled externally, those may be intentionally out of scope. No critical gaps for safe execution.
Maintenance
Related MCP Connectors
Autonomous and governed SRE & MLOps control plane for AI agent platforms.
Security gateway for AI agents: policy, approval, and audited execution, no secrets shared.
Runtime permission, approval, and audit layer for AI agent tool execution.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables controlled AI-agent access to enterprise-shaped tools with a deny-by-default gated write path, human approval, dry-run execution, and append-only audit logging.1-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to operate a simulated IT operations environment through policy-enforced, risk-tiered tool calls with human approval for risky writes, dry-run previews, rate limits, emergency lockdown, and tamper-evident auditing.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to safely interact with operations systems such as cloud inventory, runbooks, and ticketing while enforcing role-based access, JWT authentication, write confirmation, secret and PII redaction, rate limits, and audit logging.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to perform safe, auditable Kubernetes write actions such as scaling, restarting and rolling back Deployments through a plan → policy-check → approve → apply → audit flow, with server-side guards, single-use plans and scoped RBAC. Read-only planning and Prometheus SLO/alert tools support the same guarded workflow.Apache 2.0