safe-runbook-mcp

Ein richtlinienbasierter MCP-Server für operative Runbooks. Er ermöglicht einer KI, bekannte Befehle zu prüfen und auszuführen, ohne ihr eine uneingeschränkte Shell zu geben.

Warum es das gibt

KI-Agenten sind für den Betrieb nützlich, aber ihnen ein Terminal zu überlassen ist eine große Vertrauensentscheidung. Dieses Projekt hält den nützlichen Teil – wiederholbare Diagnosen und Wartung – innerhalb einer kleinen, überprüfbaren Grenze:

AI-Client → Plan prüfen → Richtlinienprüfungen → optionale menschliche Freigabe → exakter Befehl

Related MCP server: AgentPay MCP Server

Sicherheitsmodell

• Runbooks sind versionierte JSON-Dateien; die KI kann keinen Befehl erfinden.

• Die Ausführung ist standardmäßig deaktiviert.

• Ausführbare Dateien müssen explizit auf die Whitelist gesetzt werden.

• Variablen werden per Regex validiert und werden zu vollständigen Prozessargumenten.

• Befehle laufen mit shell: false in einem auf realpath begrenzten Arbeitsbereich.

• Verändernde und destruktive Pläne erfordern ein kurzlebiges HMAC-Freigabe-Token, das außerhalb von MCP erstellt wird.

• Das Token ist an das Runbook und den exakten Plan-Hash gebunden, sodass geänderte Eingaben es ungültig machen.

• Prozesse haben Zeit- und Ausgabelimits; deklarierte Geheimnisse werden geschwärzt.

MCP-Tool-Anmerkungen werden auch für Clients bereitgestellt, während serverseitige Prüfungen die Autorität bleiben.

Technologie-Stack

TypeScript 7, Node.js 22, MCP TypeScript SDK v2, Zod 4, Vitest 4, Biome 2, Docker und GitHub Actions. Das Projekt ist Open Source und hat keine kostenpflichtige API-Abhängigkeit.

Schnellstart

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

Die Ausführung muss explizit aktiviert werden:

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

Für ein veränderndes Runbook generieren Sie die Freigabe außerhalb der MCP-Verbindung und verwenden Sie dieselben Variablen für Freigabe und Ausführung:

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"

MCP-Client verbinden

Einmal bauen, dann diesen stdio-Server zu einem MCP-kompatiblen Client hinzufügen. Ersetzen Sie die Pfade durch absolute Pfade auf Ihrem Rechner.

{
  "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"
      }
    }
  }
}

Der Server stellt bereit:

• list_runbooks – verfügbare Runbooks und Risikostufen entdecken.

• inspect_runbook – Variablen auflösen und den exakten Plan samt Hash zurückgeben.

• execute_runbook – den bereits definierten Plan nach Richtlinienprüfungen ausführen.

• runbook://catalog – schreibgeschützte Katalogressource.

Logs gehen an stderr, da stdout für MCP-JSON-RPC-Verkehr reserviert ist.

Ein Runbook hinzufügen

Erstellen Sie eine JSON-Datei in 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}}"]
    }
  ]
}

Wählen Sie diagnostic, mutating oder destructive. Variablen müssen ein vollständiges Argument wie "{{service}}" belegen; String-Interpolation wird bewusst abgelehnt.

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

Lassen Sie die Ausführung für einen schreibgeschützten Mount deaktiviert. Wenn ein Runbook Docker benötigt, mounten Sie nur den erforderlichen Socket oder Remote-Kontext, nachdem Sie diese Vertrauensgrenze überprüft haben.

Entwicklung

npm run check
npm run typecheck
npm test
npm run build

Siehe CONTRIBUTING.md für den Branch-Workflow und AGENTS.md für Repository-Regeln, die von Codierungsagenten verwendet werden.

Referenzen

• MCP TypeScript SDK packages

• Build an MCP server

• Serve over stdio

Lizenz

MIT