@h2nguyen/arc42-node-mcp-server

v2.2.1

Published

a month ago

MCP server for arc42 architecture documentation - AI-assisted architecture documentation following arc42 template

0High
0Medium
0Low

h2nguyen

arc42 architecture documentation mcp model-context-protocol ai-assisted software-architecture technical-documentation

Arc42 Node MCP Server

AI-Assisted Architecture Documentation following the arc42 Template

A Model Context Protocol (MCP) server that helps you create comprehensive architecture documentation using the proven arc42 template. Perfect for AI-assisted documentation with Claude, Cursor, Cline and other MCP-compatible tools.

Table of Content

📋 What is arc42?

arc42 is a template for architecture communication and documentation. It provides a clear structure for documenting software and system architectures, making them understandable for all stakeholders.

This MCP server brings arc42 to the age of AI-assisted development, allowing you to:

🤖 Generate architecture documentation with AI assistance
📊 Follow the proven structure across twelve well-defined sections
✅ Track documentation progress and completeness
🔄 Maintain consistent, up-to-date architecture docs
🌍 Share knowledge across worldwide development teams

arc42 Template Reference

This MCP server dynamically reads version information from the arc42 template git submodule at runtime.

| Property | Value | |----------------|-----------------------------------------------------------------| | Source | arc42/arc42-template | | Submodule Path | vendor/arc42-template | | Version File | vendor/arc42-template/EN/version.properties |

Note: This server provides native templates in both AsciiDoc and Markdown formats for all 11 supported languages. AsciiDoc is the default format for new projects.

To display the current arc42 template version:

npm run show:arc42-version

Updating to the Latest arc42 Template

This project uses a dynamic version loading approach:

Git submodule (vendor/arc42-template) provides the upstream template
Version info is read dynamically from vendor/arc42-template/EN/version.properties at runtime
No hardcoded values - the version always reflects the checked-out submodule state

To update to the latest arc42 template version:

# Update submodule and display new version
npm run update:arc42

# Or manually:
npm run submodule:update       # Pull latest from upstream
npm run show:arc42-version     # Display new version info

# Review and test
npm test                       # Ensure tests pass
git diff                       # Review changes
git add vendor/arc42-template  # Stage submodule update

For contributors cloning the repo, initialize the submodule:

git clone --recurse-submodules https://github.com/h2nguyen/Arc42-Node-MCP-Server.git
# Or after cloning:
npm run submodule:init

Note for npm package users: The submodule is not included in the npm package. Fallback values are used when the submodule is unavailable.

🚀 Quick Start

Installation

# Install globally (installs latest version by default)
npm install -g @h2nguyen/arc42-node-mcp-server

# Or install a specific version
npm install -g @h2nguyen/arc42-node-mcp-server@<version>

Tip: Check npm or GitHub Releases for available versions.

Setup in Claude Desktop

Add to your Claude configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Using npx (no installation required):

{
  "mcpServers": {
    "arc42-mcp-server": {
      "command": "npx",
      "args": ["-y", "@h2nguyen/arc42-node-mcp-server", "/path/to/your/project"]
    }
  }
}

Using global installation:

{
  "mcpServers": {
    "arc42-mcp-server": {
      "command": "arc42-mcp",
      "args": ["/path/to/your/project"]
    }
  }
}

Setup in Cursor

Add to your MCP settings in Cursor:

Using npx (no installation required):

{
  "mcpServers": {
    "arc42-mcp-server": {
      "command": "npx",
      "args": ["-y", "@h2nguyen/arc42-node-mcp-server", "${workspaceFolder}"]
    }
  }
}

Using global installation:

{
  "mcpServers": {
    "arc42-mcp-server": {
      "command": "arc42-mcp",
      "args": ["${workspaceFolder}"]
    }
  }
}

Setup in Cline

Add to your Cline MCP settings file (~/.cline/data/settings/cline_mcp_settings.json):

Using npx (no installation required):

