# mmap MCP Server

一個讓 AI 助理可以讀取、搜尋、轉換 MindManager `.mmap` 檔案的本地 MCP Server。

**不需要安裝 MindManager**，直接解析 `.mmap` 原始檔案格式。

---

## 🛠️ 提供的工具

| 工具 | 說明 |
|------|------|
| `read_mmap` | 讀取 .mmap 並回傳完整 JSON 結構 |
| `mmap_to_markdown` | 將 .mmap 轉換為 Markdown 大綱 |
| `search_mmap` | 搜尋包含關鍵字的節點 |
| `mmap_stats` | 回傳節點數、深度等統計資訊 |

---

## ⚙️ 安裝步驟

### 1. 複製專案

```bash
git clone <本專案的 Git 網址>
cd mmap-mcp-server
```

### 2. 建立虛擬環境並安裝相依套件

需要 Python 3.10 以上版本。

**Windows：**
```bash
python -m venv .venv
.venv\Scripts\pip.exe install fastmcp
```

**macOS / Linux：**
```bash
python3 -m venv .venv
.venv/bin/pip install fastmcp
```

### 3. 設定 MCP

在您的 AI 工具的 MCP 設定檔中加入（請調整路徑）：

**Windows：**
```json
{
  "mcpServers": {
    "mmap-reader": {
      "command": "C:/path/to/mmap-mcp-server/.venv/Scripts/python.exe",
      "args": ["C:/path/to/mmap-mcp-server/server.py"]
    }
  }
}
```

**macOS / Linux：**
```json
{
  "mcpServers": {
    "mmap-reader": {
      "command": "/path/to/mmap-mcp-server/.venv/bin/python",
      "args": ["/path/to/mmap-mcp-server/server.py"]
    }
  }
}
```

> **Antigravity IDE 設定範例（本機）：**
> ```json
> {
>   "mcpServers": {
>     "mmap-reader": {
>       "command": "d:/git/mmap-mcp-server/.venv/Scripts/python.exe",
>       "args": ["d:/git/mmap-mcp-server/server.py"]
>     }
>   }
> }
> ```

### 4. 重新啟動 AI 工具

重啟後，AI 即可使用 mmap 相關工具。

---

## 🚀 使用範例

設定完成後，您可以對 AI 說：

```
幫我讀取 D:\projects\設計.mmap 的內容
```

```
搜尋 D:\projects\設計.mmap 裡面所有包含「管理」的節點
```

```
把 D:\projects\設計.mmap 轉成 Markdown 格式給我
```

---

## 📁 專案結構

```
mmap-mcp-server/
├── server.py         ← MCP Server 主程式
├── mmap_parser.py    ← .mmap 解析核心（不依賴 MindManager）
├── requirements.txt  ← Python 相依套件清單
├── README.md         ← 本說明文件
└── .venv/            ← 虛擬環境（git clone 後自行建立，不需 commit）
```

> ⚠️ `.venv/` 目錄不需要 commit 進 Git，請在 `.gitignore` 中忽略。

---

## 🔧 相容性

- ✅ MindManager 20 / 21 / 22 及更新版本的 `.mmap` 格式
- ✅ 不需要安裝 MindManager
- ✅ Windows / macOS / Linux 均可使用
- ✅ 支援繁體中文、簡體中文、英文節點

---

## ❓ 常見問題

**Q: AI 找不到 mmap-reader 工具？**  
A: 確認 MCP 設定檔路徑正確，且已完全重新啟動 AI 工具。

**Q: 讀取失敗顯示「無效的 .mmap 檔案」？**  
A: 確認檔案沒有設定密碼保護，且副檔名為 `.mmap`。

**Q: 支援哪些 AI 工具？**  
A: 任何支援 MCP 協定的工具，包含 Antigravity IDE、Claude Desktop、Cursor 等。

**Q: 如何更新？**  
A: `git pull` 後重新啟動 AI 工具即可，不需重裝套件。