Skip to main content
Glama
safe-runbook-mcp

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: 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

Licencia

MIT

Available Tools

3 tools
execute_runbookExecute an approved runbookA
Destructive

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 planA
Read-onlyIdempotent

Validate variables and return the exact commands, plan hash, risk, and approval requirement without executing.

Inputs: id (required), variables.

list_runbooksList safe runbooksA
Read-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

    A4.2/5.0

    Scored across 3 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    All three tool names follow a consistent verb_noun pattern: inspect, execute, and list all pair with 'runbook'. The naming is uniform and predictable.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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