Architecture MCP

AI驱动的GitHub仓库架构分析与智能编码代理系统，通过深度分析代码库结构、生成架构蓝图和实时MCP工具，确保AI编码代理遵循统一的架构规范，提升代码质量和一致性。

开发者工具人工智能聊天机器人 #架构分析 #AI代理 #代码规范 #MCP工具 .Python

评分 : 2分

下载量 : 0

更新时间 : 2026-03-12

打开站点

什么是Architecture Blueprints MCP Server?

Architecture Blueprints是一个AI驱动的架构分析与执行系统，专门解决AI编程助手在编写代码时缺乏架构感知的问题。传统AI助手每次会话只能浏览少量文件并猜测架构，导致代码风格不一致。本系统通过深度分析整个代码库，生成架构蓝图，并通过MCP协议实时指导AI助手，确保所有代码都符合项目的架构规范。

如何使用Architecture Blueprints MCP Server?

使用分为三个主要步骤：1) 分析您的GitHub仓库，系统会进行7-9个AI分析阶段，深度理解您的架构；2) 将生成的架构文档同步回您的仓库，包括CLAUDE.md文件、MCP配置等；3) 在您的IDE中配置MCP服务器连接，AI助手即可获得实时架构指导。

适用场景

适用于任何使用AI编程助手的软件开发项目，特别是：团队协作项目需要保持代码一致性；大型项目需要维护清晰的架构分层；新成员或AI助手需要快速理解复杂代码库；需要确保50个AI生成的PR都遵循相同架构模式的项目。

主要功能

深度架构分析

通过7-9个AI分析阶段全面扫描代码库，识别架构层、命名约定、通信模式、实现模式等，提供分钟级的结构化分析而非秒级的粗略浏览。

文件夹级上下文

为每个重要文件夹生成专属的CLAUDE.md文件，包含架构指导、编码模式、关键文件指南和常见任务，AI助手进入任何文件夹都能立即了解规则。

实时架构执行

通过MCP工具在AI助手行动前进行验证，where_to_put、check_naming、how_to_implement等工具返回具体答案而非建议，确保代码符合架构。

单一事实来源

CLAUDE.md、Cursor规则、AGENTS.md和MCP工具都源自同一架构蓝图，切换工具或新成员加入时都遵循相同规则。

增量重新分析

当部分文件夹变更时，增量模式会重用未变更文件夹的缓存AI分析结果，大幅减少重新分析时间。

架构模式复用

分析架构良好的项目后，可将其蓝图作为新项目的参考架构，让每个AI助手都遵循经过验证的模式而非重新发明。

自动验证

Claude Code集成自动钩子，会话开始时检查CLAUDE.md文件是否过时，每次响应后验证更改文件是否符合架构规则。

优势

解决AI助手的架构盲点问题，确保代码一致性

深度分析提供比人工浏览更全面的架构理解

实时验证防止架构违规代码进入代码库

减少向AI助手重复解释架构的时间成本

支持架构模式复用，加速新项目开发

与主流AI助手（Claude Code、Cursor等）无缝集成

增量分析优化性能，减少重复工作

局限性

需要Anthropic API密钥，可能产生API调用费用

初始分析时间较长（1-3分钟），不适合极小型项目

对私有仓库需要GitHub访问令牌

架构分析质量依赖于AI模型的理解能力

需要将输出文档同步回仓库才能生效

MCP服务器配置需要基本的IDE配置知识

如何使用

环境准备与启动

克隆仓库并运行启动脚本，系统会自动安装依赖、启动数据库和服务。

获取API密钥

准备Anthropic API密钥（分析阶段需要）和GitHub个人访问令牌（访问仓库需要）。

分析您的仓库

访问本地前端界面（http://localhost:4000），输入仓库URL并开始分析。

同步输出到仓库

分析完成后，通过交付面板将CLAUDE.md等文档推送到您的仓库。

配置IDE连接

在IDE中配置MCP服务器连接，使AI助手能够访问架构指导工具。

使用案例

添加新的API端点

AI助手需要添加用户个人资料相关的API端点，但不确定应该放在哪个目录、使用什么命名约定。

验证服务类命名

开发者提议创建一个名为UserDataProcessor的服务类，需要验证是否符合项目命名约定。

查找认证实现方式

新开发者需要了解项目如何实现JWT认证，以便添加新的受保护端点。

理解项目架构层

新加入的AI助手需要快速理解项目的架构分层和组织结构。

常见问题

Architecture Blueprints与普通代码分析工具有什么不同？

是否需要为每个仓库重复分析？

MCP服务器支持哪些IDE和AI助手？

分析过程会修改我的源代码吗？

如果我的架构发生变化怎么办？

需要多少Anthropic API调用？费用如何？

可以分析私有仓库吗？

