ADR Writer - MCP Server

Architecture Decision Record (ADR) writer as an MCP server for Claude Code. Interactively create, manage, and track ADRs with optional PRD traceability.

Installation

Claude Code Plugin

claude mcp add adr-writer -- npx -y adr-writer

Manual Configuration

Add to your Claude Code MCP settings (.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "adr-writer": {
      "command": "npx",
      "args": ["-y", "adr-writer"]
    }
  }
}

Features

• Interactive ADR creation following MADR (Markdown Any Decision Records) format
• Section-by-section guided conversation for each ADR
• Optional PRD (Product Requirements Document) traceability
• ADR lifecycle management (proposed, accepted, rejected, deprecated, superseded)
• ADR listing and status tracking

Available Tools

| Tool | Description | |------|-------------| | get_adr_overview | Get the ADR workflow overview and conversation guide | | get_adr_template | Get the ADR markdown template (MADR-based) | | get_adr_section_guide | Get conversation guide for a specific ADR section | | list_adr_sections | List all ADR sections | | load_prd | Load a PRD file for feature traceability (optional) | | list_prd_features | List PRD features and their ADR status | | init_adr | Initialize a new ADR | | save_adr_section | Save content to an ADR section | | read_adr | Read the full content of an ADR | | update_adr_status | Update ADR status | | list_adrs | List all ADRs with status | | set_adr_dir | Override the ADR output directory |

Workflow

1. get_adr_overview() - Start here to understand the ADR process
2. (Optional) load_prd(prd_path) - Load PRD for traceability
3. init_adr({ title }) - Create a new ADR
4. For each section (context, decision_drivers, considered_options, decision_outcome, consequences, confirmation):
   • get_adr_section_guide(section) - Get the conversation guide
   • Interactive Q&A with the user
   • save_adr_section(adr_id, section, content) - Save after confirmation
5. update_adr_status(adr_id, "accepted") - Finalize the ADR

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | ADR_OUTPUT_DIR | Base directory for ADR output | Current working directory |

ADRs are saved to docs/adr/ relative to the output directory.

License

Apache-2.0