# DeepAnalyze MCP Server

這是 DeepAnalyze 的 MCP (Model Context Protocol) 服務器，讓 AI Agent 能夠調用 DeepAnalyze 的智能分析功能。

## 功能

提供以下 MCP 工具供 Agent 調用：

| 工具名稱               | 說明                                   |
| ---------------------- | -------------------------------------- |
| `deepanalyze_generate` | 完整的多輪推理分析，自動執行代碼並迭代 |
| `deepanalyze_async`    | 異步版本的多輪推理分析                 |
| `execute_python_code`  | 在指定目錄安全執行 Python 代碼         |
| `list_workspace_files` | 列出工作目錄中的檔案                   |
| `read_file_content`    | 讀取檔案內容                           |

## 安裝

```bash
cd mcp
pip install -r requirements.txt
```

## 配置

項目使用 `config.json` 檔案來管理 API URL 和其他預設設定。首次使用前，請確認配置文件中的設定：

```json
{
  "api_url": "http://192.168.71.22:1234/v1/chat/completions",
  "model_name": "deepseek-ai/DeepSeek-R1",
  "max_rounds": 30,
  "default_temperature": 0.1,
  "default_max_tokens": 32768
}
```

可配置項目：

- `api_url`: vLLM API 服務器地址
- `model_name`: 預設模型名稱
- `max_rounds`: 最大推理輪數
- `default_temperature`: 預設生成溫度
- `default_max_tokens`: 預設最大 token 數

**注意**: 修改配置文件後，使用配置的工具會自動讀取新的預設值。

## 使用方式

### 1. 直接運行

```bash
python server.py
```

### 2. 配置到 VS Code

在 VS Code 的 `settings.json` 中添加：

```json
{
  "mcp.servers": {
    "deepanalyze": {
      "command": "python",
      "args": ["c:/code/vscode/agents/DeepAnalyze/mcp/server.py"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
```

### 3. 配置到 Claude Desktop

在 Claude Desktop 配置檔案中添加：

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "deepanalyze": {
      "command": "python",
      "args": ["C:\\code\\vscode\\agents\\DeepAnalyze\\mcp\\server.py"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
```

## 工具使用範例

### deepanalyze_generate

多輪推理分析，適合複雜的數據分析任務：

```json
{
  "prompt": "請分析 sales.csv 中的銷售趨勢，並生成月度報表圖表",
  "workspace": "C:/data/analysis",
  "model_name": "DeepAnalyze-8B",
  "temperature": 0.5,
  "max_rounds": 20
}
```

**注意**: `api_url` 會自動從 `config.json` 讀取，無需在每次調用時指定。如需臨時覆蓋，可在參數中添加 `"api_url": "http://your-server:port/v1/chat/completions"`。

### execute_python_code

執行單段 Python 代碼：

```json
{
  "code": "import pandas as pd\ndf = pd.read_csv('data.csv')\nprint(df.describe())",
  "workspace_dir": "C:/data/analysis",
  "timeout_sec": 60
}
```

### list_workspace_files

列出工作目錄中的檔案：

```json
{
  "workspace_dir": "C:/data/analysis"
}
```

### read_file_content

讀取檔案內容：

```json
{
  "file_path": "C:/data/analysis/result.txt",
  "encoding": "utf-8",
  "max_chars": 5000
}
```

## 架構說明

```
mcp/
├── __init__.py          # 模組初始化
├── deepanalyze_core.py  # 核心功能（DeepAnalyzeVLLM 類別）
├── server.py            # MCP 服務器主程式
├── mcp_config.json      # MCP 配置範例
├── requirements.txt     # Python 依賴
└── README.md            # 說明文檔
```

### 核心流程

```
Agent 發送請求
      ↓
MCP Server 接收
      ↓
調用 DeepAnalyzeVLLM
      ↓
┌─────────────────────┐
│  多輪推理迴圈        │
│  ┌───────────────┐  │
│  │ 模型生成回應    │  │
│  │      ↓        │  │
│  │ 提取 <Code>    │  │
│  │      ↓        │  │
│  │ 執行代碼       │  │
│  │      ↓        │  │
│  │ 回傳結果給模型  │  │
│  └───────────────┘  │
│  重複直到 <Answer>  │
└─────────────────────┘
      ↓
返回最終結果給 Agent
```

## 注意事項

1. **安全性**：程式碼會在指定的 workspace 目錄中執行，請確保不會影響重要檔案
2. **超時保護**：預設 120 秒超時，可調整 `timeout_sec` 參數
3. **模型服務**：需要先啟動 vLLM 服務或相容的 API 服務
4. **中文支援**：自動配置 matplotlib 中文字體

## License

MIT License