🏛️ mcp-architect

Stop pasting your file tree into Claude. Give any AI assistant real architectural understanding of a codebase — local, private, zero‑config.

AI coding assistants are great at files but blind to architecture. Every session you re‑explain the structure, paste the file tree, and hope it guesses your module boundaries right. mcp-architect is an MCP server that hands your assistant a structured map of any codebase — tech stack, dependency graph, hotspots, and module summaries — computed 100% locally with no API keys and no model required.

It works with Claude Desktop, Cursor, Windsurf, Cline, or any MCP client.

---

Why

Without mcp-architect	With mcp-architect
"Here's my file tree, please figure out the structure…"	architecture_overview → stack, entry points, structure in one call
AI guesses how modules relate	dependency_graph → real import graph + circular‑dependency detection
"Which files matter?"	hotspots → largest, most complex, most‑changed, highest‑risk
Re‑explaining a package every time	explain → classes, functions, and deps of any folder

Everything runs on your machine. Your code never leaves it.

---

Quickstart

1. Add it to your MCP client

Claude Desktop — edit claude_desktop_config.json:

{
  "mcpServers": {
    "architect": {
      "command": "uvx",
      "args": ["mcp-architect"]
    }
  }
}

No PyPI yet? Run straight from source:

{ "mcpServers": { "architect": {
    "command": "uvx",
    "args": ["--from", "git+https://github.com/kannajune/mcp-architect", "mcp-architect"]
} } }

Restart your client. That's it — no keys, no model download.

2. Ask your assistant

"Use the architect tools to give me an overview of ~/code/my-app, then show me its dependency graph and the highest‑risk files."

---

What you get

# Architecture Overview — my-app

**151 files · 17,368 lines of code**

## Languages
- **Python** — 93 files, 13,683 LOC
- **TypeScript** — 23 files, 3,120 LOC

## Frameworks / key libraries
- FastAPI
- React
- Tailwind CSS

## Entry points
- main.py

# Dependency Graph — my-app

**118 modules · 172 internal import edges**

## Most depended-upon (architectural hubs)
- `app.signals.signal_parser` — imported by 12 modules
- `app.core.integrations_registry` — imported by 11 modules

## Circular dependencies
✅ no circular dependencies found

Tools

Tool	What it tells the AI
architecture_overview	Languages, frameworks, ecosystems, size, top‑level structure, entry points
dependency_graph	Internal import graph, architectural hubs, circular dependencies
hotspots	Largest / most complex / most‑changed (git) / highest‑risk files
explain	Deep‑dive a folder or file: classes, functions, external deps

---

Design principles

• Zero heavy dependencies. Pure Python standard library for all analysis (ast, os, re). The only runtime dep is the MCP SDK itself. Installs in seconds.
• Local & private. No network calls, no telemetry, no LLM. Your source never leaves your machine.
• Language‑aware. Full AST parsing for Python; import parsing for JavaScript/TypeScript; file/LOC stats for 25+ languages.
• Decoupled core. The analysis layer (mcp_architect.analysis) is importable and testable on its own — use it as a plain Python library too.

from mcp_architect.analysis import get_overview, get_dependency_graph
print(get_overview("~/code/my-app")["frameworks"])

The dependency and complexity analysis is heuristic — designed to give an AI useful, fast situational awareness, not to replace a full static analyzer.

---

Pin to one project (optional)

Set MCP_ARCHITECT_ROOT so tools default to a fixed repo and you can omit paths:

{ "mcpServers": { "architect": {
    "command": "uvx", "args": ["mcp-architect"],
    "env": { "MCP_ARCHITECT_ROOT": "/Users/you/code/my-app" }
} } }

---

Roadmap

• [ ] Mermaid dependency‑diagram output
• [ ] Layered‑architecture / boundary‑violation detection
• [ ] Go, Rust & Java import graphs
• [ ] Optional local‑LLM (Ollama) narrative summaries
• [ ] compare tool for before/after architecture diffs

Contributions welcome — see CONTRIBUTING.

Contributing

PRs and issues welcome! Run the tests with:

pip install -e ".[dev]"
pytest

License

MIT © Kannan Dharmalingam