adr-writer
Interactive ADR (Architecture Decision Record) writing tool with PRD traceability. Facilitates architectural decisions through guided Q&A se
Open source Open in the app JSON README (API)
About
Interactive ADR (Architecture Decision Record) writing tool with PRD traceability. Facilitates architectural decisions through guided Q&A sessions.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- haandol
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 1
- Open pull requests
- 1
- Last push
- 2026-05-18T17:23:57Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
haandol/adr-writer/adr-writer
README
# ADR Writer
[](https://www.npmjs.com/package/adr-writer)
A [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.
## Features
- MADR-based ADR template with structured conversation guides per section
- Interactive Q&A workflow — AI asks focused questions, never auto-generates
- Document management — create, save, read, and track ADRs as Markdown
- Optional PRD (Product Requirements Document) traceability
- ADR lifecycle management (proposed, accepted, rejected, deprecated, superseded)
- Works with Claude Desktop, Claude Code, Cursor, Kiro, and any MCP-compatible client
## Quick Start
No installation required — just add the MCP config to your client:
```json
{
"mcpServers": {
"adr-writer": {
"command": "npx",
"args": ["-y", "adr-writer"]
}
}
}
```
### Client Setup
| Client | Config location |
| ------------------ | --------------------------------------------------------------------------------- |
| **Claude Desktop** | Settings > Developer > Edit Config (`claude_desktop_config.json`) |
| **Claude Code** | `claude mcp add adr-writer -- npx -y adr-writer` |
| **Cursor** | Settings > Features > MCP Servers > + Add new global MCP server |
| **Kiro** | `Cmd+Shift+P` > "Kiro: Open user MCP config (JSON)" (`~/.kiro/settings/mcp.json`) |
### Environment Variables
| Variable | Description | Default |
| ---------------- | -------------------------------------------------- | ------------------------- |
| `ADR_OUTPUT_DIR` | Directory for ADR files (`docs/adr/` subdirectory) | Current working directory |
Config example with `ADR_OUTPUT_DIR`:
```json
{
"mcpServers": {
"adr-writer": {
"command": "npx",
"args": ["-y", "adr-writer"],
"env": {
"ADR_OUTPUT_DIR": "~/projects/my-app"
}
}
}
}
```
## Available Tools
### Template 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 |
### Document Management Tools
| Tool | Description |
| -------------------- | --------------------------------------------------- |
| `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 |
| `load_prd` | Load a PRD file for feature traceability (optional) |
| `list_prd_features` | List PRD features and their ADR status |
## Workflow
The server guides AI through a structured workflow:
1. **Initialize** — `get_adr_overview()` to understand the ADR process
2. **(Optional)** — `load_prd(prd_path)` to load PRD for traceability
3. **Create** — `init_adr({ title })` to create a new ADR
4. **For each section** (context, decision_drivers, considered_options, decision_outcome, consequences, confirmation):
- `get_adr_section_guide(section)` — get questions and criteria
- Ask focused questions (1-2 at a time)
- `save_adr_section(adr_id, section, content)` — save after user confirmation
5. **Finalize** — `update_adr_status(adr_id, "accepted")` after review
## ADR Sections
| Section | Description |
| ------------------ | -------------------------------------------------------- |
| Context | Problem statement and forces at play |
| Decision Drivers | Key factors influencing the decision |
| Considered Options | At least 2 alternatives with pros/cons |
| Decision Outcome | Chosen option and rationale |
| Consequences | Positive, negative, and neutral impacts |
| Confirmation | How to verify the decision was implemented correctly |
## Development
### Running from Source
```bash
git clone https://github.com/haandol/adr-writer.git
cd adr-writer
pnpm install
pnpm build
```
Then configure your MCP client:
```json
{
"mcpServers": {
"adr-writer": {
"command": "node",
"args": ["/path/to/adr-writer/dist/index.js"]
}
}
}
```
### Commands
```bash
pnpm install # Install dependencies
pnpm dev # Run with tsx (watch mode)
pnpm build # Build for production
pnpm start # Run built version
```
## License
MIT