Agent B

This is Part 2 of a 3-part series on MIM-Runbook. Part 1 covers what the plugin is and its business value. Part 3 walks through a real example end-to-end.

This guide walks you through everything you need to get MIM-Runbook running on your machine — from cloning the repository to generating your first complete incident runbook. By the end, you’ll have three production-ready files (Markdown, Word, and Excel) generated from your incident data.

Prerequisites

Before you begin, make sure you have the following installed:

• Node.js 18+ (LTS recommended) — the MCP server is a TypeScript/Node project
• npm (comes bundled with Node.js)
• Claude Cowork (desktop app) or Claude Code (CLI) — the plugin runs inside either environment
• Git (to clone the repository)

You can verify your Node version by running node --version in your terminal. If you’re below v18, install the latest LTS from nodejs.org.

Step 1: Clone the Repository

git clone https://github.com/agentbee0/MIM-Runbook.git
cd MIM-Runbook

The repository structure looks like this:

MIM-Runbook/
├── example/
│   ├── input/              ← Sample YAML files (incidents + stakeholders)
│   └── output/             ← Sample generated runbooks
├── src/                    ← The plugin source (this is what you install)
│   ├── commands/           ← Slash commands (/generate-runbook, /validate-yaml, /snow-runbook)
│   ├── skills/             ← Auto-triggered skills (runbook-generation, incident-triage)
│   ├── servers/            ← MCP server (runbook-generator)
│   ├── .mcp.json           ← MCP server configuration
│   ├── README.md
│   ├── CONNECTORS.md
│   └── CONTRIBUTING.md
└── output/                 ← Where your generated runbooks will appear

The src/ directory is the plugin itself — everything inside it gets installed as a Claude plugin. The example/ directory contains sample inputs and outputs for reference. The root-level output/ directory is where your generated runbooks will land.

Step 2: Install MCP Server Dependencies

The plugin’s core engine is an MCP (Model Context Protocol) server written in TypeScript. It handles YAML parsing, schema validation, and the generation of all three output formats. Navigate to the server directory and install its dependencies:

cd src/servers/runbook-generator
npm install

This installs five key packages:

• @modelcontextprotocol/sdk (^1.12.0) — The MCP protocol layer that lets Claude communicate with the server
• docx (^9.6.0) — Generates the formatted Word document with title page, severity badges, headers, and footers
• exceljs (^4.4.0) — Generates the Excel workbook with four sheets, conditional formatting, dropdown validations, and formula-driven dashboards
• js-yaml (^4.1.0) — Parses your incident and stakeholder YAML files
• zod (^3.24.0) — Validates YAML input against the schema, providing field-level error messages when something is missing or malformed

The install should complete in under 30 seconds. If you see any warnings about peer dependencies, they’re safe to ignore for this project.

Step 3: Build the MCP Server (Optional)

By default, the plugin uses tsx (TypeScript Execute) to run the server directly from TypeScript source. This is convenient for development and works out of the box. If you prefer to run the compiled JavaScript:

npm run build

This compiles TypeScript to the dist/ directory. After building, the server will run via npm start (which executes node dist/index.js) instead of npm run dev (which executes tsx src/index.ts).

For most users, you can skip this step — the plugin’s .mcp.json is already configured to use tsx directly.

Step 4: Install the Plugin in Claude

For Claude Cowork (Desktop App)

1. Open Claude Cowork
2. Navigate to Customize > Browse plugins > Upload
3. Select the src/ folder — this is the folder containing .mcp.json, commands/, skills/, and servers/
4. Claude Cowork will detect the plugin structure and add it to your plugin list
5. You should see the MIM-Runbook plugin appear with its commands (/generate-runbook, /validate-yaml) available

For Claude Code (CLI)

claude plugin install --path /path/to/MIM-Runbook/src

Replace /path/to/MIM-Runbook/src with the actual path on your machine. After installation, the commands will be available in your Claude Code session.

Verify Installation

To confirm the plugin is working, try running:

/validate-yaml

If the plugin is correctly installed, the MCP server will start and respond (it may report that no YAML file was specified — that’s expected and confirms the server is running).

Step 5: Prepare Your Input YAML Files

You need two YAML files to generate a runbook: an incident file and a stakeholders file.

Incident YAML

The incident YAML describes the ServiceNow ticket (or equivalent). Here’s the required schema:

incident:
  number: "INC0078342"               # Required — becomes the ID everywhere
  title: "Short descriptive title"   # Required
  severity: "1 - Critical"           # Required — drives urgency tone
  priority: "1 - Critical"           # Required
  state: "In Progress"               # Required
  category: "Database"               # Required — routes investigation steps
  subcategory: "Availability"        # Required
  affected_service: "Payment API"    # Required — appears in all comms
  affected_ci: "prod-oracle-01"      # Required — injected into CLI commands
  environment: "Production"          # Required
  region: "us-east-1"                # Optional — adds region context
  business_impact: "..."             # Required — verbatim in all emails
  opened_at: "2026-02-26T14:28:00Z"  # Required — ISO 8601
  detected_at: "2026-02-26T14:27:45Z" # Optional
  assigned_to: "Team Name"           # Required
  assignment_group: "Group Name"     # Required
  caller_id: "Reporter Name"         # Required
  short_description: "..."           # Required
  description: |                     # Required — full context block
    Multi-line description with
    symptoms, timeline, and
    initial observations.
  change_related: true               # Optional — flags recent change

The category field is particularly important. It determines which diagnostic playbook Section 4 generates. Supported categories are: Database, Network, Application, Cloud/Infra, Security, and Other (generic fallback).

The affected_ci value is injected into every command throughout the runbook — ping prod-oracle-01, ssh prod-oracle-01, etc. — so make sure it matches the actual hostname or resource identifier your team would use.

Stakeholders YAML

The stakeholders YAML defines the people involved in the response and their escalation levels:

stakeholders:
  - name: "Full Name"
    role: "Incident Commander"      # IC, Technical Lead, Comms Lead, etc.
    title: "Job Title"
    team: "Team Name"
    email: "user@company.com"       # Used in email To:/CC: fields
    phone: "+1-555-0000"            # Used in escalation matrix
    slack: "@handle"                # Used in triage and Slack templates
    escalation_level: 1             # 1=immediate, 2=T+30, 3=T+60+
    notify_immediately: true        # true = To: in Templates 1-4
    bridge_url: "https://zoom.us/j/..." # Optional — used in all comms
    bridge_phone: "+1-... PIN: ..."     # Optional — dial-in for bridge
vendor_escalations:                 # Optional section
  - vendor: "Oracle Support"
    account_number: "ORA-12345"
    support_url: "https://support.oracle.com"
    phone: "+1-800-223-1711"
    severity_mapping: "SEV1 - Production Down"

Key design decisions to understand:

• Escalation level 1 stakeholders with notify_immediately: true appear in the “To:” line of email templates 1-4. These are your war room participants.
• Escalation level 2 stakeholders are CC’d on early emails and become “To:” recipients on templates 4-6. They’re the T+30 escalation targets.
• Escalation level 3 stakeholders (typically executives) are CC-only on templates 3-6 and never receive the initial alert directly.
• The first stakeholder with bridge_url defined provides the Zoom link used in all communications.
• The plugin automatically identifies the Incident Commander, Technical Lead, and Communications Lead by matching role names.

Using the Example Files

The repository includes several example files to get you started:

# Copy examples to your working directory
cp example/input/incident-network-outage.yaml input/my-incident.yaml
cp example/input/stakeholders-example.yaml input/my-stakeholders.yaml

Edit these files with your actual data. The example files are well-commented and include every field the schema supports.

Step 6: Validate Your YAML

Before generating, validate your YAML to catch schema errors. This step is optional but highly recommended — a missing required field will produce a runbook with gaps.

/validate-yaml input/my-incident.yaml