Claude Code的自动钩子如何工作？

🚀 架构蓝图

这是一个由人工智能驱动的系统，它能够分析 GitHub 仓库，学习其架构，并通过 MCP 借助 AI 编码代理来执行该架构。

🚀 快速开始

git clone https://github.com/your-org/architecture-blueprints.git
cd architecture-blueprints
./run

就这么简单，只需一个命令。./run 会处理所有事情：

若缺失，会安装 Docker、Python 和 Node.js。
通过 Docker 启动 PostgreSQL（包含 pgvector）和 Redis。
使用合理的默认值创建 backend/.env.local 和 frontend/.env.local。
提示输入你的 Anthropic API 密钥（也可跳过，应用会启动，但会给出警告）。
创建 Python 虚拟环境并安装后端依赖项。
安装前端依赖项。
运行数据库迁移并填充提示信息。
启动后端（http://localhost:8000）、前端（http://localhost:4000）和 ARQ 工作进程。

在后续运行时，./run 会自动检测更改（如新依赖项、过时提示、架构更改），并在启动前进行处理，你无需手动重新安装或重新填充。

唯一需要的东西

一个 Anthropic API 密钥。脚本会在首次运行时提示你输入，你也可以跳过，稍后添加到 backend/.env.local 中。

恢复操作

./run --reset    # 强制进行完整的重新设置（重新创建环境文件、重新安装依赖项、重新填充数据库）

当出现问题或拉取了有重大变更的代码后，使用 --reset 选项。

数据库选项

选项	使用场景	操作结果
postgres（默认）	本地开发，无需云依赖	Docker 在本地运行 PostgreSQL（包含 pgvector）和 Redis，迁移会自动运行。
supabase	云托管数据库	在 `backend/.env.local` 中设置 `DB_BACKEND=supabase` 并提供你的 Supabase 凭证，然后在 Supabase SQL 编辑器中运行 `backend/migrations/001_initial_setup.sql`。

旧脚本

setup.sh 和 start-dev.sh 仍然存在，但只是重定向到 ./run，请直接使用 ./run。

✨ 主要特性

深入分析

Claude Code 读取你的代码，而架构蓝图理解你的架构：AI 代理编写的代码虽然能工作，但在架构上缺乏理解，每次会话它们只会浏览几个文件并进行猜测。经过 50 次 AI 辅助的 PR 后，对于代码的位置和使用的模式会有 50 种不同的解释。而架构蓝图解决了这个问题，它通过 7 - 9 个 AI 阶段扫描整个代码库，包括层、命名、通信模式和实现模式，进行数分钟的结构化分析，而不是几秒钟的浏览。

按文件夹提供上下文

每个重要的文件夹都有自己的 CLAUDE.md 文件，其中包含架构指南、编码模式、关键文件指南和常见任务。AI 代理进入任何文件夹都能立即了解规则。

实时执行

MCP 工具会在代理行动之前被调用。where_to_put、check_naming、how_to_implement 会返回具体的答案，而不是建议。

单一事实来源

CLAUDE.md、Cursor 规则、AGENTS.md 和 MCP 工具都源自同一个蓝图。切换工具或新成员加入时，遵循相同的规则。

增量式重新分析

如果只更改了几个文件夹，增量模式会重用未更改文件夹的缓存 AI 增强信息，显著减少重新分析的时间。

复用有效方案

分析了一个架构良好的项目后，可以将其蓝图作为新项目的参考架构应用。你最好的代码库将成为一个可复用的模板，每个 AI 代理都会遵循经过验证的模式，而不是重新发明轮子。

📦 安装指南

安装步骤包含在快速开始的 ./run 命令中，它会处理所有依赖项的安装和环境的配置。

💻 使用示例

首次使用：分析并同步

在 ./run 启动应用后，你需要做两件事：分析你的仓库并将输出同步回仓库。每个仓库只需进行一次这样的设置，之后你的 AI 代理就能全面了解架构。

1. 分析你的仓库

打开 http://localhost:4000。
使用你的 GitHub 令牌进行身份验证。
输入你的仓库 URL 并开始分析。
等待分阶段分析完成（通常需要 1 - 3 分钟）。
查看生成的蓝图、按文件夹的 CLAUDE.md 文件和分析数据。

2. 将输出同步到你的仓库

这是关键步骤，只有将输出放入你的仓库，分析才能对 AI 代理有帮助。

从蓝图视图中，打开交付面板。
选择要推送的输出（CLAUDE.md、按文件夹的上下文、AGENTS.md、Cursor 规则、MCP 配置、CODEBASE_MAP.md、Claude 钩子）。
选择策略：PR（创建一个分支和拉取请求）或提交（直接提交到默认分支）。
交付管道会进行非破坏性合并，保留你现有的内容。

