kannajune/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
Install
…or skip the install entirely and let your MCP client fetch it on demand with uvx (shown below).
1. Add it to your MCP client
**Claude Desktop** — edit claude_desktop_config.json:
> Prefer pip? pip install mcp-architect. Or run the latest straight from source:
>
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
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** |
| impact_analysis | **What breaks if you change X** — direct importers + transitive blast radius, hub risk |
| 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.
> The dependency and complexity analysis is **heuristic** — designed to give an AI useful, fast situational awareness, not to replace a full static analyzer.