The validator uses Zod schema validation under the hood and returns specific, field-level error messages. For example:

❌ incident.affected_ci: Required field is missing
❌ incident.opened_at: Invalid date format — expected ISO 8601 (e.g., 2026-02-26T14:28:00Z)
✅ stakeholders: All 8 stakeholders pass validation

Fix any errors and re-validate until you get a clean pass.

Step 7: Generate Your Runbook

You’re ready. Run the generation command:

/generate-runbook input/my-incident.yaml input/my-stakeholders.yaml

Or, if your files are in the default input/ directory:

/generate-runbook

The plugin will parse both YAML files, validate them against the schema, generate the 8-section Markdown runbook, convert it to a formatted Word document, generate the 4-sheet Excel action tracker, and save all three files to the output/ directory.

Output files follow the naming convention RB-{incident_number}-{timestamp}:

output/
├── RB-INC0078342-2026-02-26T13-01-55.md
├── RB-INC0078342-2026-02-26T13-01-55.docx
└── RB-INC0078342-2026-02-26T13-01-55.xlsx

Understanding the MCP Server Architecture

Under the hood, the plugin exposes four MCP tools in Phase 1:

The MCP server configuration is defined in .mcp.json at the plugin root:

{
  "mcpServers": {
    "runbook-generator": {
      "command": "npx",
      "args": ["tsx", "servers/runbook-generator/src/index.ts"]
    }
  }
}

When Claude loads the plugin, it starts the MCP server as a child process. Claude communicates with the server over the MCP protocol, calling tools like generate_runbook and validate_incident_yaml in response to your slash commands.

Phase 2 Preview: ServiceNow Integration

Phase 2 (planned) adds live ServiceNow integration with four additional MCP tools:

• fetch_snow_incident — Fetches a live incident from ServiceNow by INC number via the Table API
• fetch_snow_stakeholders — Fetches assignment group members automatically, eliminating the need for a manual stakeholders YAML
• update_snow_incident — Posts the generated runbook back to the ticket as work notes
• create_snow_pir_ticket — Creates a Post-Incident Review Problem record in ServiceNow

Then use the single command:

/snow-runbook INC0078342

This fetches the incident, fetches stakeholders, generates all three output files, and optionally posts back to the ticket — a fully automated pipeline from SNOW ticket to prescriptive runbook.

Extending with Optional Connectors

The plugin architecture is designed for extensibility. You can add MCP connectors for external services by extending the .mcp.json configuration. Currently supported optional integrations include:

Incident Management: ServiceNow (built-in Phase 2), PagerDuty, Opsgenie

Communication: Slack (auto-create incident channels), Microsoft Teams, Zoom

Observability: Datadog, New Relic, PagerDuty alerts

Document Storage: Google Drive, SharePoint/OneDrive, Confluence

Cloud Providers: AWS, Azure, GCP (for CI health enrichment)

See CONNECTORS.md in the repository for configuration details for each connector.

Troubleshooting Common Issues

“MCP server failed to start” — Make sure you ran npm install in the servers/runbook-generator directory. Also verify Node.js 18+ is installed (node --version).

“YAML validation failed” — Run /validate-yaml with your file path to get field-level error messages. The most common issues are missing required fields and incorrect date formats (must be ISO 8601).

“Output directory doesn’t exist” — The plugin creates the output directory automatically. If it fails, create it manually: mkdir -p output/.

Plugin not appearing after install — In Claude Cowork, make sure you selected the src/ directory (not the repository root). The src/ directory must contain .mcp.json at its root level.

What’s Next

You now have MIM-Runbook installed and generating runbooks. In Part 3 of this series, we’ll trace a real-world example — a multi-region BGP network outage — from input YAML through to the generated output, examining every section of the runbook.

If you missed it, Part 1 covers the business case: why incident response breaks down without structured runbooks and how MIM-Runbook addresses each failure mode.

The repository is open source under the MIT license at github.com/agentbee0/MIM-Runbook.