用途
AI 编程助手擅长处理单个文件，却对代码库的整体架构缺乏感知。mcp-architect 解决的就是这个问题：它通过 MCP（Model Context Protocol）向任意 AI 助手提供代码库的结构化地图，让助手不必每次会话都重新解释项目结构或粘贴文件树，就能理解模块边界。它计算的内容包括技术栈概览、内部依赖图（含循环依赖检测）、风险热点以及模块摘要。
主要能力
- 技术栈概览：识别项目中使用的语言和技术栈。
- 依赖图：构建代码库内部的依赖关系图，并检测循环依赖。
- 风险热点：标出风险较高的文件。
- 模块摘要：生成模块级别的摘要。
- 语言支持：对 Python 进行完整 AST 解析；对 JavaScript/TypeScript 解析导入关系；为 25 种以上语言提供文件与代码行统计。
使用方式
- 将 mcp-architect 添加到 MCP 客户端。以 Claude Desktop 为例，编辑 claude_desktop_config.json 进行配置。也可使用 pip install mcp-architect 安装，或直接从源码运行最新版本。
- 重启客户端。无需密钥，无需下载模型。
- 向助手提问，例如：“Use the architect tools to give me an overview of ~/code/my-app, then show me its dependency graph and the highest-risk files.”
- 可选：设置 MCP_ARCHITECT_ROOT 环境变量，将工具固定到某个项目根目录，之后调用时即可省略路径。
也支持通过 uvx 让 MCP 客户端按需拉取。
适用场景
- 配合 Claude Desktop、Cursor、Windsurf、Cline 或任何 MCP 客户端使用。
- 需要在不把代码送出本机的前提下，让 AI 快速理解代码库结构。
- 将分析层 mcp_architect.analysis 作为普通 Python 库导入使用。
设计原则
- 零重型依赖：所有分析使用 Python 标准库（ast、os、re），唯一运行时依赖是 MCP SDK，安装只需数秒。
- 本地且私密：无网络调用、无遥测、无 LLM，源码永不离开本机。
- 语言感知：Python 完整 AST 解析，JavaScript/TypeScript 导入解析，25 种以上语言的文件与代码行统计。
- 解耦核心：分析层可独立导入和测试，也可作为普通 Python 库使用。
限制
- 依赖与复杂度分析属于启发式方法，旨在为 AI 提供快速、有用的情境认知，不能替代完整的静态分析器。
- 资料中提及的代码示例与具体配置内容未完整提供。
与其他工具的关系
mcp-architect 不是语义搜索引擎，也不是上下文打包器，而是任何 AI 助手可按需调用的结构视角。它与 Cursor、Serena 等工具互补：Cursor 和 Serena 帮助 AI 阅读代码，mcp-architect 帮助 AI 理解架构，二者可以叠加使用。
其他信息
- 路线图提及：分层架构/边界违规检测、Go/Rust/Java 导入图、可选的本地 LLM（Ollama）叙述性摘要、用于架构前后对比的 compare 工具。
- 测试运行方式在资料中提及但未给出具体命令。
- 许可证：MIT © Kannan Dharmalingam。
- 欢迎贡献，参见 CONTRIBUTING。
