mdblu Docs

Overview

mdblu is a library of Markdown templates designed specifically for AI workflows. Each template has a structure that Claude can reason about without open-ended interpretation — every section has a clear purpose and expected content type.

An MCP server exposes the templates programmatically, so Claude can scaffold them, propose updates, and hook into your project's document lifecycle without copy-paste.

Connect the server

Add mdblu to your Claude Desktop config:

{
  "mcpServers": {
    "mdblu": {
      "command": "node",
      "args": ["/path/to/mdblu/dist/index.js"]
    }
  }
}

See the GitHub repo for full setup instructions including the hosted MCP server option.

Use a template

Scaffold a template directly from the CLI or via Claude:

mdblu use MISSION

This writes a MISSION.md to the current directory with all sections pre-populated with guidance comments.

MISSION

Captures why the project exists, what success looks like, and the constraints Claude must respect. Typically placed at project root and referenced in AGENT.md.

Key sections: Vision, Goals, Non-goals, Success metrics, Constraints.

SPEC

Defines a feature or system at implementation level — inputs, outputs, behavior, edge cases. Written before coding begins, referenced throughout implementation.

Key sections: Problem, Solution, API / Interface, Edge cases, Open questions.

ADR

Architecture Decision Record — documents a significant technical decision, the options considered, and the rationale for the choice made. Immutable once recorded.

Key sections: Context, Decision, Options considered, Consequences.

HANDOFF

Packages the current state of a piece of work for handoff between sessions or collaborators. Prevents context loss between Claude sessions.

Key sections: Current state, What was done, What's next, Known blockers, Files changed.

use_template

use_template({ template: "SPEC", path: "docs/spec-auth.md" })

Scaffolds the named template at the specified path. Claude fills in context-aware content if the project has a MISSION.md or AGENT.md.

propose_template_update

propose_template_update({
  template: "HANDOFF",
  section: "Files changed",
  suggestion: "Add a 'Diff summary' subsection..."
})

Opens a PR against the mdblu repo with the proposed change. Accepted suggestions improve the template for all users.

scaffold_hook

Registers a lifecycle hook that fires when Claude finishes a task — for example, auto-scaffolding a HANDOFF on session end:

scaffold_hook({ event: "session_end", template: "HANDOFF" })

Documentation