# rollout-playbook-mcp

An MCP (Model Context Protocol) server that turns enterprise deployment best practices into resources and tools an AI assistant can use directly, instead of leaving them as static documents nobody re-reads once a project starts.

## Why I built this

I spent years leading the teams that designed and deployed telco networks in the voice and wireless space, hundreds of production deployments for carriers worldwide. The hardest part was never the individual project. It was capturing what we learned each time and getting it into the hands of the next team fast enough to matter, so my team documented the patterns and built internal tools around them.

This is a small, deliberately scoped version of that same idea, rebuilt with AI in mind: instead of a static playbook doc that lives in a wiki nobody opens, the patterns are exposed as MCP resources an assistant can read, and as tools that generate a tailored plan on request. It's a toy compared to a real enterprise deployment practice, but the underlying instinct is the same one I've applied throughout my career and am now applying to Navi, an enterprise agentic AI platform I lead at IBM/HashiCorp: get expert knowledge out of a document and into the hands of whoever needs it, exactly when they need it.

## What it does

**Resources** — four playbooks, exposed as browsable documents:
- Rollout Checklist (phase-by-phase deployment checklist)
- Risk Assessment Framework (score a deployment's risk before committing to a plan)
- Stakeholder RACI Template (who owns what, by phase)
- Migration Cutover Plan (the specific moment traffic/data/users move to the new system)

**Tools**:
- `search_playbooks(query)` — keyword search across all four playbooks, returns matching sections
- `generate_rollout_plan(project_type, team_size, risk_level)` — generates a tailored rollout plan by combining the playbooks based on your inputs

**Prompt**:
- `assess_deployment_risk(project_description)` — a pre-built prompt template that walks through the risk framework for a given project

## Quick start

```bash
git clone https://github.com/<your-username>/rollout-playbook-mcp.git
cd rollout-playbook-mcp
npm install
npm run build
npm start
```

The server communicates over stdio, so it's meant to be launched by an MCP client (Claude Desktop, Cursor, etc.), not run standalone in a terminal for interactive use.

### Connecting it to an MCP client

Add to your client's MCP config (for example `claude_desktop_config.json` or a project's `.mcp.json`):

```json
{
  "mcpServers": {
    "rollout-playbook": {
      "command": "node",
      "args": ["/absolute/path/to/rollout-playbook-mcp/dist/index.js"]
    }
  }
}
```

## Architecture

- Built on `@modelcontextprotocol/sdk` (TypeScript), using the high-level `McpServer` API
- Playbook content is authored as markdown in `/playbooks`, then compiled into `src/playbooks.ts` as embedded string constants, so the built package is self-contained and works over `npx` without relying on relative file paths at runtime
- Transport is stdio, the standard choice for a locally-run MCP server invoked by a desktop client

## Project structure

```
rollout-playbook-mcp/
├── playbooks/              # Source markdown for each playbook
├── src/
│   ├── playbooks.ts         # Generated: embedded playbook content
│   └── index.ts             # Server: resources, tools, prompt
├── package.json
├── tsconfig.json
└── README.md
```

## License

MIT