{
  "mcpServers": {
    "arc42-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@h2nguyen/arc42-node-mcp-server", "/path/to/your/project"],
      "autoApprove": [
        "arc42-workflow-guide",
        "arc42-init",
        "arc42-status",
        "update-section",
        "generate-template",
        "get-section"
      ]
    }
  }
}

⚠️ Important for NVM users: For the npx approach to work with NVM, you may need to use the full path to npx: /path/to/.nvm/versions/node/vXX.X.X/bin/npx

Using npm package with NVM:

⚠️ Important for NVM users: Cline spawns MCP servers without loading your shell profile (.zshrc/.bashrc), so NVM-managed Node.js paths are not in PATH. You must use full absolute paths to both the Node.js binary and the arc42-mcp command. See Troubleshooting: NVM Users for details.

{
  "mcpServers": {
    "arc42-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "/path/to/.nvm/versions/node/vXX.X.X/bin/node",
      "args": [
        "/path/to/.nvm/versions/node/vXX.X.X/bin/arc42-mcp",
        "/path/to/your/project"
      ],
      "autoApprove": [
        "arc42-workflow-guide",
        "arc42-init",
        "arc42-status",
        "update-section",
        "generate-template",
        "get-section"
      ]
    }
  }
}

To find your NVM paths, run:

# Get the Node.js binary path
nvm which current
# Example output: /Users/yourname/.nvm/versions/node/v24.13.0/bin/node

# The arc42-mcp command is in the same bin directory
# /Users/yourname/.nvm/versions/node/v24.13.0/bin/arc42-mcp

Using npm package without NVM (system Node.js):

If Node.js is installed system-wide (not via NVM), you can use the simpler configuration:

{
  "mcpServers": {
    "arc42-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "arc42-mcp",
      "args": ["/path/to/your/project"],
      "autoApprove": [
        "arc42-workflow-guide",
        "arc42-init",
        "arc42-status",
        "update-section",
        "generate-template",
        "get-section"
      ]
    }
  }
}

Using local build:

{
  "mcpServers": {
    "arc42-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "node",
      "args": [
        "/path/to/Arc42-Node-MCP-Server/dist/index.js",
        "/path/to/your/project"
      ],
      "autoApprove": [
        "arc42-workflow-guide",
        "arc42-init",
        "arc42-status",
        "update-section",
        "generate-template",
        "get-section"
      ]
    }
  }
}

Note: For local builds with NVM, use the full path to the Node.js binary as the command instead of just node.

Troubleshooting: NVM Users

If you see "MCP error -32001: Request timed out" or the server fails to start, this is typically caused by NVM path issues:

