ui-chan-mcp

通过 MCP（Model Context Protocol）操作桌面宠物的服务器。 从 Claude Code 或任意支持 MCP 的智能体，可以整体切换宠物的外观（脸＋手臂）和声音，并让它在气泡中说出台词。

• 显示层使用 Electron（透明・置顶・屏幕右下角）

• 立绘直接使用 PSDTool 格式的 PSD（!=必需图层、*=单选切换）

• 外观＋声音以 Cue（1个文件=1套完整的外观＋声音）为单位管理。面向智能体的视觉操作工具只有 set_cue 一个

• 支持说话队列・多个智能体同时连接

立绘 PSD 不包含在仓库中（因为素材受版权保护）。 将兼容 PSDTool 的 PSD 放到 assets/ 即可运行。如果没有，则使用占位符启动。 随附的 ui-chan.config.json 和 cues/*.json 面向 雨衣（うい）立绘素材（坂本アヒル様） 的图层结构。 请在雨衣角色指南的范围内使用。

设置

→ 图解设置步骤 （从克隆到画面出现为止。以人类或 AI 都能理解的粒度编写。 相同内容也放在 docs/setup-page.html 中）

给赶时间的人的摘要：

git clone https://github.com/Uncle-Peke/ui-chan-mcp.git && cd ui-chan-mcp
npm install                     # 依存の取得 + ビルド（prepare で dist/ まで作られる）
cp .env.example .env            # VoiSona Talk の資格情報（音声を使わないなら不要）
# 立ち絵 PSD を assets/ に配置
npm run doctor                  # ビルド・PSD・資格情報・エンジン起動をまとめて確認

连接

无论用哪种连接方式，连接完成即配置完成。宠物应用和 VoiSona Talk 会在连接时自动启动， 人格会通过 MCP 握手（instructions）传递。无需手动粘贴人格文件。

以插件方式安装（Claude Code / Claude Desktop 通用・推荐）

插件注册表由 Claude Code 和 Claude Desktop 共享。在 Claude Code 中注册一次后， Desktop 端的“设置 → 插件”中也会出现相同的插件（反过来，Desktop 的添加界面只能从 GitHub 添加，无法指定本地文件夹）。

/plugin marketplace add /path/to/ui-chan-mcp      # ローカルのクローンから
/plugin install ui-chan@ui-chan

如果从 GitHub 安装，请指定 Uncle-Peke/ui-chan-mcp（但 dist/ 没有被提交，因此需要 另外克隆并执行 npm install 后的实体）。

安装插件后，连接器（MCP 服务器）也会一并注册（.mcp.json）。 无需手动注册连接器，如果两者都做，同一个服务器会启动两次。

只使用 MCP 服务器（仅连接器）

不需要技能或钩子，只需要工具和人格时使用此方式。Claude Desktop 请通过 设置 → 开发者 → 编辑设置 打开 claude_desktop_config.json，追加以下内容后 完全退出应用（⌘Q）再重新启动。command 中请填入 which node 的结果 （Claude Desktop 与终端的运行环境不同，只写 node 有时会找不到）。

{
  "mcpServers": {
    "ui-chan": {
      "command": "/usr/local/bin/node",
      "args": ["/path/to/ui-chan-mcp/dist/mcp-server.js"]
    }
  }
}

如果要用一条命令完成同样的操作（保留现有设置，并留下 .bak）：

npm run install-desktop        # 解除は npm run install-desktop -- --remove

如需在 Claude Code 中手动注册，步骤如下。凭据会从 .env 读取，因此无需 env。

claude mcp add ui-chan -- node /path/to/ui-chan-mcp/dist/mcp-server.js

安装方式的区别

这不是 Claude Code 与 Claude Desktop 的差别，而是安装方式的差别。无论哪种应用， 以插件方式安装后都能使用相同的功能。

Related MCP server: Persona Motion Studio

架构

MCP 服务器是薄桥接层，所有状态都集中在 Electron 应用侧。 即使多个智能体同时连接，状态也不会不一致。

flowchart LR
  agent["エージェント<br/>(Claude Code 等)"]
  mcp["dist/mcp-server.js<br/>ステートレスなブリッジ"]

  subgraph app["Electron アプリ (dist/app/main.js)"]
    direction TB
    state["UiChanState<br/>発話キュー・好感度・アイドル"]
    tts["VoiSonaTalkClient<br/>音声合成"]
    renderer["レンダラ<br/>PSD合成・吹き出し・口パク"]
  end

  voisona["VoiSona Talk<br/>REST API :32766"]

  agent -- "stdio (MCP)" --> mcp
  mcp -- "WebSocket :8123" --> state
  mcp -. "未起動なら自動起動" .-> app
  mcp -. "未起動なら自動起動" .-> voisona
  state --> tts
  tts -- "WAV + 音素タイミング" --> renderer
  tts <--> voisona
  state -- "IPC (RenderCommand)" --> renderer

• 端口 — ui-chan.config.json 的 port，或环境变量 UI_CHAN_PORT

• 自动启动 — 应用在会话开始（SessionStart 钩子）和每次工具调用时，VoiSona Talk 在 MCP 启动时和每次 set_cue 时，如果进程已退出就会重新拉起

• 智能体名称 — 从 MCP 客户端信息自动获取（可用 UI_CHAN_AGENT_NAME 覆盖）

更详细的实现指南请参阅 CLAUDE.md。

命令列表

MCP 工具（由智能体调用）

Cue 列表由 persona 提示词（以及 SessionStart 钩子）在每次启动时从 cues/*.json 生成， 并传给智能体的上下文。

斜杠命令（安装插件时）

npm 脚本

Q&A

只有修改了 src/ 中的 TypeScript 时才需要。npm install 会通过 prepare 构建一次， 所以克隆后也不需要执行 npm run build。Cue 和 ui-chan.config.json 都是 JSON，不需要构建（Cue 保存后会立即重新加载）。

不过，MCP 服务器会一直持有会话开始时的代码继续运行。即使重新构建， 也不会反映到该会话中，请重新连接 MCP 或重新打开会话。

请运行 npm run doctor。常见原因包括：VoiSona Talk 未启动、 .env 中没有凭据、或 VoiSona 侧没有启用 REST API。

即使没有声音，气泡也会显示，口型也会根据 reading 的假名动起来。 VoiSona 会在每次 set_cue 时被重新拉起（最多每30秒一次），并最多等待 REST 响应20秒。 原因会显示在 get_state 的 warnings 中。详见 docs/TTS.md。

可以先运行 npm run app 单独启动来排查。安装插件时， SessionStart 钩子会尝试启动，所以通常只要打开会话就会出现。 如果 assets/ 中没有 PSD，则会以占位符显示。

只需创建 cues/<名称>.json 一个文件即可。无继承・完全自包含，保存后会立即重新加载。 想以可视化方式制作请用 npm run editor。格式与图层指定见 docs/CUES_AND_CONFIG.md，PSD 图层名速查表见 docs/CUES.md。

请编辑 persona/ui-chan.md（基本人格与工具使用方针）和 context/*.md（SOUL.md 价值观 / VOCABULARY.md 词汇・NG 词 / AFFINITY.md 好感度）。放在 context/ 中的 Markdown 会 按文件名顺序全部注入到智能体。详见 docs/PERSONA.md。

通过 ui-chan.config.json 中 idle.idlingCues 的 minSec / maxSec（默认 120〜300 秒）调整间隔， 通过各 IdlingCue 的 weight 调整出现概率。也可以用 minAffinity / maxAffinity 按好感度区分触发。

请调整 ui-chan.config.json 的 eventCues.events。每个事件名都有台词池， 用 cooldownSec（由具有相同 throttleKey 的事件共享）和 chance 调整吵闹程度。 内容与 IdlingCue 形式相同，所以可以使用 weight / minAffinity / maxAffinity / hours。

可用事件：permission（等待许可）、idle_wait（等待输入）、tool_failure、 turn_done、compact、agent_out（送出子智能体）、agent_back（归来）。

用 npm run debug 的 event <事件名> 确认。钩子侧（hooks/）只负责抛出事件名， 所以修改台词不需要碰 JavaScript。

用 npm run dump-psd -- path/to/file.psd 确认图层名，然后改写 ui-chan.config.json 和 cues/*.json（基础是 cues/default.json）。人格侧请将 persona/ 和 context/ 整体替换。 不存在的图层路径会被忽略并显示在 get_state 的 warnings 中， 所以替换过程中也不会崩溃。

好感度还没有达到阈值（65）。通过感谢、体贴、记得她都会提升。 直白的好意表达反而会下降。

文档