Mnemosyne MCP

# Mnemosyne MCP - MVP Sprint 計劃 v2.0 **文件版本**: 2.0 (戰術性微調) **狀態**: 最終版 (Final) **更新日期**: 2025年7月15日 **架構師**: AI Assistant & Project Lead ## 總體策略：從「戰略性大改」到「戰術性微調」 原有的 Sprint 2 和 3 的目標是完全正確的，但我們根據 Sprint 1 的成果，對其核心任務的順序和粒度進行優化，使其更平滑、風險更低。 ### 為什麼這個順序更好？ 1. **風險隔離**: 將「向量搜索」和「圖遍歷」的實現拆分到兩個 Sprint，可以讓我們獨立地驗證和除錯每一部分，降低了 Sprint 2 的技術風險。 2. **價值更平滑**: Sprint 2 結束時，我們就有了一個可用的「智能搜索」功能。Sprint 3 結束時，這個功能會變得「更智能」。這比在一個 Sprint 裡交付一個大而全的功能，反饋迴圈更短，價值曲線更平滑。 3. **故事線更清晰**: 這個順序構成了一個完美的產品故事：「我們先讓機器能看懂你的程式碼（S1），然後讓它能聽懂你的話（S2），接著讓它能理解程式碼的脈絡（S3），最後我們教它遵守規則（S4）。」 ## 優化後的 Sprint 計劃概覽 | Sprint | 核心主題 | 關鍵交付物 | |--------|---------|-----------| | Sprint 0 | 基礎設施 | 可運行的空殼服務 | | Sprint 1 | 數據管線與視覺化 | 程式碼 → 可視化圖譜 | | Sprint 2 | AI 核心：語義理解 | 純向量搜索 API (Search v1) | | Sprint 3 | 智能核心：上下文融合 | 混合檢索 API (Search v2) + 影響力分析 API | | Sprint 4 | 治理核心：安全護欄 | 約束與鎖定 API + CI/CD 檢查 CLI | --- ## Sprint 0: 基礎設施搭建 ✅ **[已完成]** ### 目標 建立一個可工作的、可擴展的基礎設施，為後續的功能開發提供堅實的基礎。 ### 核心任務 - ✅ **Docker Compose 環境**: 實現 MCP 服務 + FalkorDB 的一鍵啟動 - ✅ **gRPC-First 架構**: 完成 gRPC 服務骨架和 REST Gateway - ✅ **抽象層設計**: 完成 `GraphStoreClient` 抽象介面 - ✅ **FalkorDB 驅動**: 實現基本的圖資料庫操作 - ✅ **健康檢查**: 提供 `/health` 端點確保服務狀態可監控 - ✅ **CLI 工具**: 基礎的 `mnemo` 命令行工具 - ✅ **開發工具鏈**: 完整的 lint, test, format 工具鏈 ### 關鍵創新點 - **Seed 腳本**: 讓新用戶能立即在 Browser 中看到東西，極大提升了第一印象 - **Cypher Trace log**: 這是為未來的可觀測性埋下的重要伏筆 ### 交付成果 一個可運行的、架構清晰的 MCP 服務，具備了進行功能開發的所有基礎設施。 --- ## Sprint 1: ECL 管線與知識圖譜 ✅ **[已完成]** ### 目標 實現 ECL (Extract → Cognify → Load) 管線，將程式碼轉換為可視化的知識圖譜。 ### 核心任務 - ✅ **Extract 階段**: 實現 Git 和檔案系統的程式碼提取 - ✅ **Cognify 階段**: 實現 Python AST 解析器，提取函數和呼叫關係 - ✅ **Load 階段**: 將解析結果存入 FalkorDB 圖資料庫 - ✅ **RPC 整合**: 提供 `ProcessRepository` gRPC 接口 - ✅ **視覺化**: 確保生成的圖譜可在 FalkorDB Browser 中查看 ### 關鍵創新點 - **最小範例 repo**: 讓 ECL 管線的測試變得可重複、自動化 - **Pydantic V2 遷移**: 確保數據模型的類型安全和驗證 ### 交付成果 一個完整的 ECL 管線，能夠將 Python 專案轉換為可視化的知識圖譜。 --- ## Sprint 2: AI 核心：語義理解 🔄 **[優化版]** ### 目標 實現第一個「由 LLM 驅動的、有用的」功能：純向量搜索 API。 ### 核心任務 (重新排序) #### 2.1 LLM 能力中心與 openai-starter 預設 - **任務**: 實現我們最終確定的 LLMProvider 插件架構和 OpenAIProvider - **技術實現**: 將 generation, embedding, reasoning 三個能力硬編碼綁定到： - `generation` → gpt-4.1-mini - `embedding` → text-embedding-3-small - `reasoning` → gpt-4.1-nano - **理由**: 這是所有 AI 功能的基礎設施，必須先行 #### 2.2 實現 Search API (第一階段：純向量搜索) - **任務**: 擴展 ECL 的 Load 階段，使其能夠呼叫 embedding 能力（3-small）為 Function 或 File 的註釋生成向量，並存入 FalkorDB 的向量索引 - **API 實現**: 實現 Search API，使其能夠接收自然語言，並只返回 Top-K 個語義最相似的節點 - **理由**: 我們需要先驗證「文本到圖節點」的語義映射這條路是通的。暫時不要加入圖遍歷，以隔離變量 #### 2.3 手動驗證與 Demo - **驗證場景**: 開發者手動呼叫 Search API，輸入「如何處理用戶認證」，看看它是否能準確地返回與 validateCredentials 相關的函數或文件節點 - **Demo 價值**: 向外界展示「Mnemosyne MCP 能夠聽懂自然語言，並在您的程式碼庫中找到相關的概念」 ### 交付成果 (優化後) 一個具備核心語義理解能力的 MCP。它還不能進行複雜的推理，但已經能作為一個「智能程式碼搜索引擎」來使用。 --- ## Sprint 3: 智能核心：上下文融合 🔄 **[優化版]** ### 目標 將「語義」與「結構」融合，提供真正的圖譜洞察。 ### 核心任務 #### 3.1 實現 Search API (第二階段：混合檢索) - **任務**: 擴展 Search API 的邏輯。在得到向量搜索的 Top-K 個種子節點後，再執行 1-hop Traversal，將種子節點的一度鄰居也加入到上下文中，返回一個更豐富的子圖 - **範圍控制**: 將 Search API 的第一版範圍縮小到 1-hop Traversal，是規避性能風險、快速驗證核心邏輯的明智之舉 - **理由**: 這是我們產品相較於普通向量數據庫的核心差異化，必須盡快實現 #### 3.2 實現第一個「自省式」工具 (RunImpactAnalysis) - **任務**: 實現這個 API。它的邏輯相對獨立，可以在混合檢索的基礎上並行開發 - **價值**: 這將是我們第一個純圖譜推理的功能 #### 3.3 手動驗證與 Demo - **Demo 1 (Search)**: 再次查詢「如何處理用戶認證」，這次返回的結果不僅有相關的函數，還有呼叫它的 API 端點、它所在的類等結構化上下文 - **Demo 2 (Impact)**: 展示修改一個核心函數後，可以立即看到受影響的其他函數列表 ### 交付成果 (優化後) 一個真正智能的 MCP。它不僅能「找到」信息，更能「理解」信息之間的關聯。產品的核心價值在此完全體現。 --- ## Sprint 4: 治理核心：安全護欄 🔄 **[原 Sprint 3]** ### 目標 為智能引擎安裝「安全系統」，引入約束與 CI/CD 整合。 ### 核心任務 #### 4.1 約束模型實現 - **數據模型**: 實現 Constraint, Lock 等約束相關的 Pydantic 模型 - **圖譜整合**: 將約束模型整合到 FalkorDB Schema 中 #### 4.2 事務性鎖定 API - **API 實現**: 實現 AcquireLock, ReleaseLock RPC - **併發控制**: 確保多代理操作的原子性 #### 4.3 CI/CD 整合工具 - **CLI 命令**: 開發 `mnemo pr-check` CLI 命令，並在內部呼叫 RunImpactAnalysis 和新的 CheckConstraints 邏輯 - **ChangeSet Diff 工具**: 讓 pr-check 的結果不僅僅是通過/失敗，而是能提供可讀的「變更摘要」，價值巨大 - **GitHub Action**: 提供官方 GitHub Action 範例 ### 交付成果 一個可靠、可信、可被整合的 MCP，具備了進入更嚴肅生產場景的基礎。 --- ## 集成測試與驗收門檻 ### 更新後的路線圖：將集成測試作為每個階段的「驗收門」 | Sprint | 核心開發主題 | 集成與驗證目標 | |--------|-------------|---------------| | Sprint 0 & 1 | 基礎設施 + ECL 閉環 | 內部驗證: 開發者能在 Browser 中看到正確的圖譜 | | Sprint 2 | AI 核心：語義理解 | AI 代理集成: 驗證一個簡單的 RAG 腳本能通過 gRPC 呼叫 Search API 並提升回答質量 | | Sprint 3 | 智能核心：上下文融合 | 開發工具集成: 驗證 Search v2 和 ImpactAnalysis 的結果能有效地增強 Cursor 或 Copilot Chat 的上下文 | | Sprint 4 | 治理核心：安全護欄 | 協議與 CI/CD 集成: 驗證 stdio/SSE 模式工作正常，並完成一次 GitHub Action 的端到端攔截測試 | ### Sprint 2 之後：第一次「AI 代理」集成驗證 **時機**: 在我們完成了 Sprint 2，交付了核心的 Search API (v1, 純向量搜索) 之後。 **目標**: 驗證一個最簡單的 AI 代理（例如，一個基於 LangChain 或 LlamaIndex 的腳本）是否能成功地呼叫我們的 MCP API，並利用返回的上下文來提升其回答質量。 **測試內容**: #### gRPC 客戶端可用性測試 - 使用我們從 .proto 文件自動生成的 Python gRPC stub，編寫一個簡單的客戶端腳本 - 驗證這個腳本能否成功連接到本地運行的 MCP 服務，並呼叫 Search RPC #### 基本 RAG 流程驗證 - 創建一個簡單的 RAG Chain。其 Retriever 部分不再是直接讀取本地文件，而是呼叫我們的 Search API - 向這個 RAG Chain 提出一個關於範例程式碼庫的問題（例如，「哪個函數負責處理數據庫連接？」） - **驗收標準**: 觀察 LLM 的最終回答，是否明確地利用了 Search API 返回的、比普通文件搜索更精準的上下文（例如，它直接引用了 db_connector.py 中的 connect_to_database 函數） **階段價值**: 第一次驗證了我們的核心價值主張——即 MCP 提供的上下文確實能「改變 AI 代理的行為」。 ### Sprint 3 之後：與「真實世界」開發工具的初步集成 **時機**: 在我們完成了 Sprint 3，交付了混合檢索 (Search v2) 和影響力分析 (RunImpactAnalysis) 這兩個強大功能之後。 **目標**: 驗證 MCP 是否能與開發者日常使用的工具（如 Cursor 這類 AI-First IDE）進行初步集成，並提供有意義的幫助。 **測試內容**: #### Cursor 自定義命令 (Custom Commands) - Cursor 允許用戶定義自定義的 @ 命令。我們可以創建一個 @mcp 命令 - 當用戶在 Cursor 中輸入 `@mcp 哪個函數修改了用戶密碼？` 時，這個自定義命令會觸發一個後台腳本，該腳本呼叫我們 MCP 的 Search API - **驗收標準**: MCP 的響應結果，能夠作為豐富的上下文，被插入到 Cursor 的聊天窗口中，幫助 AI 更準確地定位和回答問題 #### Augment Code / Copilot Chat 的上下文增強 - 許多現代 AI 編程助手都允許用戶手動粘貼上下文。我們可以進行一個手動測試： - **對比實驗 A**: 直接向 Copilot Chat 提問：「重構 UserService 的風險是什麼？」 - **對比實驗 B**: 先呼叫我們 MCP 的 RunImpactAnalysis API，獲取關於 UserService 的詳細影響力報告，然後將這份報告和我們的問題一起粘貼給 Copilot Chat - **驗收標準**: 明顯觀察到，在實驗 B 中，Copilot Chat 的回答更具體、更準確，並且引用了我們提供的影響力報告中的內容 **階段價值**: 驗證了 MCP 作為一個「人類開發者輔助工具」的潛力，而不僅僅是服務於全自動的 AI 代理。 ### Sprint 4 之後 (或並行進行)：協議層與 CI/CD 的深度集成 **時機**: 在我們完成了 Sprint 4，交付了約束與鎖定功能之後。 **目標**: 確保我們的 MCP 能夠穩定、可靠地作為一個自動化守護進程，在 CI/CD 和其他需要標準化 I/O 的環境中運行。 **測試內容**: #### stdio (標準輸入/輸出) 連接模式測試 - 這是許多語言伺服器（Language Server）和守護進程的標準通信方式 - 我們需要為 Mnemosyne MCP 開發一個新的啟動模式。除了 run-server，還應該有一個 run-stdio 模式 - 在 run-stdio 模式下，MCP 不再監聽網絡端口，而是從其 stdin 讀取 JSON-RPC 2.0 請求，並將響應寫入其 stdout - **驗收標準**: 編寫一個測試腳本，通過管道將請求發送給 MCP 進程，並能成功接收和解析其響應 #### SSE (Server-Sent Events) 測試 - 對於我們的 REST Gateway，我們需要為那些耗時較長的任務（如 Ingest）提供一個 SSE 端點，用於流式傳輸進度更新 - **驗收標準**: 在瀏覽器或使用 curl 呼叫這個 SSE 端點時，能夠持續地接收到服務器推送的進度消息 #### GitHub Action 的端到端測試 - 創建一個真實的、私有的 GitHub 倉庫 - 將我們在 Sprint 4 中開發的 GitHub Action 範例，實際地部署到這個倉庫的 CI/CD 工作流中 - 創建一個違反了我們預設約束的 PR - **驗收標準**: CI 檢查必須失敗，並且 PR 頁面上必須成功出現由 MCP Bot 自動發表的、帶有詳細警告的評論 **階段價值**: 確保了 Mnemosyne MCP 具備了工業級的、可靠的自動化集成能力。 --- ## 技術風險管理 ### Sprint 2 風險控制 - **向量索引性能**: 透過批量處理和增量更新降低性能風險 - **OpenAI API 限制**: 實現請求頻率控制和優雅降級 - **記憶體使用**: 監控 embedding 生成過程的記憶體消耗 ### Sprint 3 風險控制 - **圖遍歷性能**: 限制在 1-hop 範圍內，避免圖爆炸 - **混合檢索複雜度**: 先實現簡單的加權合併，後續再優化 - **影響力分析準確性**: 建立測試用例確保分析結果的正確性 ### Sprint 4 風險控制 - **併發鎖定死鎖**: 實現超時機制和死鎖檢測 - **CI/CD 整合穩定性**: 提供離線模式和錯誤恢復機制 - **約束驗證性能**: 確保約束檢查不會顯著影響開發工作流 --- ## 成功標準與驗收條件 ### Sprint 2 成功標準 - [ ] OpenAI API 整合完成，三個能力可正常呼叫 - [ ] 向量索引建立成功，可儲存和檢索 embeddings - [ ] Search API 能夠返回語義相關的程式碼節點 - [ ] 端到端 Demo 展示自然語言搜索功能 ### Sprint 3 成功標準 - [ ] 混合檢索 API 完成，能夠結合向量搜索和圖遍歷 - [ ] RunImpactAnalysis API 完成，能夠分析程式碼變更影響 - [ ] 1-hop 圖遍歷性能滿足要求 (< 500ms) - [ ] 兩個核心 Demo 展示圖譜洞察能力 ### Sprint 4 成功標準 - [ ] 約束模型和鎖定 API 完成並通過測試 - [ ] `mnemo pr-check` CLI 工具完成並可產生變更摘要 - [ ] GitHub Action 範例完成並驗證可用 - [ ] 完整的 CI/CD 整合流程驗證通過 --- ## 版本歷史 - **v1.0**: 初始版本，定義基本 Sprint 結構 - **v2.0**: 戰術性微調版本，優化 Sprint 2-4 的任務順序和粒度，提升開發效率和風險控制，增加集成測試與驗收門檻