mcp-ddd-analysis

DDD 建模 MCP 服務：以一組 MCP tools 涵蓋「需求描述記錄 → 事件溯源建模 → 模型查詢與驗證」三個階段。

• 需求描述存於目標專案的 .dev/requirement/requirement-{date}-{time}.docx，固定五章結構（大綱／異動歷程／模組總覽／模組介紹／資料庫），每次編輯自動在「異動歷程」表格追加一列。
• 模型以事件溯源儲存於 .dev/ddd-model/：每次變更寫入 events/event-{seq}.json（唯一真相來源），模型物件為套用事件後的快照 {type}-{name}-{version}.json。支援 DDD 戰術八構件：entity、valueobject、service、module、factory、repository、aggregate、domain-event。
• 本體論原則：行為（behaviors，含前後置條件與發出的事件）與規則（rules，invariant/policy/validation）內嵌於模型物件本身。

安裝與註冊

需求：Python >= 3.10、uv（npm 方式另需 Node >= 18）。

方式一：npm（推薦）

claude mcp add ddd-analysis -- npx -y mcp-ddd-analysis

npx 啟動殼層會自動把目前工作目錄傳為 --project-root（也可自行指定參數或設 DDD_PROJECT_ROOT）。

方式二：從原始碼

uv sync

註冊到 Claude Code（在要建模的目標專案目錄下執行，server 以啟動時的 cwd 作為 project root）：

claude mcp add ddd-analysis -- uv --directory /path/to/mcp-ddd-analysis run mcp-ddd-analysis

也可明確指定目標專案：... run mcp-ddd-analysis --project-root /path/to/target-project，或設環境變數 DDD_PROJECT_ROOT。一個 server instance 對應一個專案（單一寫入者，免檔案鎖，適用 WSL2 /mnt/c）。

Tools（15 個）

| 區域 | Tool | 說明 | |---|---|---| | 需求 | create_requirement_doc | 依五章模板建立 docx，寫入第一筆異動歷程 | | 需求 | list_requirement_docs | 列出文件與編輯統計 | | 需求 | read_requirement_doc | 讀全文或指定章節（section key 見下） | | 需求 | update_requirement_section | 改寫/追加章節並自動記錄異動歷程；可自動插入新模組節 | | 建模 | create_model_object | 建立模型物件（ObjectCreated 事件 + v1 快照） | | 建模 | update_model_object | 一次呼叫 = 版本 +1；changes 可含多個 op，展開為多筆事件 | | 建模 | deprecate_model_object | 廢棄物件並回報仍引用它的物件 | | 建模 | rebuild_snapshots | 從事件日誌重播，修復/校驗快照 | | 建模 | get_workspace_info | 回報綁定的 project root 與統計 | | 查詢 | list_model_objects | 列最新版物件，可依 type / module 過濾 | | 查詢 | get_model_object | 取完整快照（latest 或指定版本） | | 查詢 | get_object_history | 物件的完整事件歷史 | | 查詢 | get_model_graph | 關係圖 {nodes, edges} | | 查詢 | diff_model_versions | 兩版本差異 + 期間事件 | | 查詢 | validate_model | 一致性驗證 V01–V13（聚合封裝、identity、VO 不可變…） |

章節 key（編號會隨模組增減，故以 key 定位）：1 大綱、2 異動歷程（唯讀）、3 模組總覽、4.{模組名} 模組引言、4.{模組名}.{1-5} 或 4.{模組名}.主要情境 等子節、5.1／5.2 資料庫小節。

開發

uv run pytest          # 50 個單元/整合測試

設計重點：

• modeling/projector.py 是唯一計算物件狀態的地方；live 寫入與 rebuild 走同一條重播路徑，保證決定性。
• 寫入順序固定「先事件、後快照」，中途中斷可用 rebuild_snapshots 修復。
• 不用檔案鎖與 symlink（drvfs 相容）；原子寫入採同目錄暫存檔 + os.replace；名稱唯一性以 casefold 比對（NTFS 大小寫不敏感）。
• docx 被 Windows 端 Word 開啟時會回傳「請先關閉 Word」的明確錯誤。