ui-chan-mcp

Сервер для управления настольным маскотоном через MCP (Model Context Protocol). Позволяет из Claude Code или любого MCP-совместимого агента переключать внешний вид маскотона (лицо + руки) вместе с голосом и произносить реплики в облачке.

• Отображение — Electron (прозрачный, поверх всех окон, правый нижний угол экрана)

• Спрайт — используется как есть PSD в формате PSDTool (!=обязательный слой, *=радио-переключатель)

• Внешний вид + голос управляются как Cue (1 файл = один готовый внешний вид + голос). Для агентов есть только один инструмент визуального управления — set_cue

• Поддержка очереди речи и одновременного подключения нескольких агентов

Стоячие спрайты PSD не включены в репозиторий (из-за защищённых авторским правом материалов). Работает, если положить PSD, совместимый с PSDTool, в assets/. Если его нет, приложение запускается с плейсхолдером. Включённые ui-chan.config.json и cues/*.json рассчитаны на структуру слоёв 雨衣（うい）立ち絵素材（坂本アヒル様）. Используйте в рамках 雨衣キャラクターガイドライン.

Установка

→ Иллюстрированные шаги настройки (от клонирования до появления на экране; описано с такой детализацией, что поймёт и человек, и ИИ. То же самое есть в 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

• Порт — port в ui-chan.config.json или переменная окружения UI_CHAN_PORT

• Автозапуск — приложение поднимается заново при старте сессии (хук SessionStart) и при каждом вызове инструмента; VoiSona Talk — при запуске MCP и при каждом set_cue, если они не были запущены

• Имя агента — автоматически берётся из информации MCP-клиента (можно переопределить через UI_CHAN_AGENT_NAME)

Более подробное руководство по реализации см. в CLAUDE.md.

Список команд

MCP-инструменты (вызываются агентом)

Список Cue генерируется при каждом запуске из cues/*.json промптом persona (и хуком SessionStart) и передаётся в контекст агента.

Слэш-команды (при установке плагина)

npm-скрипты

Q&A

Только когда вы правили TypeScript в src/. Поскольку 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 секунд. Причина отображается в warnings у get_state. Подробнее: docs/TTS.md.

Сначала попробуйте запустить отдельно через npm run app — это поможет локализовать проблему. При установке плагина хук SessionStart пытается запустить приложение, так что обычно оно появляется просто при открытии сессии. Если PSD нет в assets/, отображается плейсхолдер.

Достаточно создать один файл cues/<名前>.json. Без наследования, полностью самодостаточный; после сохранения сразу перезагружается. Для создания в визуальном режиме — npm run editor. Формат и указание слоёв — в docs/CUES_AND_CONFIG.md, шпаргалка по именам слоёв PSD — в docs/CUES.md.

Это persona/ui-chan.md (базовая личность и правила использования инструментов) и context/*.md (SOUL.md — ценности / VOCABULARY.md — словарь и запрещённые слова / AFFINITY.md — уровень симпатии). Все Markdown-файлы в context/ внедряются в агента в порядке имён файлов. Подробнее: docs/PERSONA.md.

Интервал задаётся через minSec / maxSec (по умолчанию 120–300 секунд) в idle.idlingCues файла ui-chan.config.json, а частота появления — через weight каждого IdlingCue. С помощью minAffinity / maxAffinity можно также управлять появлением в зависимости от уровня симпатии.

Это eventCues.events в ui-chan.config.json. Для каждого имени события есть пул реплик; cooldownSec (общий для событий с одинаковым throttleKey) и chance регулируют степень шумности. Содержимое имеет ту же форму, что и IdlingCue, поэтому доступны weight / minAffinity / maxAffinity / hours.

Доступные события: permission (ожидание разрешения), idle_wait (ожидание ввода), tool_failure, turn_done, compact, agent_out (отправка субагента), agent_back (возвращение).

Проверить можно командой event <イベント名> в npm run debug. Сторона хуков (hooks/) только отправляет имя события, поэтому для изменения реплик не нужно трогать JavaScript.

Проверьте имена слоёв через npm run dump-psd -- path/to/file.psd и перепишите ui-chan.config.json и cues/*.json (основа — cues/default.json). Сторону личности замените целиком: persona/ и context/. Несуществующие пути слоёв игнорируются и показываются в warnings у get_state, поэтому при замене краха не будет.

Уровень симпатии не достиг порога (65). Он повышается за благодарность, заботу и то, что вы помните о ней. Прямолинейные выражения симпатии, наоборот, снижают его.

Документация