3. 从你的编码代理使用

就这么简单，没有第三步。一旦输出放入你的仓库，你的编码代理会自动获取它们：

Claude Code - 原生支持，每次会话会自动读取 CLAUDE.md 和 .claude/rules/，无需配置。
其他代理（Cursor、Windsurf 等） - 通过 MCP 连接，将服务器添加到你的 IDE 配置中，代理就能使用 where_to_put、check_naming、how_to_implement 并访问完整的蓝图。

更改后重新分析

当重新分析已经有蓝图的仓库时，UI 提供两个选项：

增量式（更快） - 重用未更改文件夹的缓存 AI 增强信息。
完整分析 - 从头开始重新运行整个流程。

重新分析后，再次同步以推送更新后的输出。

将 MCP 服务器连接到你的 IDE

将 MCP 服务器添加到你的 IDE 配置（.mcp.json 或 .cursor/mcp.json）中：

{
  "mcpServers": {
    "architecture-blueprints": {
      "url": "http://localhost:8000/mcp/sse"
    }
  }
}

MCP 服务器提供以下工具：

工具	用途
`where_to_put`	获取组件类型的正确目录和命名模式
`check_naming`	根据项目命名约定验证提议的名称
`how_to_implement`	模糊搜索功能的现有实现方式（库、模式、关键文件）
`list_implementations`	列出所有记录的实现功能及其 ID 和摘要
`how_to_implement_by_id`	根据 ID 获取特定功能的完整实现细节
`get_repository_blueprint`	获取完整的架构蓝图 JSON
`list_repository_sections`	列出蓝图中可寻址的部分 ID
`get_repository_section`	根据 slug 获取特定的蓝图部分（节省令牌）
`list_source_files`	列出分析期间收集的所有源文件及其大小
`get_file_content`	读取特定源文件的内容

自动验证（Claude Code）

当你在交付输出中包含 claude_hooks 时，Claude Code 会获得两个自动运行的钩子：

会话开始时：检查本地的 CLAUDE.md 文件是否与蓝图相比过时，并给出警告。
每次响应后：收集更改的文件，通过 AI 根据架构规则进行验证，并立即重新生成过时的 CLAUDE.md 文件。

这样可以确保在编码时架构文档保持最新。蓝图本身不会由钩子重新生成，只有 CLAUDE.md 文件会根据现有蓝图重新渲染。如果你的架构发生根本性变化，请从 UI 重新进行分析。

运行测试

cd backend
PYTHONPATH=src python -m pytest tests/unit/ -v

📚 详细文档

有关详细的技术文档、架构内部原理和 API 参考，请参阅 docs/ARCHITECTURE.md。

🔧 技术细节

工作原理

  GitHub Repo
       |
       v
  1. Clone & Extract    -- 文件树、依赖项、配置、代码示例
       |
       v
  2. RAG Index           -- 对代码进行分块，使用 sentence-transformers 进行嵌入，存储在 pgvector 中
       |                     文件级检索返回完整文件（而非片段）
       |                     特定阶段的分块类型偏好提高相关性
       v
  3. Phased AI Analysis  -- 7 - 9 次 Claude API 调用，每次基于前一次的结果
       |                     （观察 -> 智能文件读取 -> 发现 -> 层 -> 模式 -> 通信 -> 技术 -> [前端] -> 实现分析 -> 综合）
       |                     文件注册表注入每个阶段的提示中
       |                     基于仓库大小的动态文件读取预算
       v
  4. StructuredBlueprint -- 单一 JSON 事实来源（Pydantic 模型）
       |
       v
  5. Intent Layer        -- 按文件夹生成 CLAUDE.md
       |                     确定性蓝图映射到文件夹层次结构
       |                     可选的 AI 增强（模式、关键文件指南、常见任务、反模式、代码示例）
       |                     CODEBASE_MAP.md 用于跨领域导航
       |                     增量模式跳过未更改的文件夹
       |
       |---> CLAUDE.md (root)    -- 项目根目录的 AI 代理说明
       |---> src/api/CLAUDE.md   -- 按文件夹的上下文（每个重要文件夹）
       |---> CODEBASE_MAP.md     -- 扁平架构概述，便于快速参考
       |---> .claude/rules/      -- Claude Code 规则文件
       |---> .cursor/rules/      -- Cursor IDE 集成
       |---> AGENTS.md           -- 多代理系统指南
       |---> MCP Server          -- 实时的 where_to_put、check_naming
       \---> Delivery to GitHub  -- 通过 PR 或直接提交（非破坏性合并）推送输出

你的 IDE 中的 AI 代理会连接到 MCP 服务器。在创建文件之前，它会调用 where_to_put；在命名类之前，它会调用 check_naming。如果任何检查失败，代理会在继续之前修复违规问题。