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 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

📋 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:

1. 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.

2. 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)

3. 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

1. Start with the guide: Ask your AI assistant to run arc42-workflow-guide
2. Initialize documentation: Use arc42-init with your project name
3. Check status: Run arc42-status to see your progress
4. Generate templates: Use generate-template for specific sections
5. 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

1. Introduction and Goals - Requirements, quality goals, stakeholders
2. Architecture Constraints - Technical and organizational constraints
3. Context and Scope - Business and technical context
4. Solution Strategy - Fundamental decisions and strategies
5. Building Block View - Static decomposition of the system
6. Runtime View - Dynamic behavior and scenarios
7. Deployment View - Infrastructure and deployment
8. Cross-cutting Concepts - Overall regulations and approaches
9. Architecture Decisions - Important decisions (ADRs)
10. Quality Requirements - Quality tree and scenarios
11. Risks and Technical Debt - Known problems and risks
12. 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

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

For Users

1. Start with Section 1: Always begin with Introduction and Goals
2. Be iterative: You don't need to complete all sections immediately
3. Focus on decisions: Document WHY, not just WHAT
4. Keep it current: Update as architecture evolves
5. 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.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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

⭐ Star History