Mnemosyne MCP

# Mnemosyne MCP [](https://github.com/MumuTW/Mnemosyne-mcp/actions) [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT) > 主動的、有狀態的軟體知識圖譜引擎 Mnemosyne MCP 是一個為 AI 代理和人類開發者設計的**「全知開發夥伴」**，通過將軟體專案的所有元素模型化為即時的、可查詢的知識圖譜，為開發的每一個環節提供精準的上下文、預測性的洞察和強制性的護欄。 ## 🚀 快速開始 ### 安裝選項 #### 方式一：一鍵安裝（推薦） ```bash # 使用 Claude Code 一鍵安裝 claude mcp add mnemosyne-mcp npx @MumuTW/Mnemosyne-mcp # 或手動安裝 npm install -g @mnemosyne/mcp-server # 手動配置 Claude Desktop（~/.claude/claude_desktop_config.json） { "mcpServers": { "mnemosyne": { "command": "npx", "args": ["@mnemosyne/mcp-server"] } } } ``` #### 方式二：原始碼開發 前置需求： - Docker & Docker Compose - Python 3.10+ - uv (Python 套件管理工具) ### 🎯 極簡 4 步驟啟動 **1️⃣ 克隆並設置開發環境** ```bash git clone https://github.com/your-org/mnemosyne-mcp.git cd mnemosyne-mcp make dev-setup ``` 自動完成：建立虛擬環境、安裝依賴、生成 .env、建立 logs/ 目錄 **2️⃣ 啟用虛擬環境** ```bash source .venv/bin/activate ``` **3️⃣ 設定 API 金鑰（可選但建議）** ```bash cp .env.example .env # 編輯 .env，填入 OPENAI_API_KEY 或 OPENROUTER_API_KEY ``` **4️⃣ 一鍵啟動所有服務** ```bash make deploy ``` 自動完成： - 🏗️ 建構 Docker 映像 - 📚 啟動 FalkorDB（圖形資料庫） - 🚀 啟動 FalkorDB UI（圖形可視化介面） - ⚡ 啟動 MCP API 服務（提供 /docs 和 /health） ### 🔍 驗證服務狀態 執行完畢後，可直接訪問： - **FalkorDB UI**: http://localhost:3000 — 圖譜可視化介面 - **MCP API Docs**: http://localhost:8000/docs — Swagger API 文件 - **健康檢查**: http://localhost:8000/health — 服務狀態檢查 ### 🎯 導入你的專案（可選） ```bash mnemo ingest --git https://github.com/example-org/example-repo ``` 查詢導入進度： ```bash mnemo ingest-status <task_id> ``` ## 🐳 Docker 一鍵啟動方案 ### 📋 前置需求 確保專案根目錄包含以下檔案： - `docker-compose.yml` - 服務編排配置 - `Dockerfile` - MCP 應用建置檔案 - `.env` - 環境變數設定（包含 API 金鑰） ### 🚀 一鍵啟動 1. **確保 `.env` 包含必要設定**： ```bash # 至少需要其中一組 OPENAI_API_KEY=sk-xxx # 或 OPENROUTER_API_KEY=or-xxx ``` 2. **執行啟動指令**： ```bash docker-compose up --build ``` ### 🔍 驗證狀態 啟動完成後，可訪問： - **圖形 UI**: http://localhost:3000 — FalkorDB 圖譜可視化介面 - **API 文檔**: http://localhost:8000/docs — Swagger API 文件 - **健康檢查**: http://localhost:8000/health — 服務狀態檢查 ### 💡 Docker 方案優勢 - **資料持久化**: 使用 `falkor-data` volume 確保重啟不丟資料 - **環境變數管理**: 統一在 `.env` 設定所有配置 - **可擴展性**: 可輕鬆加入 Redis 叢集、副本服務或其他 microservice - **一鍵部署**: 支援 CI/CD 接入，適合開發/staging/production 環境 ## 🛠️ 一鍵部署指令 **🎯 最快速的啟動方式** 1️⃣ **確保你已填寫 `.env`**（或複製 `.env.example`）： ```bash cp .env.example .env ``` 2️⃣ **執行部署指令**： ```bash make deploy ``` 3️⃣ **檢查服務是否成功**： - 📊 **FalkorDB UI**: http://localhost:3000 - 📚 **MCP API Docs**: http://localhost:8000/docs - ✅ **健康檢查**: http://localhost:8000/health --- ## ✅ 最終使用體驗（4 行指令完成部署） ```bash git clone https://github.com/your-org/mnemosyne-mcp.git cd mnemosyne-mcp make dev-setup && source .venv/bin/activate make deploy ``` 🎉 **完整的知識圖譜系統 + API + UI 一次啟動完成！** ### 其他開發指令 ```bash # 運行測試 make test # 代碼格式化 make format # CI 流程檢查 make ci-check # 驗證 Sprint 0 完成狀態 make sprint0-verify ``` ## 🏗️ 架構概覽 ``` src/mnemosyne/ ├── api/ # FastAPI 應用和 REST Gateway ├── core/ # 核心業務邏輯 ├── interfaces/ # 抽象介面定義 ├── drivers/ # 資料庫驅動實作 ├── schemas/ # Pydantic 數據模型 └── cli/ # 命令行工具 ``` ## 📊 當前狀態 (Sprint 0 - 已完成 ✅) - ✅ 基礎設施搭建完成 - ✅ Docker Compose 環境 - ✅ FalkorDB 整合 - ✅ GraphStoreClient 抽象層 - ✅ 完整的 API 骨架 - ✅ 健康檢查端點 - ✅ 27個單元測試全部通過 - ✅ CLI 工具和開發工具鏈 - ✅ 完整的配置管理系統 - ✅ Pydantic v2 數據模型 ## 🔄 開發流程 ### Sprint 計劃 - **Sprint 0**: 基礎設施與核心抽象層搭建 ✅ - **Sprint 1**: 數據的「生」與「現」- 實現第一個 ECL 閉環 - **Sprint 2**: AI 的「靈魂注入」- 混合檢索與核心工具 - **Sprint 3**: 治理與約束 - 建立「安全護欄」 ### 貢獻指南 1. Fork 專案 2. 創建功能分支 (`git checkout -b feature/amazing-feature`) 3. 提交變更 (`git commit -m 'Add some amazing feature'`) 4. 推送到分支 (`git push origin feature/amazing-feature`) 5. 開啟 Pull Request ## 🧪 測試 ```bash # 運行所有測試 make test # 運行特定類型的測試 uv run pytest -m unit uv run pytest -m integration uv run pytest -m e2e # 生成覆蓋率報告 make test-cov ``` ## 📝 文檔 詳細文檔請參考 `docs/` 目錄： - [產品需求文件 (PRD)](docs/DEVELOPEMENT/PRD.md) - [技術架構藍圖 (TAB)](docs/DEVELOPEMENT/TAB.md) - [API 規格](docs/DEVELOPEMENT/API.md) - [數據模型](docs/DEVELOPEMENT/data_schema.md) - [開發計劃](docs/DEVELOPEMENT/mvp_sprint.md) ## 📄 授權 本專案採用 MIT 授權 - 詳見 [LICENSE](LICENSE) 文件。 ## 🤝 支援 如有問題或建議，請： 1. 查看 [Issues](https://github.com/your-org/mnemosyne-mcp/issues) 2. 創建新的 Issue 3. 聯繫開發團隊 --- **Mnemosyne MCP** - 讓軟體開發變得更智能、更安全、更高效。