mcp-architect

Purpose

AI coding assistants are good at handling individual files, but they lack awareness of the overall architecture of a codebase. mcp-architect solves this problem: it provides any AI assistant with a structured map of the codebase through MCP (Model Context Protocol), so that the assistant can understand module boundaries without having to re-explain the project structure or paste a file tree in every session. What it computes includes a tech stack overview, an internal dependency graph (including cycle detection), risk hotspots, and module summaries.

Main Capabilities

• Tech stack overview: identifies the languages and tech stack used in the project.
• Dependency graph: builds a graph of internal dependencies within the codebase and detects circular dependencies.
• Risk hotspots: flags higher-risk files.
• Module summaries: generates module-level summaries.
• Language support: full AST parsing for Python; import relationship parsing for JavaScript/TypeScript; file and line-of-code statistics for more than 25 languages.

How to Use

1. Add mcp-architect to an MCP client. For Claude Desktop, for example, edit claude_desktop_config.json to configure it. You can also install it with pip install mcp-architect, or run the latest version directly from source.
2. Restart the client. No key is needed, and no model download is required.
3. Ask the assistant a question, for example: "Use the architect tools to give me an overview of ~/code/my-app, then show me its dependency graph and the highest-risk files."
4. Optional: set the MCP_ARCHITECT_ROOT environment variable to pin the tools to a project root, after which the path can be omitted in calls.

Using uvx to let the MCP client pull it on demand is also supported.

Use Cases

• Use with Claude Desktop, Cursor, Windsurf, Cline, or any MCP client.
• When you need to let AI quickly understand the structure of a codebase without sending code off your machine.
• Import and use the analysis layer mcp_architect.analysis as an ordinary Python library.

Design Principles

• Zero heavy dependencies: all analysis uses the Python standard library (ast, os, re); the only runtime dependency is the MCP SDK, and installation takes only seconds.
• Local and private: no network calls, no telemetry, no LLM; source code never leaves the machine.
• Language-aware: full AST parsing for Python, import parsing for JavaScript/TypeScript, and file and line-of-code statistics for more than 25 languages.
• Decoupled core: the analysis layer can be imported and tested independently, and can also be used as an ordinary Python library.

Limitations

• Dependency and complexity analysis are heuristic methods, intended to provide AI with fast, useful situational awareness, and are not a replacement for a full static analyzer.
• The code examples and specific configuration content mentioned in the material are not fully provided.

Relationship with Other Tools

mcp-architect is not a semantic search engine, nor a context packer, but a structural perspective that any AI assistant can call on demand. It complements tools such as Cursor and Serena: Cursor and Serena help AI read code, while mcp-architect helps AI understand architecture, and the two can be used together.

Other Information

• The roadmap mentions: layered architecture/boundary violation detection, Go/Rust/Java import graphs, optional local LLM (Ollama) narrative summaries, and a compare tool for before-and-after architecture comparison.
• The way tests are run is mentioned in the material but no specific command is given.
• License: MIT © Kannan Dharmalingam.
• Contributions are welcome; see CONTRIBUTING.