# Live2D MCP

> 轻量的、可在 Agent 运行时让 Agent 接入控制的 Live2D 桌面宠物。

Agent 通过 MCP（Model Context Protocol）控制桌宠的表情、动作、模型和窗口设置，无需绑定特定 Live2D SDK。

## 架构

```
Agent (Claude / 任意 MCP 客户端)
  │  MCP JSON-RPC over STDIO
  ▼
packages/adapters/mcp   ← TypeScript MCP Adapter
  │  WebSocket :9228
  ▼
packages/desktop-pet    ← Python 桌宠 (PySide6 + OpenGL)
  │  live2d-py (用户自行安装)
  ▼
Live2D 模型渲染
```

消息流：Agent → MCP STDIO → Adapter → WebSocket → desktop-pet → Model API。

## 仓库结构

```
packages/
├── protocol/              # L2D 消息类型与 JSON Schema (传输无关)
├── adapters/mcp/          # MCP JSON-RPC STDIO Adapter → WebSocket 转发
└── desktop-pet/           # Python 桌面宠物 (基于 Live2DMascot, MIT)
    ├── app/               # 全局设置与版本定义
    ├── config/            # QConfig 持久化设置
    ├── control/           # WebSocket 服务 (:9228)
    ├── ui/                # Qt 窗口、系统托盘、设置面板
    ├── utils/             # 模型操作、model3.json 解析
    ├── Resources/         # 模型资源 (gitignore, 用户自行放入)
    ├── main.py            # 入口
    └── application.py     # 生命周期与组件编排
```

## 快速开始

### 前置条件

- Node.js 20+
- Python 3.13+ (64 位)
- Windows（当前仅支持 Windows，因 live2d-py 提供 Win 平台 wheel）

### 1. 安装依赖

```bash
# TypeScript 侧
npm install

# Python 侧
cd packages/desktop-pet
pip install -r requirements.txt
```

`live2d-py` 不包含在本仓库中，由用户通过 `pip install live2d-py` 自行安装，以规避 Live2D 官方 SDK 分发许可。

### 2. 准备模型资源

模型文件不包含在仓库中。将 Live2D 模型放入 `packages/desktop-pet/Resources/v3/`：

```
Resources/v3/
├── Haru/
│   ├── Haru.model3.json    # 入口文件
│   ├── Haru.moc3
│   ├── Haru.physics3.json
│   ├── Haru.2048/           # 纹理
│   ├── expressions/         # 表情
│   ├── motions/             # 动作
│   └── sounds/              # 语音
├── Natori/
└── ...
```

### 3. 启动桌宠

```bash
cd packages/desktop-pet
python main.py
```

桌宠窗口出现后，WebSocket 服务在 `ws://127.0.0.1:9228` 监听。

### 4. 配置 MCP 客户端

#### 方式 A：构建产物（推荐）

```bash
npm run build
```

在 MCP 客户端配置中指向构建产物：

```json
{
  "mcpServers": {
    "live2d-pet": {
      "command": "node",
      "args": ["/absolute/path/to/live2d-mcp/packages/adapters/mcp/dist/index.js"]
    }
  }
}
```

#### 方式 B：开发模式（tsx 直接运行 .ts）

用 `node --import` 加载 tsx loader，避免 `npx tsx` 在后台进程中解析失败：

```json
{
  "mcpServers": {
    "live2d-pet": {
      "type": "stdio",
      "command": "node",
      "args": [
        "--import",
        "file:///absolute/path/to/live2d-mcp/node_modules/tsx/dist/loader.mjs",
        "/absolute/path/to/live2d-mcp/packages/adapters/mcp/src/index.ts"
      ],
      "env": {}
    }
  }
}
```

也可通过 Claude CLI 添加（添加后仍需检查路径是否为绝对路径）：

```bash
claude mcp add live2d-pet -- \
  node \
  --import file:///absolute/path/to/live2d-mcp/node_modules/tsx/dist/loader.mjs \
  /absolute/path/to/live2d-mcp/packages/adapters/mcp/src/index.ts
```

#### 配置注意事项

| # | 错误做法 | 问题 | 正确做法 |
|---|----------|------|----------|
| 1 | 手动创建 `~/.claude/.mcp.json` | `.mcp.json` 是项目级配置，全局 MCP 服务器不读这个文件 | 全局配置写在 `~/.claude.json` 顶层 `mcpServers` 中 |
| 2 | 用 `npx tsx` 作为 command | `npx` 在 Claude 后台进程中可能解析失败 | 用 `node --import <tsx loader 绝对路径>` 替代 |
| 3 | 使用相对路径 `src/index.ts` | 无 `cwd` 时从用户主目录解析，找不到文件 | 所有路径用绝对路径 |
| 4 | 在配置中设置 `cwd` 字段 | Claude 的 MCP 启动器不支持 `cwd`，设置无效 | 所有路径用绝对路径 |

配置后重启 MCP 客户端，Agent 即可通过 7 个工具控制桌宠。

## MCP 工具

| 工具 | 参数 | 说明 |
|------|------|------|
| `model_load` | `path` | 加载指定路径的模型，返回表情列表 |
| `expression_list` | — | 列出当前模型的可用表情 |
| `expression_set` | `name` | 切换到指定表情 |
| `action_list` | — | 列出可用的语义动作 |
| `action_perform` | `name` | 播放指定动作 |
| `settings_get` | — | 读取窗口、模型、音频、场景设置 |
| `settings_set` | 键值对 | 修改设置（如 `model.scale`、`window.width`） |

## 开发

```bash
# 类型检查与构建
npm run check
npm run build

# 运行测试
npm test

# WebSocket 层测试
python scripts/test_websocket.py

# MCP 闭环测试
node scripts/test_mcp.mjs
```

## 技术债

详见 [TECH_DEBT.md](./TECH_DEBT.md)。当前已知：

- **TD-001**：点击模型触发 `Touch` 方法报错（PyPI 版 live2d-py API 缺失），留到 AvatarRuntime 适配层修复。

## 许可

- 本项目代码采用 **MIT** 协议。
- `packages/desktop-pet/` 基于 [Live2DMascot](https://github.com/Arkueid/Live2DMascot)（MIT, by Arkueid）fork。
- Live2D Cubism SDK 及模型文件 **不包含**在本仓库中，受 [Live2D 官方许可条款](https://www.live2d.com/en/sdk/license/) 约束，由用户自行获取与安装。