Architecture MCP

🚀 架構藍圖

這是一個由人工智能驅動的系統，它能夠分析 GitHub 倉庫，學習其架構，並通過 MCP 藉助 AI 編碼代理來執行該架構。

🚀 快速開始

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

就這麼簡單，只需一個命令。./run 會處理所有事情：

1. 若缺失，會安裝 Docker、Python 和 Node.js。
2. 通過 Docker 啟動 PostgreSQL（包含 pgvector）和 Redis。
3. 使用合理的默認值創建 backend/.env.local 和 frontend/.env.local。
4. 提示輸入你的 Anthropic API 密鑰（也可跳過，應用會啟動，但會給出警告）。
5. 創建 Python 虛擬環境並安裝後端依賴項。
6. 安裝前端依賴項。
7. 運行數據庫遷移並填充提示信息。
8. 啟動後端（http://localhost:8000）、前端（http://localhost:4000）和 ARQ 工作進程。

在後續運行時，./run 會自動檢測更改（如新依賴項、過時提示、架構更改），並在啟動前進行處理，你無需手動重新安裝或重新填充。

唯一需要的東西

一個 Anthropic API 密鑰。腳本會在首次運行時提示你輸入，你也可以跳過，稍後添加到 backend/.env.local 中。

恢復操作

./run --reset    # 強制進行完整的重新設置（重新創建環境文件、重新安裝依賴項、重新填充數據庫）

當出現問題或拉取了有重大變更的代碼後，使用 --reset 選項。

數據庫選項

舊腳本

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. 分析你的倉庫

1. 打開 http://localhost:4000。
2. 使用你的 GitHub 令牌進行身份驗證。
3. 輸入你的倉庫 URL 並開始分析。
4. 等待分階段分析完成（通常需要 1 - 3 分鐘）。
5. 查看生成的藍圖、按文件夾的 CLAUDE.md 文件和分析數據。

2. 將輸出同步到你的倉庫

這是關鍵步驟，只有將輸出放入你的倉庫，分析才能對 AI 代理有幫助。

1. 從藍圖視圖中，打開交付面板。
2. 選擇要推送的輸出（CLAUDE.md、按文件夾的上下文、AGENTS.md、Cursor 規則、MCP 配置、CODEBASE_MAP.md、Claude 鉤子）。
3. 選擇策略：PR（創建一個分支和拉取請求）或提交（直接提交到默認分支）。
4. 交付管道會進行非破壞性合併，保留你現有的內容。

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 服務器提供以下工具：

自動驗證（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。如果任何檢查失敗，代理會在繼續之前修復違規問題。

📄 許可證

原文檔未提及許可證相關信息，故跳過此章節。