safe-runbook-mcp

운영 런북을 위한 정책 게이트를 갖춘 MCP 서버입니다. AI가 제한 없는 셸을 부여받지 않고도 알려진 명령을 검사하고 실행할 수 있게 합니다.

존재 이유

AI 에이전트는 운영 작업에 유용하지만, 에이전트에 터미널을 쥐어주는 것은 큰 신뢰 결정입니다. 이 프로젝트는 반복 가능한 진단과 유지보수라는 유용한 부분을 작고 검토 가능한 경계 안에 둡니다:

AI client → inspect plan → policy checks → optional human approval → exact command

Related MCP server: AgentPay MCP Server

안전 모델

• 런북은 버전 관리되는 JSON입니다. AI는 명령을 임의로 만들 수 없습니다.

• 실행은 기본적으로 비활성화되어 있습니다.

• 실행 파일은 명시적으로 허용 목록에 등록되어야 합니다.

• 변수는 정규식으로 검증되며 완전한 프로세스 인수가 됩니다.

• 명령은 realpath로 제한된 작업 공간 안에서 shell: false로 실행됩니다.

• 변경(mutating) 및 파괴(destructive) 플랜은 MCP 외부에서 생성된 단기 HMAC 승인 토큰이 필요합니다.

• 토큰은 런북과 정확한 플랜 해시에 바인딩되므로 입력이 변경되면 무효화됩니다.

• 프로세스에는 시간 및 출력 제한이 있으며, 선언된 비밀 정보는 편집(redact)됩니다.

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

변경(mutating) 런북의 경우, 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 — 사용 가능한 런북과 위험 수준을 탐색합니다.

• inspect_runbook — 변수를 해석하고 정확한 플랜과 해시를 반환합니다.

• execute_runbook — 정책 검사 후 이미 정의된 플랜을 실행합니다.

• runbook://catalog — 읽기 전용 카탈로그 리소스입니다.

로그는 stderr로 출력됩니다. stdout은 MCP JSON-RPC 트래픽용으로 예약되어 있기 때문입니다.

런북 추가

runbooks/에 JSON 파일을 만드세요:

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

읽기 전용 마운트의 경우 실행을 비활성화 상태로 유지하세요. 런북에 Docker가 필요한 경우, 해당 신뢰 경계를 검토한 후 필요한 소켓 또는 원격 컨텍스트만 마운트하세요.

개발

npm run check
npm run typecheck
npm test
npm run build

브랜치 워크플로는 CONTRIBUTING.md를, 코딩 에이전트가 사용하는 저장소 규칙은 AGENTS.md를 참조하세요.

참고 자료

• MCP TypeScript SDK 패키지

• MCP 서버 구축

• stdio로 제공하기

라이선스

MIT