safe-runbook-mcp

Сервер MCP с политиками доступа для операционных runbook. Он позволяет ИИ просматривать и запускать известные команды, не предоставляя ему неограниченный доступ к оболочке.

Зачем это нужно

ИИ-агенты полезны для операционной работы, но передача агенту терминала — это большое доверие. Этот проект удерживает полезную часть — повторяемые диагностики и обслуживание — внутри небольшой, проверяемой границы:

ИИ-клиент → просмотр плана → проверка политик → опциональное одобрение человека → точная команда

Related MCP server: AgentPay MCP Server

Модель безопасности

• Runbook хранятся в JSON под контролем версий; ИИ не может придумать команду.

• Выполнение по умолчанию отключено.

• Исполняемые файлы должны быть явно внесены в список разрешённых.

• Переменные проверяются регулярными выражениями и становятся полными аргументами процесса.

• Команды выполняются с shell: false внутри рабочей области, ограниченной realpath.

• Изменяющие и разрушительные планы требуют кратковременный HMAC-токен одобрения, созданный вне MCP.

• Токен привязан к runbook и точному хэшу плана, поэтому изменение входных данных делает его недействительным.

• Процессы имеют ограничения по времени и объёму вывода; объявленные секреты редактируются.

Аннотации инструментов MCP также предоставляются для клиентов, при этом проверки на стороне сервера остаются авторитетными.

Стек

TypeScript 7, Node.js 22, MCP TypeScript SDK v2, Zod 4, Vitest 4, Biome 2, Docker и GitHub Actions. Проект с открытым исходным кодом и не имеет платных API-зависимостей.

Быстрый старт

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

Выполнение должно быть явно включено:

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

Для изменяющего runbook сгенерируйте одобрение вне MCP-соединения и используйте те же переменные для одобрения и выполнения:

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-клиента

Соберите один раз, затем добавьте этот stdio-сервер в MCP-совместимый клиент. Замените пути на абсолютные пути на вашей машине.

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

Сервер предоставляет:

• list_runbooks — обнаружение доступных runbook и уровней риска.

• inspect_runbook — разрешение переменных и возврат точного плана вместе с его хэшем.

• execute_runbook — выполнение уже определённого плана после проверок политик.

• runbook://catalog — ресурс каталога только для чтения.

Логи идут в stderr, потому что stdout зарезервирован для MCP JSON-RPC трафика.

Добавление runbook

Создайте JSON-файл в 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}}"]
    }
  ]
}

Выберите diagnostic, mutating или destructive. Переменные должны занимать полный аргумент, например "{{service}}"; строковая интерполяция намеренно отклоняется.

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

Оставьте выполнение отключённым для монтирования только для чтения. Если runbook требует Docker, смонтируйте только необходимый сокет или удалённый контекст после проверки этой границы доверия.

Разработка

npm run check
npm run typecheck
npm test
npm run build

См. CONTRIBUTING.md для описания рабочего процесса с ветками и AGENTS.md для правил репозитория, используемых кодирующими агентами.

Ссылки

• Пакеты MCP TypeScript SDK

• Создание MCP-сервера

• Работа через stdio

Лицензия

MIT