Bmad Mcp Agents

A BMAD v6 research platform that validates MCP-based storage for AI-driven development workflows.

BMAD (Build Me A Dream) is an AI-assisted software development method that orchestrates a team of specialized agents — PM, Architect, Developer, QA, and others — through structured workflows to produce full software projects from scratch. This repository takes a standard BMAD installation and adds one architectural experiment on top: all artifact I/O is routed through a custom MCP server instead of touching the filesystem directly.

The result is a working proof-of-concept where BMAD workflows run completely unmodified, yet every planning document, epic, and story is stored and retrieved through a protocol-level abstraction layer.

Table of Contents

1. The MCP Storage Gateway
2. BMAD Agent Customization
3. Example Project — Todo List App
4. Project Structure
5. Further Reading

The MCP Storage Gateway

Why It Was Built

BMAD workflows instruct agents to read and write artifacts to specific paths (PRDs, architecture docs, epics, stories, etc.). By default those operations land directly on the filesystem. This works, but it tightly couples the workflow runtime to a single storage backend.

The MCP Storage Gateway was built to break that coupling:

• Swap backends without touching workflows — a single config field determines which provider is active (storage-a or storage-b); the workflow instructions never change.
• Open the path to non-filesystem backends — the same abstraction can later front a database, object store, or remote API with no impact on agent behavior.
• Make artifact I/O observable — all requests pass through a single server, enabling logging, validation, and auditing at one point (MCP_LOG_FILE env var activates request logging).

What It Is

The gateway is a stdio MCP server — no HTTP, no WebSockets. The host spawns it as a child process and communicates via stdin/stdout using line-delimited JSON:

→ {"id":"1","method":"document.createDocument","params":{...}}
← {"id":"1","result":{...}}

It exposes a three-tier API:

| Tier | Namespace | Purpose | |---|---|---| | Raw storage | storage.* | Read, write, patch text; list paths; stat | | Business documents | document.* | Structured document model with sections and metadata | | Agile artifacts | epic.* / story.* | Full CRUD for epics and user stories with AC, task lists, status lifecycle |

Artifacts are addressed with a bmad:// URI scheme:

bmad://{tenant}/{project}/{relative-path}

Example: bmad://default/generic-workflow/planning-artifacts/prd

Storage Providers

Two providers are configured out of the box, selectable via config.json:

| Provider | Maps to | |---|---| | fs-primary | _bmad-output/storage-a/ | | fs-secondary | _bmad-output/storage-b/ |

Switching the active provider is a one-field change in mcp/storage_gateway/config.example.json.

Key Files

| File | Role | |---|---| | mcp/storage_gateway/src/server.ts | Main server — readline loop and all method handlers | | mcp/storage_gateway/src/shim.ts | Tool-call interceptor — routes BMAD paths to MCP, passes everything else through | | mcp/storage_gateway/src/hostBridge.ts | Host integration point — createBmadMcpHostBridge(config) with interceptToolCall() | | mcp/storage_gateway/src/mcpClient.ts | Persistent stdio client with request/response matching by id |

BMAD Agent Customization

How BMAD Customization Works

BMAD provides a safe, upgrade-proof customization mechanism via .customize.yaml files. One file exists per agent and lives under _bmad/_config/agents/. You edit these files rather than the agent files themselves — the installer preserves your customizations across updates, while agent files are freely overwritten.

Each file supports five optional sections:

| Section | Behavior | Use case | |---|---|---| | agent.metadata | Replaces | Override the agent's display name | | persona | Replaces | Set role, identity, style, and principles | | memories | Appends | Add persistent context the agent always recalls | | menu | Appends | Add custom menu items for workflows or prompts | | critical_actions | Appends | Define startup instructions the agent executes on wake |

After editing, run npx bmad-method install and select Recompile Agents to apply changes.

Full documentation: https://docs.bmad-method.org/how-to/customize-bmad/

How This Project Uses Customization

Every agent in this project is customized to enforce the MCP-first storage policy: agents must route all artifact I/O through the MCP server and must never fall back to direct filesystem access.

What the Policy Enforces

All agents receive these rules via memories:

• MCP-first I/O — use document.* for business documents, epic.*/story.* for agile artifacts, storage.* only for unstructured artifacts
• Fail-closed rule — if the MCP server is unavailable, the agent must hard-stop and alert the user; silent filesystem fallback is forbidden
• Pre-response self-check — before every response the agent verifies it has not used any forbidden direct filesystem tool

