kannajune/mcp-architect

# 🏛️ mcp-architect [](https://pypi.org/project/mcp-architect/) [](LICENSE) [](https://www.python.org/) [](https://modelcontextprotocol.io/)

AI 编程助手擅长处理*文件*，但对*架构*却视而不见。每次会话你都得重新解释项目结构，粘贴文件树，并指望它能猜对你的模块边界。**mcp-architect** 是一个 [MCP](https://modelcontextprotocol.io/) 服务器，它能将任何代码库的结构化图谱——技术栈、依赖图、热点和模块摘要——直接交给你的助手。这一切完全在**本地**计算，**无需任何 API 密钥，也不依赖任何模型**。 它可以与 **Claude Desktop、Cursor、Windsurf、Cline** 或任何 MCP 客户端配合使用。 ## 为什么使用它 | 没有 mcp-architect | 使用 mcp-architect | |---|---| | “这是我的文件树，请自己弄清楚结构……” | `architecture_overview` → 一次调用即可获取技术栈、入口点和结构 | | AI 靠猜来理解模块间的关系 | `dependency_graph` → 真实的导入图 + 循环依赖检测 | | “哪些文件最重要？” | `hotspots` → 最大、最复杂、变动最频繁、风险最高的文件 | | 每次都要重新解释一个 package | `explain` → 获取任意文件夹的类、函数和依赖项 | 一切都在你的机器上运行。你的代码绝对不会离开本地。 ## 快速开始 ### 安装 ``` pip install mcp-architect ``` ……或者干脆跳过安装步骤，让你的 MCP 客户端使用 `uvx` 按需自动拉取（如下所示）。 ### 1. 将其添加到你的 MCP 客户端 **Claude Desktop** — 编辑 `claude_desktop_config.json`： ``` { "mcpServers": { "architect": { "command": "uvx", "args": ["mcp-architect"] } } } ``` 重启你的客户端。**就这么简单** —— 不需要密钥，也不需要下载模型。 ### 2. 询问你的助手 ## 你能得到什么 ``` # 架构概览 — my-app **151 files · 17,368 lines of code** ## 语言 - **Python** — 93 files, 13,683 LOC - **TypeScript** — 23 files, 3,120 LOC ## Frameworks / key libraries - FastAPI - React - Tailwind CSS ## 入口点 - main.py ``` ``` # Dependency Graph — my-app **118 modules · 172 internal import edges** ## 被依赖最多（架构枢纽） - `app.signals.signal_parser` — imported by 12 modules - `app.core.integrations_registry` — imported by 11 modules ## 循环依赖 ✅ no circular dependencies found ``` ## 工具 | 工具 | 它能告诉 AI 什么 | |------|----------------------| | `architecture_overview` | 语言、框架、生态系统、代码规模、顶层结构和入口点 | | `dependency_graph` | 内部导入图、架构枢纽以及**循环依赖** | | `impact_analysis` | **如果你修改了 X 会影响什么** —— 直接导入者 + 传递性爆炸半径、枢纽风险 | | `hotspots` | 最大 / 最复杂 / 变动最频繁（基于 git）/ 风险最高的文件 | | `explain` | 深入解析某个文件夹或文件：类、函数、外部依赖 | ## 设计原则 - **零重型依赖。** 纯粹使用 Python 标准库（`ast`、`os`、`re`）进行所有分析。唯一的运行时依赖只有 MCP SDK 本身。几秒钟即可完成安装。 - **本地与隐私。** 没有网络调用，没有遥测，也不需要 LLM。你的源码永远不会离开你的机器。 - **具备语言感知能力。** 为 Python 提供完整的 AST 解析；为 JavaScript/TypeScript 提供导入解析；支持 25+ 种语言的文件/LOC 统计。 - **解耦的核心。** 分析层（`mcp_architect.analysis`）可独立导入和测试 —— 你也可以将其作为普通的 Python 库使用。 ``` from mcp_architect.analysis import get_overview, get_dependency_graph print(get_overview("~/code/my-app")["frameworks"]) ``` ## 绑定到特定项目（可选） 设置 `MCP_ARCHITECT_ROOT`，这样工具就会默认使用一个固定的 repo，你可以省略路径： ``` { "mcpServers": { "architect": { "command": "uvx", "args": ["mcp-architect"], "env": { "MCP_ARCHITECT_ROOT": "/Users/you/code/my-app" } } } } ``` ## 横向对比 mcp-architect 不是语义搜索引擎，也不是上下文打包器 —— 它是任何 AI 助手都可以按需调用的**结构化视角**。它的设计初衷是*补充*以下工具，而不是取代它们： | 工具 / 方法 | 擅长领域 | mcp-architect 补充的能力 | |---|---|---| | **Cursor codebase indexing** | Cursor 内部的语义代码片段检索 | 适用于**任何** MCP 客户端（Claude Desktop、Cline、Windsurf、Cursor 等），**100% 本地**运行（无需云端 embeddings），并且返回的是**架构信息** —— 依赖图、循环、热点 —— 而不仅仅是相关的代码片段 | | **Serena**（基于 LSP 的代码 Agent） | 精确的符号级导航与编辑 | **零配置、零重型依赖**（仅使用标准库 —— 无需安装语言服务器），并提供**高层次的架构图谱**，而不是逐个符号的操作 | | **RepoPrompt**（上下文打包） | 手动挑选文件组合成 prompt | 让助手通过工具按需**拉取**结构化的架构信息 —— 无需手动选择文件，也不必费心去调整 token 预算 | **一句话概括：** Cursor 和 Serena 帮助 AI *阅读*你的代码；而 mcp-architect 帮助它在本地、在任何客户端中*理解架构*。它们搭配使用效果极佳。 ## 路线图 - [ ] 分层架构 / 边界违规检测 - [ ] Go、Rust 和 Java 的导入图 - [ ] 可选的本地 LLM (Ollama) 叙述性摘要 - [ ] 用于前后架构对比差异的 `compare` 工具 ## 贡献 欢迎提交 PR 和 issue！运行测试请使用： ``` pip install -e ".[dev]" pytest ``` ## 许可证 [MIT](LICENSE) © Kannan Dharmalingam

标签：AI辅助编程, IPv6支持, MCP, SOC Prime, WebSocket, 上下文提供者, 代码分析, 依赖分析, 凭证管理, 开发工具, 自动化payload嵌入, 逆向工具