ui-chan-mcp

デスクトップマスコットを MCP（Model Context Protocol）経由で操作するサーバ。 Claude Code や任意の MCP 対応エージェントから、マスコットの見た目（顔＋腕）と声をまとめて切り替え、 吹き出しでセリフを話させることができます。

• 表示層は Electron（透過・最前面・画面右下）

• 立ち絵は PSDTool 形式の PSD（!=必須レイヤー、*=ラジオ切替）をそのまま利用

• 見た目＋声は Cue（1ファイル=1つの完成した見た目＋声）という単位で管理。エージェント向けの 視覚操作ツールは set_cue ただ1つ

• 発話キュー・複数エージェント同時接続に対応

立ち絵 PSD はリポジトリに含まれていません（著作権保護された素材のため）。 assets/ に PSDTool 対応の PSD を置くと動きます。無い場合はプレースホルダで起動します。 同梱の 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 の追加 UI は 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"]
    }
  }
}

同じことを1コマンドでやる場合（既存の設定は保持し、.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: pov

アーキテクチャ

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 で1回ビルドするので、 クローン直後も 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秒に1回まで）、REST が応答するまで最大20秒待ちます。 get_state の warnings に理由が出ます。詳しくは docs/TTS.md。

まず npm run app で単体起動を試すと切り分けられます。プラグイン導入時は SessionStart フックが起動を試みるので、通常はセッションを開くだけで出てきます。 PSD が assets/ に無い場合はプレースホルダ表示になります。

cues/<名前>.json を1ファイル作るだけです。継承なし・完全に自己完結で、保存すると即リロードされます。 ビジュアルに作るなら 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）に届いていません。感謝・気遣い・覚えていてくれること で上がります。 直球の好意表現はむしろ下がります。

ドキュメント