Live2d To Agent

轻量的、可在 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. 安装依赖

# 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. 启动桌宠

cd packages/desktop-pet
python main.py

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

4. 配置 MCP 客户端

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

npm run build

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

{
  "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 在后台进程中解析失败：

{
  "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 添加（添加后仍需检查路径是否为绝对路径）：

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）

开发

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

# 运行测试
npm test

# WebSocket 层测试
python scripts/test_websocket.py

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

技术债

详见 TECH_DEBT.md。当前已知：

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

许可

• 本项目代码采用 MIT 协议。
• packages/desktop-pet/ 基于 Live2DMascot（MIT, by Arkueid）fork。
• Live2D Cubism SDK 及模型文件 不包含在本仓库中，受 Live2D 官方许可条款 约束，由用户自行获取与安装。