acad-mcp

0.2.1 verified Fri May 01 auth: no javascript

ACAD-MCP is an MCP (Model Context Protocol) server implementing the Architecture-Centric AI-native Development (ACAD) methodology. Version 0.2.1, requires Node.js >=18. Key differentiators: provides diagram validation for Mermaid/PlantUML, a documentation bridge to auto-read ACAD design artifacts (5 documents), test/lint/typecheck runners, and agent handoff file generation (CLAUDE.md, AGENTS.md, GEMINI.md). Built with TypeScript, bundled via esbuild, follows Hexagonal architecture. Supports Claude, Codex CLI, Gemini CLI, and VS Code GitHub Copilot Agent Mode via standard MCP configuration. No external dependencies beyond Node.js; runs as a stdio MCP server via npx.

Common errors

error Error: Cannot find module '...' ↓

cause Running npx acad-mcp in a directory without network access or with a stale npm cache.

fix

Run 'npx clear-npx-cache' then retry 'npx acad-mcp'.

error Error: connect ECONNREFUSED ... ↓

cause Trying to connect as an HTTP server instead of stdio. acad-mcp uses stdio transport only.

fix

Ensure your MCP client is configured to use 'type': 'stdio' with command 'npx' and args ['-y','acad-mcp'].

error Error: read_acad_docs: no documents found in docs/ ↓

cause The docs/ directory is missing or does not contain the expected ACAD artifact files.

fix

Create a docs/ folder with the five standard files: arch-story.md, architecture-drivers.md, architecture.md, validation-report.md, implementation-plan.md.

error Error: validate_diagram: unsupported diagram type ↓

cause Passed a diagram type other than 'mermaid' or 'plantuml'.

fix

Use only 'mermaid' or 'plantuml' as the diagram type parameter.

error TypeError: Cannot read properties of undefined (reading 'mcpServers') ↓

cause Incorrect JSON structure when configuring Claude Desktop or other agent.

fix

Ensure the top-level key is 'mcpServers' (not 'mcp_servers' or 'servers'). Example: {"mcpServers":{"acad-mcp":{"command":"npx","args":["-y","acad-mcp"]}}}

Warnings

breaking Requires Node.js >=18. Older versions will fail to run. ↓

fix Upgrade Node.js to v18 or newer.

gotcha The server expects ACAD design documents in a docs/ folder at the project root. If the folder is missing or empty, read_acad_docs will return no results. ↓

fix Ensure your project has a docs/ directory containing the five ACAD artifacts (arch-story.md, architecture-drivers.md, architecture.md, validation-report.md, implementation-plan.md).

gotcha Diagram validation (validate_diagram) checks only syntax, not semantics. A valid diagram may still be logically incorrect. ↓

fix Review diagram semantics separately; validation only catches parse errors.

gotcha The run_checks tool defaults to running 'test' script. For lint/typecheck, the project's package.json must define corresponding scripts (lint, typecheck). ↓

fix Add 'lint' and 'typecheck' scripts to package.json if you want those checks.

gotcha MCP server configuration paths differ per AI agent (Claude Desktop uses ~/Library/Application Support/Claude/claude_desktop_config.json, Codex CLI uses ~/.codex/config.toml, etc.). Incorrect path leads to connection failure. ↓

fix Refer to docs/agent-setup-guide.md for per-agent configuration details.

Install

npm install acad-mcp

yarn add acad-mcp

pnpm add acad-mcp

Imports

default (server)
```
No code import; run via CLI: npx acad-mcp
```
This is a CLI tool, not a library. Use npx or add as an MCP server in your AI agent's config.

Quickstart

Shows how to start the acad-mcp MCP server and configure it with various AI agents (Claude Code, Claude Desktop, Codex CLI, Gemini CLI, VS Code).

# Run the MCP server directly (no install needed)
npx acad-mcp

# For Claude Code:
claude mcp add acad-mcp -- npx -y acad-mcp

# Or create .mcp.json in project root:
# {
#   "mcpServers": {
#     "acad-mcp": {
#       "command": "npx",
#       "args": ["-y", "acad-mcp"]
#     }
#   }
# }

# Then use tools in your AI agent:
# - validate_diagram: validate Mermaid/PlantUML syntax
# - read_acad_docs: read ACAD design documents from docs/
# - create_agent_instructions: generate handoff files (CLAUDE.md, etc.)
# - run_checks: run test/lint/typecheck