ui-chan-mcp

Ein Server zur Steuerung eines Desktop-Maskottchens über MCP (Model Context Protocol). Von Claude Code oder einem beliebigen MCP-fähigen Agenten aus lassen sich Aussehen (Gesicht + Arme) und Stimme des Maskottchens gemeinsam umschalten, und es kann über eine Sprechblase Sätze sprechen.

• Anzeige läuft über Electron (transparent, immer im Vordergrund, rechts unten am Bildschirm)

• Das Standbild wird direkt als PSD im PSDTool-Format verwendet (!=Pflicht-Layer, *=Radio-Umschaltung)

• Aussehen + Stimme werden in Einheiten namens Cue (1 Datei = ein fertiges Aussehen + Stimme) verwaltet. Das einzige visuelle Bedienwerkzeug für Agenten ist set_cue

• Unterstützt Sprechwarteschlangen und gleichzeitige Verbindungen mehrerer Agenten

Die Standbild-PSD ist nicht im Repository enthalten (da es sich um urheberrechtlich geschütztes Material handelt). Wenn Sie eine PSDTool-kompatible PSD in assets/ ablegen, funktioniert sie. Andernfalls wird mit einem Platzhalter gestartet. Die enthaltenen ui-chan.config.json und cues/*.json sind für die Layer-Struktur des Ui (雨衣)-Standbildmaterials (von Sakamoto Ahiru) gedacht. Bitte im Rahmen der Ui-Charakterrichtlinien verwenden.

Setup

→ Bebilderte Setup-Anleitung (Vom Klonen bis zur Anzeige auf dem Bildschirm. Es ist in einer Granularität geschrieben, die Menschen und KI gleichermaßen verstehen. Derselbe Inhalt ist auch in docs/setup-page.html enthalten)

Kurzfassung für Eilige:

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・資格情報・エンジン起動をまとめて確認

Verbinden

Bei jeder Verbindungsart ist die Einrichtung abgeschlossen, sobald die Verbindung hergestellt ist. Die Mascot-App und VoiSona Talk werden bei der Verbindung automatisch gestartet, und die Persönlichkeit wird über den MCP-Handshake (instructions) übermittelt. Sie müssen keine Persönlichkeitsdateien einfügen.

Als Plugin installieren (Claude Code / Claude Desktop gemeinsam, empfohlen)

Die Plugin-Registry wird zwischen Claude Code und Claude Desktop geteilt. Wenn Sie es einmal in Claude Code registrieren, erscheint dasselbe auch unter „Einstellungen → Plugins“ auf der Desktop-Seite (umgekehrt kann die Desktop-Add-UI nur von GitHub hinzufügen; lokale Ordner können nicht angegeben werden).

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

Bei Installation von GitHub geben Sie Uncle-Peke/ui-chan-mcp an (da dist/ jedoch nicht committet ist, benötigen Sie eine separate, geklonte und mit npm install eingerichtete Instanz).

Beim Installieren des Plugins wird auch der Connector (MCP-Server) mit registriert (.mcp.json). Eine manuelle Connector-Registrierung ist nicht nötig; wenn Sie beides tun, wird derselbe Server doppelt gestartet.

Nur den MCP-Server verwenden (nur Connector)

Für Fälle, in denen weder Skills noch Hooks benötigt werden, sondern nur Tools und Persönlichkeit. In Claude Desktop öffnen Sie unter Einstellungen → Entwickler → Einstellungen bearbeiten die Datei claude_desktop_config.json, ergänzen den folgenden Inhalt, beenden die App vollständig (⌘Q) und starten sie neu. Tragen Sie in command das Ergebnis von which node ein (da die Umgebung von Claude Desktop sich vom Terminal unterscheidet, wird node möglicherweise nicht gefunden, wenn Sie nur node schreiben).

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

Um dasselbe mit einem einzigen Befehl zu tun (bestehende Einstellungen bleiben erhalten, .bak wird beibehalten):

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

Für die manuelle Registrierung in Claude Code gehen Sie wie folgt vor. Die Anmeldeinformationen werden aus .env gelesen, daher ist env nicht erforderlich.

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

Unterschiede je nach Installationsart

Es ist kein Unterschied zwischen Claude Code und Claude Desktop, sondern ein Unterschied der Installationsart. In beiden Apps können Sie dasselbe verwenden, wenn Sie es als Plugin installieren.

Related MCP server: pov

Architektur

Der MCP-Server ist eine dünne Brücke; der gesamte Zustand ist zentral auf der Electron-App-Seite gehalten. Selbst wenn mehrere Agenten gleichzeitig verbunden sind, bleibt der Zustand konsistent.

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 — port in ui-chan.config.json oder die Umgebungsvariable UI_CHAN_PORT

• Autostart — Die App wird bei Sitzungsbeginn (SessionStart-Hook) und bei jedem Tool-Aufruf wiederbelebt, falls sie beendet ist; VoiSona Talk wird beim MCP-Start und bei jedem set_cue wiederbelebt

• Agentenname — Wird automatisch aus den MCP-Client-Informationen ermittelt (überschreibbar mit UI_CHAN_AGENT_NAME)

Eine ausführlichere Implementierungsanleitung finden Sie in CLAUDE.md.

Befehlsübersicht

MCP-Tools (vom Agenten aufgerufen)

Die Cue-Liste wird vom persona-Prompt (und vom SessionStart-Hook) bei jedem Start aus cues/*.json generiert und an den Kontext des Agenten übergeben.

Slash-Befehle (bei Plugin-Installation)

npm-Skripte

Q&A

Nur wenn Sie den TypeScript-Code in src/ geändert haben. Da npm install über prepare einmal baut, müssen Sie direkt nach dem Klonen kein npm run build ausführen. Cues und ui-chan.config.json sind JSON und benötigen keinen Build (Cues werden beim Speichern sofort neu geladen).

Allerdings läuft der MCP-Server mit dem Code vom Sitzungsbeginn weiter. Auch nach einem erneuten Build wird die Änderung in dieser Sitzung nicht übernommen. Verbinden Sie den MCP daher neu oder öffnen Sie die Sitzung neu.

Führen Sie npm run doctor aus. Häufige Ursachen sind: VoiSona Talk ist nicht gestartet, es fehlen Anmeldeinformationen in .env, oder die REST-API ist in VoiSona nicht aktiviert.

Auch ohne Ton erscheint die Sprechblase, und die Lippenbewegung funktioniert anhand der Kana in reading. VoiSona wird bei jedem set_cue wiederbelebt (höchstens einmal alle 30 Sekunden) und wartet bis zu 20 Sekunden auf eine REST-Antwort. Die Ursache erscheint in den warnings von get_state. Details: docs/TTS.md.

Zuerst können Sie mit npm run app den Einzelstart versuchen, um das Problem einzugrenzen. Bei Plugin-Installation versucht der SessionStart-Hook den Start, sodass es normalerweise schon beim Öffnen einer Sitzung erscheint. Wenn keine PSD in assets/ liegt, wird ein Platzhalter angezeigt.

Erstellen Sie einfach eine Datei cues/<Name>.json – ohne Vererbung, vollständig eigenständig, und beim Speichern sofort neu geladen. Für eine visuelle Erstellung verwenden Sie npm run editor. Format und Layer-Angaben: docs/CUES_AND_CONFIG.md; die Schnellübersicht der PSD-Layernamen finden Sie in docs/CUES.md.

Das sind persona/ui-chan.md (Grundpersönlichkeit und Tool-Nutzungsrichtlinie) und context/*.md (SOUL.md Werte / VOCABULARY.md Wortschatz und verbotene Wörter / AFFINITY.md Zuneigung). Alle Markdown-Dateien in context/ werden in Dateinamensreihenfolge vollständig in den Agenten injiziert. Details: docs/PERSONA.md.

Mit minSec / maxSec (Standard 120–300 Sekunden) in idle.idlingCues von ui-chan.config.json stellen Sie den Abstand ein, mit dem weight jedes IdlingCue die Wahrscheinlichkeit. Über minAffinity / maxAffinity können Sie auch nach Zuneigungsgrad steuern.

Das ist eventCues.events in ui-chan.config.json. Für jedes Ereignis gibt es einen Pool von Sätzen; mit cooldownSec (geteilt durch Ereignisse mit demselben throttleKey) und chance passen Sie den Geräuschpegel an. Der Inhalt hat dieselbe Form wie IdlingCue, daher können weight / minAffinity / maxAffinity / hours verwendet werden.

Verfügbare Ereignisse: permission (Warten auf Erlaubnis), idle_wait (Warten auf Eingabe), tool_failure, turn_done, compact, agent_out (Sub-Agent aussenden), agent_back (Rückkehr).

Prüfen können Sie das mit event <Ereignisname> in npm run debug. Die Hook-Seite (hooks/) wirft nur den Ereignisnamen, daher müssen Sie für Satzänderungen kein JavaScript anfassen.

Ermitteln Sie mit npm run dump-psd -- path/to/file.psd die Layernamen und passen Sie ui-chan.config.json und cues/*.json (Basis: cues/default.json) an. Ersetzen Sie auf der Persönlichkeitsseite persona/ und context/ vollständig. Nicht vorhandene Layer-Pfade werden ignoriert und in den warnings von get_state gemeldet; während der Umstellung kommt es also nicht zum Absturz.

Die Zuneigung hat den Schwellenwert (65) noch nicht erreicht. Sie steigt durch Dankbarkeit, Fürsorge und dass man sich an sie erinnert. Unverblümte Zuneigungsbekundungen lassen sie eher sinken.

Dokumentation