runbook

MCP server that exposes development tasks defined in YAML as MCP tools.

Install

curl -fsSL https://runbookproduction.z13.web.core.windows.net/install.sh | bash

Build

go build -o bin/runbook main.go

Or use make:

make build

Configuration

The server looks for configuration in this order:

1. Path given via -config flag (file or directory)
2. .runbook/ directory — all *.yaml files are merged automatically

Create a .runbook/ directory with one or more YAML files:

.runbook/
  tasks.yaml
  daemons.yaml
  prompts.yaml

Each file is a standard manifest. They are merged together — task names, workflow names, and prompt names must be unique across files.

Overrides file

Place a .runbook.overrides.yaml at the project root to control task visibility without editing your config files. Glob patterns are supported for task names.

# .runbook.overrides.yaml
tasks:
  deploy:
    disabled: true       # fully disable (CLI + MCP)
  ts-*:
    disable_mcp: true    # hide from AI, keep CLI access
workflows:
  ci:
    disabled: true

The overrides file is optional and is ignored if it does not exist.

Example

.runbook/tasks.yaml:

version: "1.0"

tasks:
  test:
    description: "Run tests"
    command: "go test ./..."
    type: oneshot

  dev:
    description: "Start dev server"
    command: "npm run dev"
    type: daemon

CLI Usage

Run tasks directly from the command line:

runbook list                                    # List all available tasks
runbook run <task> [--param=value...]           # Run a oneshot task or workflow
runbook start <task> [--param=value...]         # Start a daemon
runbook stop <task>                             # Stop a daemon
runbook status <task>                           # Show daemon status
runbook logs <task> [--lines=N] [--filter=REGEX] [--session=ID]

All subcommands accept --config=path to specify a custom config location.

Examples

# List tasks defined in your config
runbook list

# Run a task
runbook run build

# Run a parameterized task
runbook run go_test --flags="-v -race" --package="./..."

# Start/stop a daemon
runbook start dev
runbook stop dev
runbook status dev

# View logs
runbook logs dev --lines=50
runbook logs dev --filter="ERROR"

Task output goes to stdout (pipeable). Status and metadata go to stderr.

Prompt Templates

Prompts support Go template syntax. Use run_task to reference task tool names — this works with any task name including those containing hyphens:

prompts:
  dev-workflow:
    description: "How to work on this project"
    content: |
      Run tests: {{run_task "my-tests"}}
      Start server: {{run_task "dev-server"}}

{{run_task "my-tests"}} resolves to run_my-tests. For task names without hyphens, dot-access also works: {{.Tasks.build.Run}} → run_build.

Usage with MCP

Add to your .mcp.json:

{
  "mcpServers": {
    "runbook": {
      "command": "/path/to/runbook"
    }
  }
}

Development

make test    # Run tests
make lint    # Run linter
make build   # Build binary to bin/runbook
make install # Install to $HOME/.bin/runbook