{"id":24881,"library":"acad-mcp","title":"acad-mcp","description":"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.","status":"active","version":"0.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/cskeum88/acad-mcp","tags":["javascript","mcp","acad","architecture","diagram","plantuml","mermaid"],"install":[{"cmd":"npm install acad-mcp","lang":"bash","label":"npm"},{"cmd":"yarn add acad-mcp","lang":"bash","label":"yarn"},{"cmd":"pnpm add acad-mcp","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is a CLI tool, not a library. Use npx or add as an MCP server in your AI agent's config.","symbol":"default (server)","correct":"No code import; run via CLI: npx acad-mcp"}],"quickstart":{"code":"# Run the MCP server directly (no install needed)\nnpx acad-mcp\n\n# For Claude Code:\nclaude mcp add acad-mcp -- npx -y acad-mcp\n\n# Or create .mcp.json in project root:\n# {\n#   \"mcpServers\": {\n#     \"acad-mcp\": {\n#       \"command\": \"npx\",\n#       \"args\": [\"-y\", \"acad-mcp\"]\n#     }\n#   }\n# }\n\n# Then use tools in your AI agent:\n# - validate_diagram: validate Mermaid/PlantUML syntax\n# - read_acad_docs: read ACAD design documents from docs/\n# - create_agent_instructions: generate handoff files (CLAUDE.md, etc.)\n# - run_checks: run test/lint/typecheck","lang":"javascript","description":"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)."},"warnings":[{"fix":"Upgrade Node.js to v18 or newer.","message":"Requires Node.js >=18. Older versions will fail to run.","severity":"breaking","affected_versions":">=0.0.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Review diagram semantics separately; validation only catches parse errors.","message":"Diagram validation (validate_diagram) checks only syntax, not semantics. A valid diagram may still be logically incorrect.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Add 'lint' and 'typecheck' scripts to package.json if you want those checks.","message":"The run_checks tool defaults to running 'test' script. For lint/typecheck, the project's package.json must define corresponding scripts (lint, typecheck).","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Refer to docs/agent-setup-guide.md for per-agent configuration details.","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run 'npx clear-npx-cache' then retry 'npx acad-mcp'.","cause":"Running npx acad-mcp in a directory without network access or with a stale npm cache.","error":"Error: Cannot find module '...'"},{"fix":"Ensure your MCP client is configured to use 'type': 'stdio' with command 'npx' and args ['-y','acad-mcp'].","cause":"Trying to connect as an HTTP server instead of stdio. acad-mcp uses stdio transport only.","error":"Error: connect ECONNREFUSED ..."},{"fix":"Create a docs/ folder with the five standard files: arch-story.md, architecture-drivers.md, architecture.md, validation-report.md, implementation-plan.md.","cause":"The docs/ directory is missing or does not contain the expected ACAD artifact files.","error":"Error: read_acad_docs: no documents found in docs/"},{"fix":"Use only 'mermaid' or 'plantuml' as the diagram type parameter.","cause":"Passed a diagram type other than 'mermaid' or 'plantuml'.","error":"Error: validate_diagram: unsupported diagram type"},{"fix":"Ensure the top-level key is 'mcpServers' (not 'mcp_servers' or 'servers'). Example: {\"mcpServers\":{\"acad-mcp\":{\"command\":\"npx\",\"args\":[\"-y\",\"acad-mcp\"]}}}","cause":"Incorrect JSON structure when configuring Claude Desktop or other agent.","error":"TypeError: Cannot read properties of undefined (reading 'mcpServers')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}