acad-mcp

library0.2.1jsnpmunverified

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.

llm-agents workflow devops

npm install acad-mcp

github ↗package ↗

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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

Debug

Known issues

breakingRequires Node.js >=18. Older versions will fail to run.

fix

Upgrade Node.js to v18 or newer.

affects: >=0.0.0

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

affects: >=0.0.0

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

affects: >=0.0.0

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

affects: >=0.0.0

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

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module '...'

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: connect ECONNREFUSED ...

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: read_acad_docs: no documents found in docs/

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: validate_diagram: unsupported diagram type

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

fix

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

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

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"]}}}

Upgrade

Version history

0.2.1latest on PyPI

Audit

Dependencies

No dependency data recorded yet.

Agent activity

75 hits · last 30 days

node

ahrefsbot

amazonbot

Resources

githubhttps://github.com/cskeum88/acad-mcp ↗

packagehttps://www.npmjs.com/package/acad-mcp ↗