# MCP Server 配置

MCP (Model Context Protocol) 是 Anthropic 提出的协议，允许 AI 工具返回原生内容（如图片）直接显示在聊天窗口中。

## 为什么使用 MCP？

| 方式 | 图片显示 | 配置复杂度 |
|------|----------|------------|
| HTTP API | 需要 Read 工具读取文件路径 | 简单 |
| **MCP Server** | **原生显示在聊天窗口** | 中等 |

## 配置步骤

### 方式一：使用 uvx (推荐，无需安装依赖)

直接在 Cursor 配置中使用 `uvx` 拉起最新版客户端（需安装 [uv](https://github.com/astral-sh/uv)）。此方式无需污染 ComfyUI 环境，且自动保持更新。

在项目根目录创建/编辑 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "animatool": {
      "command": "uvx",
      "args": [
        "--from",
        "comfyui-animatool",
        "animatool-mcp"
      ],
      "env": {
        "COMFYUI_URL": "http://127.0.0.1:8188",
        "ANIMATOOL_CHECK_MODELS": "false"
      }
    }
  }
}
```

> 说明：`ANIMATOOL_CHECK_MODELS` 设为 `false` 可跳过本地模型检查（适合远程连接 ComfyUI 的场景）。

### 方式二：直接运行插件内置 Server (开发调试用)

如果你需要修改 server 代码，或者不想安装 uv，可以直接运行插件目录下的脚本。

1. **安装依赖**：
   ```bash
   # 在 ComfyUI 的 python 环境中
   pip install mcp
   ```

2. **配置 Cursor**：

```json
{
  "mcpServers": {
    "anima-tool": {
      "command": "<PATH_TO_PYTHON>",
      "args": ["<PATH_TO>/ComfyUI-AnimaTool/servers/mcp_server.py"],
      "env": {
        "COMFYUI_URL": "http://127.0.0.1:8188",
        "COMFYUI_MODELS_DIR": "<PATH_TO>/ComfyUI/models"
      }
    }
  }
}
```

#### 路径示例 (方式二)

**Windows**：

```json
{
  "mcpServers": {
    "anima-tool": {
      "command": "C:\\ComfyUI\\.venv\\Scripts\\python.exe",
      "args": ["C:\\ComfyUI\\custom_nodes\\ComfyUI-AnimaTool\\servers\\mcp_server.py"],
      "env": {
        "COMFYUI_URL": "http://127.0.0.1:8188",
        "COMFYUI_MODELS_DIR": "C:\\ComfyUI\\models"
      }
    }
  }
}
```

**macOS/Linux**：

```json
{
  "mcpServers": {
    "anima-tool": {
      "command": "/path/to/ComfyUI/.venv/bin/python",
      "args": ["/path/to/ComfyUI/custom_nodes/ComfyUI-AnimaTool/servers/mcp_server.py"]
    }
  }
}
```

### 3. 重启 Cursor

重启 Cursor 以加载 MCP Server 配置。

## 验证配置

### 检查状态

Cursor Settings → MCP → 查看 `anima-tool` 状态

状态说明：
- ✅ Running：正常运行
- ❌ Failed：启动失败，点击查看日志
- ⏳ Starting：正在启动

### 测试生成

在 Cursor 聊天中输入：

> 画一个穿白裙的少女，竖屏 9:16，safe

如果配置正确，图片会直接显示在聊天窗口中。

## 故障排除

### "Connection closed" 错误

1. 确认 `mcp` 库已安装到正确的 Python 环境
2. 检查路径转义（Windows 使用 `\\` 或 `/`）
3. 使用绝对路径

### MCP Server 没加载

1. 检查 Cursor Settings → MCP → anima-tool 状态
2. 点击 "Show Output" 查看日志
3. 确认 Python 路径正确

### 生成失败

1. 确认 ComfyUI 正在运行（`http://127.0.0.1:8188`）
2. 确认 Anima 模型文件存在
3. 检查 ComfyUI 控制台错误

### LoRA 报错："Value not in list: lora_name ..."

这是 ComfyUI 的枚举校验：`LoraLoaderModelOnly.lora_name` 必须与 `GET /models/loras` 返回的字符串 **逐字一致**。

- Windows 下通常是反斜杠路径（例如 `_Anima\cosmic_xxx.safetensors`）
- 如果你在 JSON 里写，需要写成 `_Anima\\cosmic_xxx.safetensors`

PowerShell 一行命令获取 LoRA 列表：

```powershell
Invoke-RestMethod -Uri "http://127.0.0.1:8188/models/loras"
```

### 手动测试

```bash
python /path/to/ComfyUI-AnimaTool/servers/mcp_server.py
```

正常情况下不会有输出（MCP 使用 stdio 通信）。如果有错误会打印到 stderr。

---

## 其他客户端支持

### Cherry Studio

Cherry Studio v0.9.0+ 支持 MCP 协议。

#### 方式一：使用 uvx (推荐)

无需在 ComfyUI 环境安装依赖，直接运行：

在 Cherry Studio 设置 -> MCP Servers -> 点击添加：

- **Type**: `stdio`
- **Command**: `uvx`
- **Args** (注意：请分三行填写):
    ```text
    --from
    comfyui-animatool
    animatool-mcp
    ```
- **Environment Variables**:
    - `COMFYUI_URL`: `http://127.0.0.1:8188`

#### 方式二：本地运行 (使用 ComfyUI Python)

- **Type**: `stdio`
- **Command**: `<PATH_TO_PYTHON>` (ComfyUI 的 Python 解释器路径)
- **Args**: `<PATH_TO>/ComfyUI-AnimaTool/servers/mcp_server.py` (填入绝对路径)
- **Environment Variables**:
    - `COMFYUI_URL`: `http://127.0.0.1:8188`

### SillyTavern (酒馆)

需安装 [SillyTavern MCP Client](https://github.com/Moeblack/sillytavern-mcp-client) 扩展。

1. 打开 Extensions -> MCP Client -> Manage Servers
2. 点击 **Add Server (JSON)**
3. 填入以下配置（使用 uvx 示例）：

```json
{
  "id": "animatool",
  "name": "Anima Tool",
  "transport": {
    "type": "stdio",
    "command": "uvx",
    "args": [
      "--from",
      "comfyui-animatool",
      "animatool-mcp"
    ],
    "env": {
      "COMFYUI_URL": "http://127.0.0.1:8188"
    }
  },
  "enabled": true,
  "autoConnect": true
}
```

> 注意：如需使用本地 Python 环境，请将 `command` 改为 python 路径，`args` 改为 `["/path/to/ComfyUI-AnimaTool/servers/mcp_server.py"]`。

---

## 补充：导入 AI 技能库 (Skills)

除了配置 MCP Server 提供工具接口外，**强烈建议**在你的 AI 客户端中导入本仓库提供的技能文档（位于 `skills/` 目录）：

- `skills/how-to-use-animatool.md`
- `skills/how-to-use-qwenedit.md`

**为什么需要导入？**
MCP 仅告诉 AI "有哪些参数可以调用"，而 Skill 文档则告诉 AI "**在什么场景下该怎么构思提示词、如何避免由于人类指令模糊导致的翻车**"。支持 Skill 或 Custom Instructions 的客户端（如 Cursor、Cline 等）可以直接配置或引用这些 `.md` 文件的内容。