{
  "markdown": "# ADR Writer\n\n[![npm version](https://img.shields.io/npm/v/adr-writer.svg)](https://www.npmjs.com/package/adr-writer)\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that helps you write ADRs (Architecture Decision Records) interactively with AI. Guides you through structured sections with templates, conversation guides, and document management based on [MADR](https://adr.github.io/madr/) format.\n\n## Features\n\n- MADR-based ADR template with structured conversation guides per section\n- Interactive Q&A workflow — AI asks focused questions, never auto-generates\n- Document management — create, save, read, and track ADRs as Markdown\n- Optional PRD (Product Requirements Document) traceability\n- ADR lifecycle management (proposed, accepted, rejected, deprecated, superseded)\n- Works with Claude Desktop, Claude Code, Cursor, Kiro, and any MCP-compatible client\n\n## Quick Start\n\nNo installation required — just add the MCP config to your client:\n\n```json\n{\n  \"mcpServers\": {\n    \"adr-writer\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"adr-writer\"]\n    }\n  }\n}\n```\n\n### Client Setup\n\n| Client             | Config location                                                                   |\n| ------------------ | --------------------------------------------------------------------------------- |\n| **Claude Desktop** | Settings > Developer > Edit Config (`claude_desktop_config.json`)                 |\n| **Claude Code**    | `claude mcp add adr-writer -- npx -y adr-writer`                                 |\n| **Cursor**         | Settings > Features > MCP Servers > + Add new global MCP server                   |\n| **Kiro**           | `Cmd+Shift+P` > \"Kiro: Open user MCP config (JSON)\" (`~/.kiro/settings/mcp.json`) |\n\n### Environment Variables\n\n| Variable         | Description                                        | Default                   |\n| ---------------- | -------------------------------------------------- | ------------------------- |\n| `ADR_OUTPUT_DIR` | Directory for ADR files (`docs/adr/` subdirectory) | Current working directory |\n\nConfig example with `ADR_OUTPUT_DIR`:\n\n```json\n{\n  \"mcpServers\": {\n    \"adr-writer\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"adr-writer\"],\n      \"env\": {\n        \"ADR_OUTPUT_DIR\": \"~/projects/my-app\"\n      }\n    }\n  }\n}\n```\n\n## Available Tools\n\n### Template Tools\n\n| Tool                    | Description                                        |\n| ----------------------- | -------------------------------------------------- |\n| `get_adr_overview`      | Get the ADR workflow overview and conversation guide |\n| `get_adr_template`      | Get the ADR markdown template (MADR-based)         |\n| `get_adr_section_guide` | Get conversation guide for a specific ADR section  |\n| `list_adr_sections`     | List all ADR sections                              |\n\n### Document Management Tools\n\n| Tool                 | Description                                         |\n| -------------------- | --------------------------------------------------- |\n| `init_adr`           | Initialize a new ADR                                |\n| `save_adr_section`   | Save content to an ADR section                      |\n| `read_adr`           | Read the full content of an ADR                     |\n| `update_adr_status`  | Update ADR status                                   |\n| `list_adrs`          | List all ADRs with status                           |\n| `set_adr_dir`        | Override the ADR output directory                   |\n| `load_prd`           | Load a PRD file for feature traceability (optional) |\n| `list_prd_features`  | List PRD features and their ADR status              |\n\n## Workflow\n\nThe server guides AI through a structured workflow:\n\n1. **Initialize** — `get_adr_overview()` to understand the ADR process\n2. **(Optional)** — `load_prd(prd_path)` to load PRD for traceability\n3. **Create** — `init_adr({ title })` to create a new ADR\n4. **For each section** (context, decision_drivers, considered_options, decision_outcome, consequences, confirmation):\n   - `get_adr_section_guide(section)` — get questions and criteria\n   - Ask focused questions (1-2 at a time)\n   - `save_adr_section(adr_id, section, content)` — save after user confirmation\n5. **Finalize** — `update_adr_status(adr_id, \"accepted\")` after review\n\n## ADR Sections\n\n| Section            | Description                                              |\n| ------------------ | -------------------------------------------------------- |\n| Context            | Problem statement and forces at play                     |\n| Decision Drivers   | Key factors influencing the decision                     |\n| Considered Options | At least 2 alternatives with pros/cons                   |\n| Decision Outcome   | Chosen option and rationale                              |\n| Consequences       | Positive, negative, and neutral impacts                  |\n| Confirmation       | How to verify the decision was implemented correctly     |\n\n## Development\n\n### Running from Source\n\n```bash\ngit clone https://github.com/haandol/adr-writer.git\ncd adr-writer\npnpm install\npnpm build\n```\n\nThen configure your MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"adr-writer\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/adr-writer/dist/index.js\"]\n    }\n  }\n}\n```\n\n### Commands\n\n```bash\npnpm install    # Install dependencies\npnpm dev        # Run with tsx (watch mode)\npnpm build      # Build for production\npnpm start      # Run built version\n```\n\n## License\n\nMIT\n",
  "bytes": 5518,
  "sha": "6258b1e56f04216a820bf92f47dbfc939febd298af7c5ddfc94b3293c7269953",
  "repo_slug": "haandol/adr-writer",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_haandol_adr_writer_adr_writer_839db02f/readme"
}