Per-Agent Enforcement Level

Agents are grouped into two tiers based on their proximity to artifact production:

| Tier | Agents | Additional critical_actions | |---|---|---| | Full enforcement | architect, dev, pm, qa, quick-flow-solo-dev, tech-writer | No direct FS access; translate all workflow artifact instructions to MCP calls; strict policy adherence | | Lighter enforcement | bmad-master, analyst, sm, ux-designer | Load agent-storage-policy.md on startup; block discovery-search on artifact paths |

The distinction reflects role: agents that create or modify planning and implementation artifacts carry the strictest rules, while orchestration and lighter-touch roles rely primarily on the shared memories block.

Example Project — Todo List App

To validate the full stack end-to-end, a complete BMAD project run was executed through the MCP gateway. The imaginary product: a lightweight web-based Todo List application for personal task management.

Tech Stack (chosen by the Architect agent)

React 19 · TypeScript 5 (strict) · Vite 6 · Tailwind CSS v4 · Vitest + React Testing Library · Vercel (static SPA, GitHub CI/CD) · localStorage (no backend, no PII)

Artifacts Produced

Every artifact below was created and retrieved exclusively through MCP — zero direct filesystem writes from agents.

Planning documents (storage-a/documents/planning-artifacts/)

| Document | Description | |---|---| | prd | Product Requirements Document — vision, 20 FRs, 13 NFRs, user journeys | | architecture | Architecture Decision Document — stack decisions and deployment model | | epics | Epic Breakdown — epics and stories mapped to PRD requirements |

Epics and stories (storage-a/epics/, storage-a/stories/)

| Epic | Title | Goal | |---|---|---| | Epic 1 | Project Foundation & Infrastructure | Working deployed skeleton — Vite + React + TS + Tailwind scaffold, CI/CD on Vercel | | Epic 2 | Core Todo Experience | Add, view, complete, and delete todos with localStorage persistence | | Epic 3 | Responsive & Accessible Experience | WCAG 2.1 AA compliance, keyboard-only support, works from 320 px up |

12 stories were produced in total (3 in Epic 1, 5 in Epic 2, 4 in Epic 3), each with acceptance criteria and task breakdowns.

Storage Layout

_bmad-output/storage-a/
├── documents/
│   └── planning-artifacts/
│       ├── prd.json
│       ├── architecture.json
│       └── epics.json
├── epics/
│   ├── epic-1.json
│   ├── epic-2.json
│   └── epic-3.json
└── stories/
    ├── story-1-1.json  story-1-2.json  story-1-3.json
    ├── story-2-1.json  story-2-2.json  story-2-3.json
    │   story-2-4.json  story-2-5.json
    └── story-3-1.json  story-3-2.json  story-3-3.json  story-3-4.json

All JSON files are structured models (not flat markdown), enabling the document.* / epic.* / story.* API tiers to serve them with field-level precision.

Project Structure

The sections of the repo relevant to this README:

generic-workflow/
├── mcp/
│   └── storage_gateway/        # MCP Storage Gateway server
│       ├── src/
│       │   ├── server.ts        # Main server + all method handlers
│       │   ├── shim.ts          # Tool-call interceptor
│       │   ├── hostBridge.ts    # Host integration point
│       │   └── mcpClient.ts     # Persistent stdio client
│       ├── config.example.json  # Primary provider config (storage-a)
│       └── config.secondary.json
│
├── _bmad/
│   └── _config/
│       └── agents/             # Per-agent .customize.yaml files
│           ├── core-bmad-master.customize.yaml
│           ├── bmm-analyst.customize.yaml
│           ├── bmm-architect.customize.yaml
│           ├── bmm-dev.customize.yaml
│           ├── bmm-pm.customize.yaml
│           ├── bmm-qa.customize.yaml
│           ├── bmm-sm.customize.yaml
│           ├── bmm-tech-writer.customize.yaml
│           ├── bmm-ux-designer.customize.yaml
│           └── bmm-quick-flow-solo-dev.customize.yaml
│
├── _bmad-output/
│   └── storage-a/              # All MCP-produced artifacts (example project)
│       ├── documents/
│       ├── epics/
│       └── stories/
│
└── docs/
    └── mcp/                    # Design docs and test plans

Further Reading

| Document | Description | |---|---| | docs/mcp/agent-storage-policy.md | Canonical agent policy: method mapping, fail-closed rule, glob override rules |