Problem: Cline spawns processes without sourcing shell profiles, so node and arc42-mcp commands resolve to system paths (or aren't found at all) instead of NVM-managed versions.
Solution: Use full absolute paths in your configuration:
- command: Full path to the Node.js binary (e.g., ~/.nvm/versions/node/v24.13.0/bin/node)
- First args item: Full path to arc42-mcp (e.g., ~/.nvm/versions/node/v24.13.0/bin/arc42-mcp)
Why both paths?: Even if you use the full path to arc42-mcp, the script's shebang (#!/usr/bin/env node) will resolve node from PATH, which may point to an incompatible system Node.js version. By specifying Node.js directly as the command, we bypass the shebang entirely.

Understanding Workspace Configuration

The arc42 MCP server needs to know where to create and manage documentation files. There are two ways to configure this:

Option 1: Default Workspace Path (Server Startup Argument)

When starting the MCP server, you can provide a default workspace path as a command line argument:

node dist/index.js /path/to/my-project

This sets /path/to/my-project as the default location. The server will create documentation at /path/to/my-project/arc42-docs/.

In MCP configurations:

Claude Desktop: "args": ["/path/to/your/project"]
Cursor: "args": ["${workspaceFolder}"] (dynamically uses the current project)
Cline: "args": ["/path/to/dist/index.js", "/path/to/default/project"]

If no path is provided, the server uses the current working directory (process.cwd()).

Option 2: Dynamic targetFolder Parameter (Per-Tool Override)

Each tool call can include an optional targetFolder parameter to override the default workspace:

arc42-init {
  "projectName": "My Project",
  "targetFolder": "/Users/me/another-project"
}

This is useful when:

You want to work with multiple projects without reconfiguring the server
You're using Cline/other AI assistants where workspace context may vary
You want the AI agent to dynamically choose where to write documentation

Priority: targetFolder parameter (if provided) > Server startup argument > Current working directory

Recommendation

| Use Case | Recommendation | |----------------------------|------------------------------------------| | Single project focus | Set default path in server args | | Multi-project workflow | Use targetFolder parameter dynamically | | IDE with workspace support | Use ${workspaceFolder} variable | | Cline/AI agents | Omit default path, use targetFolder |

First Steps

Start with the guide: Ask your AI assistant to run arc42-workflow-guide
Initialize documentation: Use arc42-init with your project name
Check status: Run arc42-status to see your progress
Generate templates: Use generate-template for specific sections
Document iteratively: Use update-section to add content

🛠️ Available Tools

arc42-workflow-guide

Load the complete arc42 documentation workflow guide with instructions for all 12 sections.

arc42-workflow-guide {
  language?: "EN" | "DE" | "ES" | ...  // Optional: language code (default: EN)
  format?: "asciidoc" | "markdown"     // Optional: output format (default: asciidoc)
}

arc42-init

Initialize arc42 documentation workspace for your project.

arc42-init {
  projectName: "Your Project Name",
  language?: "EN",       // Optional: language for templates (default: EN)
  format?: "asciidoc",   // Optional: output format (default: asciidoc)
  force?: false,         // Re-initialize even if exists
  targetFolder?: "/path/to/project"  // Optional: specify target directory
}

arc42-status

Check the status of your documentation, including completion percentage and section details.

arc42-status {
  targetFolder?: "/path/to/project"  // Optional: specify target directory
}
// Returns: language info, format info, available languages/formats, and localized section titles

generate-template

Generate a detailed template for any of the 12 arc42 sections.

generate-template {
  section: "01_introduction_and_goals" | "02_architecture_constraints" | ...,
  language?: "EN" | "DE" | "ES" | ...  // Optional: language code (default: EN)
  format?: "asciidoc" | "markdown"     // Optional: output format (default: asciidoc)
}

update-section

Update content in a specific arc42 section.

update-section {
  section: "01_introduction_and_goals",
  content: "= Your AsciiDoc or Markdown content here",
  mode?: "replace" | "append",
  targetFolder?: "/path/to/project"  // Optional: specify target directory
}
// Note: Automatically detects format from existing file extension

get-section

Read content from a specific arc42 section.

get-section {
  section: "01_introduction_and_goals",
  targetFolder?: "/path/to/project"  // Optional: specify target directory
}
// Note: Supports both .md and .adoc file formats

🌍 Multi-Language Support

This MCP server supports documentation templates in 11 languages, matching the official arc42 template translations.

Supported Languages

| Code | Language | Native Name | |------|------------|-------------| | EN | English | English | | DE | German | Deutsch | | ES | Spanish | Español | | FR | French | Français | | IT | Italian | Italiano | | NL | Dutch | Nederlands | | PT | Portuguese | Português | | RU | Russian | Русский | | CZ | Czech | Čeština | | UKR | Ukrainian | Українська | | ZH | Chinese | 中文 |

Using Languages

Initialize with a specific language:

arc42-init {
  projectName: "Mein Projekt",
  language: "DE"  // German templates and section titles
}

Generate templates in a specific language:

generate-template {
  section: "01_introduction_and_goals",
  language: "FR"  // French template
}

Get workflow guide in a specific language:

arc42-workflow-guide {
  language: "ES"  // Spanish guide
}

Language Configuration

The language is stored in config.yaml when you initialize a workspace:

projectName: My Project
language: DE
format: asciidoc

arc42-status reads and displays the configured language
Templates and section titles are localized based on this setting
Language codes are case-insensitive (de, DE, De all work)

📄 Multi-Format Support

This MCP server supports documentation output in 2 formats: Markdown and AsciiDoc.

Supported Formats

| Code | Format | Extension | Aliases | |------------|----------|-----------|------------------------------| | asciidoc | AsciiDoc | .adoc | adoc, ascii, asciidoctor, asc | | markdown | Markdown | .md | md, mdown, mkd |

Default: AsciiDoc is the default format for new projects. AsciiDoc provides richer formatting features (includes, admonitions, cross-references) ideal for professional documentation.

Using Formats

Initialize with a specific format:

arc42-init {
  projectName: "My Project",
  format: "markdown"  // Use Markdown instead of default AsciiDoc
}

Generate templates in a specific format:

generate-template {
  section: "01_introduction_and_goals",
  format: "asciidoc"  // AsciiDoc template
}

Get workflow guide in a specific format:

arc42-workflow-guide {
  format: "markdown"  // Markdown guide
}

Combine language and format:

arc42-init {
  projectName: "Mein Projekt",
  language: "DE",
  format: "asciidoc"  // German AsciiDoc templates
}

Format Configuration

The format is stored in config.yaml when you initialize a workspace:

projectName: My Project
language: EN
format: asciidoc

arc42-status reads and displays the configured format
update-section automatically detects file format from extension
get-section supports both .md and .adoc files
Format codes are case-insensitive and support aliases (adoc, ASCIIDOC, md all work)

📚 The 12 arc42 Sections

Introduction and Goals - Requirements, quality goals, stakeholders
Architecture Constraints - Technical and organizational constraints
Context and Scope - Business and technical context
Solution Strategy - Fundamental decisions and strategies
Building Block View - Static decomposition of the system
Runtime View - Dynamic behavior and scenarios
Deployment View - Infrastructure and deployment
Cross-cutting Concepts - Overall regulations and approaches
Architecture Decisions - Important decisions (ADRs)
Quality Requirements - Quality tree and scenarios
Risks and Technical Debt - Known problems and risks
Glossary - Important terms

📖 Usage Examples

Example 1: Starting Fresh

You: "Help me create architecture documentation for my e-commerce platform"

AI runs: arc42-workflow-guide
AI runs: arc42-init { projectName: "E-Commerce Platform" }
AI runs: generate-template { section: "01_introduction_and_goals" }

AI: "Let's start with Section 1. What are your top 3 quality goals?"

Example 2: Document Specific Section

You: "Document the deployment architecture - we use AWS with ECS"

AI runs: generate-template { section: "07_deployment_view" }
AI creates content with your AWS/ECS details
AI runs: update-section { 
  section: "07_deployment_view",
  content: "..." 
}
AI runs: arc42-status

Example 3: Add Architecture Decision

You: "Document why we chose PostgreSQL over MongoDB"

AI runs: generate-template { section: "09_architecture_decisions" }
AI creates ADR with context, decision, and consequences
AI runs: update-section { 
  section: "09_architecture_decisions",
  content: "...",
  mode: "append"
}

🏗️ Project Structure

After initialization, your project will have:

your-project/
└── arc42-docs/
    ├── README.md                    # Getting started guide
    ├── arc42-documentation.md        # Main combined document
    ├── config.yaml                  # Configuration
    ├── images/                      # Diagrams and images
    └── sections/                    # Individual section files
        ├── 01_introduction_and_goals.md
        ├── 02_architecture_constraints.md
        ├── 03_context_and_scope.md
        ├── 04_solution_strategy.md
        ├── 05_building_block_view.md
        ├── 06_runtime_view.md
        ├── 07_deployment_view.md
        ├── 08_concepts.md
        ├── 09_architecture_decisions.md
        ├── 10_quality_requirements.md
        ├── 11_technical_risks.md
        └── 12_glossary.md

🎯 Best Practices

For AI Assistants

Always start with the guide: Run arc42-workflow-guide to understand the structure
Check status regularly: Use arc42-status to track progress
One section at a time: Focus on completing one section before moving to the next
Use diagrams: Generate Mermaid/PlantUML diagrams in the content
Ask clarifying questions: Don't assume - ask the user for specific details

For Users

Start with Section 1: Always begin with Introduction and Goals
Be iterative: You don't need to complete all sections immediately
Focus on decisions: Document WHY, not just WHAT
Keep it current: Update as architecture evolves
Use version control: Commit your arc42-docs directory to Git

🧠 Claude Skill for Arc42

This project includes a pre-built Claude Skill that teaches Claude (via Claude Code or any skill-aware Claude integration) how to effectively use the arc42 MCP server tools for architecture documentation — without manual prompting.

What Is the Arc42 Skill?

The skill is a structured knowledge package located at .claude/skills/arc42-docs-mcp/ containing:

.claude/skills/arc42-docs-mcp/
├── SKILL.md              # Skill definition with workflows, tool reference, and behavioral guidelines
└── references/
    ├── setup.md          # MCP server installation and configuration for all clients
    └── examples.md       # Practical usage examples (8 scenarios)

When present in a project, Claude automatically loads the skill and understands:

The correct workflow order for arc42 documentation (guide → init → status → template → write → review)
All 6 MCP tools, their parameters, and expected responses
Best practices such as always generating a template before writing, using append mode for ADRs, and asking clarifying questions before assuming project details
The recommended documentation order (Section 1 → 3 → 4 → 5 → 9, then fill the remaining sections)

Installing the Skill in Other Projects

To enable the arc42 skill in any project where Claude Code is used:

Option 1: Copy the skill directory

# From your project root
mkdir -p .claude/skills
cp -r /path/to/Arc42-Node-MCP-Server/.claude/skills/arc42-docs-mcp .claude/skills/

Option 2: Symlink (keeps the skill up-to-date)

# From your project root
mkdir -p .claude/skills
ln -s /path/to/Arc42-Node-MCP-Server/.claude/skills/arc42-docs-mcp .claude/skills/arc42-docs-mcp

Prerequisite: The arc42 MCP server must also be configured in your project's MCP settings (.mcp.json, Claude Desktop config, etc.). The skill teaches Claude how to use the tools, but the MCP server must be running to provide them. See Setup in Claude Desktop, Setup in Cursor, or Setup in Cline for server configuration.

After installation, commit the .claude/skills/arc42-docs-mcp/ directory to version control so all team members benefit from the skill automatically.

Skill Triggers

Claude activates the arc42 skill when it detects any of the following in conversation:

| Trigger | Examples | |-------------------------------------|----------------------------------------------------------------------------------------------| | Architecture documentation keywords | "create architecture documentation", "document the architecture", "update architecture docs" | | Arc42 references | "arc42", "initialize arc42", "arc42 template" | | Section-specific requests | "document the deployment view", "add quality requirements", "describe the building blocks" | | ADR mentions | "add an Architecture Decision Record", "document why we chose PostgreSQL" | | Any of the 12 arc42 sections | Introduction and Goals, Constraints, Context and Scope, Solution Strategy, etc. |

Benefits for Your Projects

| Benefit | Without Skill | With Skill | |------------------------|---------------------------------------------------|-----------------------------------------------------------------------------------| | Workflow knowledge | Must manually prompt Claude to follow arc42 order | Claude automatically follows guide → init → template → write workflow | | Tool usage | May call tools incorrectly or skip steps | Calls the right tools with correct parameters in the right sequence | | Content quality | Generic documentation output | Generates templates first, asks clarifying questions, documents WHY not just WHAT | | ADR handling | Risk of overwriting existing decisions | Always reads existing ADRs first and uses append mode | | Format awareness | May mix AsciiDoc and Markdown syntax | Checks arc42-status for configured format and writes consistently | | Multi-language | Defaults to English only | Respects configured language across all tool calls | | Team consistency | Each developer gets different results | Shared skill in version control ensures consistent documentation quality |

🔧 Development

Development Methodology

This project is developed using Spec Driven Development (SDD), a methodology that emphasizes creating detailed specifications before implementation. Features are planned, documented, and approved through a structured workflow before any code is written.

The SDD workflow is powered by @pimzino/spec-workflow-mcp, an MCP server that provides:

Structured specification workflow (Requirements → Design → Tasks → Implementation)
Real-time web dashboard for tracking progress
Approval gates between development phases
Implementation logging for knowledge preservation

Documentation Quality Assurance

Architecture documentation is reviewed and validated using dacli, a Documentation Access CLI that bridges LLMs with documentation projects. As an MCP server, dacli enables:

Hierarchical navigation and content retrieval of documentation
Full-text search across all documentation sections
Structure validation to detect orphaned files and issues
Programmatic querying and manipulation of AsciiDoc/Markdown content

Building from Source

git clone https://github.com/h2nguyen/Arc42-Node-MCP-Server.git
cd Arc42-Node-MCP-Server
npm install
npm run build

Running in Development Mode

npm run dev /path/to/your/project

🧪 Testing

This project maintains high-quality standards with a comprehensive test suite using Vitest.

Running Tests

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Test Structure

src/__tests__/
├── fixtures/
│   └── test-helpers.ts     # Shared test utilities and constants
├── templates/
│   └── index.test.ts       # Tests for all twelve arc42 templates
├── tools/
│   └── arc42-init.test.ts  # Tests for the arc42-init tool
└── types.test.ts           # Tests for types and constants

Coverage Thresholds

The project enforces minimum coverage thresholds to maintain quality:

| Metric | Threshold | |------------|-----------| | Statements | 70% | | Branches | 60% | | Functions | 70% | | Lines | 70% |

Test Categories

Unit Tests: Core functions, type helpers, and constants
Template Tests: All twelve arc42 section templates for structure and guidance content
Tool Tests: MCP tool definitions and execution behavior
Error Handling: Invalid inputs, edge cases, and graceful failure

CI/CD Pipeline

The GitHub Actions workflow runs automatically on pull requests and pushes:

Lint: TypeScript type checking and ESLint
Test: Multi-version Node.js matrix (22, 24) with coverage reporting
Docker: Container build verification
Security: npm audit for vulnerability scanning

🐳 Docker Support

Building the Docker Image

docker build -t arc42-node-mcp-server .

Running with Docker

# Run with a mounted project directory
docker run -v /path/to/project:/project arc42-node-mcp-server

# Interactive mode
docker run -it -v /path/to/project:/project arc42-node-mcp-server

Using Docker Compose

Docker Compose provides convenient setups for development and testing:

# Build the container
docker compose build

# Run the MCP server
docker compose run --rm arc42-node-mcp-server

# Run in development mode with live reload
docker compose up dev

Testing with MCP Inspector standalone (Recommended)

The MCP Inspector provides a web-based UI for testing MCP servers.

📖 Detailed Guide: See docs/mcp-inspector-testing.md for complete step-by-step instructions.

Quick Start with npx (Recommended):

# Build the project
npm run build

# Start MCP Inspector with the arc42 server
npx @modelcontextprotocol/inspector node dist/index.js ./test-project

Then open http://localhost:6274 in your browser.

Using Docker Compose:

# Prerequisites: Build the project first
npm run build

# Create a test directory
mkdir -p test-project

# Start MCP Inspector with the arc42 server
docker compose up mcp-inspector

Then open http://localhost:6274 in your browser. The server should auto-connect, and you'll see the six arc42 tools in the "Tools" tab, see the following screenshot:

Note: If auto-connect doesn't work, manually configure using container paths:
Command: node
Arguments: /app/dist/index.js /project
⚠️ Do NOT use local paths like /Users/yourname/... - these don't exist inside the Docker container.

Configuring MCP Inspector Manually (Standalone):

If running MCP Inspector standalone (not via Docker), configure these settings with your local absolute paths:

| Field | Value | |----------------|----------------------------------------------------------| | Transport Type | STDIO | | Command | node | | Arguments | /full/path/to/dist/index.js /full/path/to/test-project |

Click Connect to start testing the tools.

The Inspector allows you to:

Browse available tools (arc42-workflow-guide, arc42-init, arc42-status, etc.)
Execute tools with custom parameters
Inspect request/response payloads
Test the complete MCP protocol interaction

Docker Compose Services

| Service | Description | Usage | |-------------------------|------------------------------------|-----------------------------------------------------------| | arc42-node-mcp-server | Production-ready container | docker compose run --rm arc42-node-mcp-server | | mcp-inspector | MCP Inspector with stdio transport | docker compose up mcp-inspector → http://localhost:6274 | | dev | Development mode with live reload | docker compose up dev |

Testing Workflow

# 1. Create a test project directory
mkdir -p test-project

# 2. Build the project
npm run build

# 3. Start MCP Inspector
docker compose up mcp-inspector

# 4. Open browser at http://localhost:6274

# 5. Test tools:
#    - Call arc42-workflow-guide (no params)
#    - Call arc42-init with {"projectName": "Test Project"}
#    - Call arc42-status (no params)
#    - Call generate-template with {"section": "01_introduction_and_goals"}

🤝 Contributing

We welcome contributions! This project serves architecture documentation needs worldwide.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

📄 License

This project is licensed under the Apache License 2.0 – see the LICENSE file for details.

Note about arc42: This MCP server uses material from the arc42 architecture template (https://arc42.org and https://github.com/arc42/arc42-template). The arc42 template was created by Dr. Gernot Starke and Dr. Peter Hruschka and is licensed under Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0).

For software code attributions, see NOTICE.
For the full arc42 license terms, see LICENSE-ARC42.

🙏 Acknowledgments

arc42 - The proven, practical, and pragmatic architecture template
Dr. Gernot Starke and Dr. Peter Hruschka - Creators of arc42
Model Context Protocol - The protocol enabling AI tool use, including MCP Inspector for testing
@pimzino/spec-workflow-mcp - MCP server powering our Spec Driven Development workflow
dacli - Documentation Access CLI for reviewing and validating architecture documentation

📞 Support

Issues: GitHub Issues

🔗 Links

arc42 Website: https://arc42.org/
arc42 Documentation: https://docs.arc42.org/
arc42 GitHub: https://github.com/arc42
arc42 Examples: https://arc42.org/examples (Additional examples are embedded within the documentation at https://docs.arc42.org/)
arc42 FAQ: https://faq.arc42.org/
arc42 Node MCP Server on Github: https://github.com/h2nguyen/Arc42-Node-MCP-Server
arc42 Node MCP Server on NPM: https://www.npmjs.com/package/@h2nguyen/arc42-node-mcp-server/v/latest
MCP Specification: https://modelcontextprotocol.io/specification/

Built with ❤️ for the global software architecture community

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Arc42 Node MCP Server

Table of Content

📋 What is arc42?

arc42 Template Reference

Updating to the Latest arc42 Template

🚀 Quick Start

Installation

Setup in Claude Desktop

Setup in Cursor

Setup in Cline

Troubleshooting: NVM Users

Understanding Workspace Configuration

Option 1: Default Workspace Path (Server Startup Argument)

Option 2: Dynamic targetFolder Parameter (Per-Tool Override)

Recommendation

First Steps

🛠️ Available Tools

arc42-workflow-guide

arc42-init

arc42-status

generate-template

update-section

get-section

🌍 Multi-Language Support

Supported Languages

Using Languages

Language Configuration

📄 Multi-Format Support

Supported Formats

Using Formats

Format Configuration

📚 The 12 arc42 Sections

📖 Usage Examples

Example 1: Starting Fresh

Example 2: Document Specific Section

Example 3: Add Architecture Decision

🏗️ Project Structure

🎯 Best Practices

For AI Assistants

For Users

🧠 Claude Skill for Arc42

What Is the Arc42 Skill?

Installing the Skill in Other Projects

Skill Triggers

Benefits for Your Projects

🔧 Development

Development Methodology

Documentation Quality Assurance

Building from Source

Running in Development Mode

🧪 Testing

Running Tests

Test Structure

Coverage Thresholds

Test Categories

CI/CD Pipeline

🐳 Docker Support

Building the Docker Image

Running with Docker

Using Docker Compose

Testing with MCP Inspector standalone (Recommended)

Docker Compose Services

Testing Workflow

🤝 Contributing

📄 License

🙏 Acknowledgments

📞 Support

🔗 Links

⭐ Star History