ui-chan-mcp

Servidor para operar una mascota de escritorio a través de MCP (Model Context Protocol). Desde Claude Code o cualquier agente compatible con MCP, puedes cambiar a la vez el aspecto (cara + brazos) y la voz de la mascota, y hacerle decir líneas en un globo de diálogo.

• La capa de visualización es Electron (transparente, siempre al frente, esquina inferior derecha)

• El sprite usa PSD en formato PSDTool (!=capa obligatoria, *=conmutación de radio) tal cual

• El aspecto + voz se gestionan en unidades llamadas Cue (1 archivo = un aspecto + voz completos). La única herramienta de manipulación visual para agentes es set_cue

• Compatible con cola de habla y conexión simultánea de varios agentes

El PSD del sprite no está incluido en el repositorio (por ser material protegido por derechos de autor). Funcionará si colocas un PSD compatible con PSDTool en assets/. Si no hay, se inicia con un marcador de posición. El ui-chan.config.json incluido y cues/*.json están pensados para la estructura de capas del material de sprite de Ui (雨衣) (por Sakamoto Ahiru). Úsalo dentro del ámbito de las directrices del personaje Ui.

Configuración

→ Guía de configuración ilustrada (Desde la clonación hasta que aparece en pantalla. Está escrita con un nivel de detalle comprensible tanto para humanos como para IA. El mismo contenido también está en docs/setup-page.html)

Resumen para quienes tienen prisa:

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

Conectar

Con cualquier método de conexión, está completo en el momento de conectar. La aplicación de la mascota y VoiSona Talk se inician automáticamente al conectarse, y la personalidad se transfiere en el handshake de MCP (instructions). No hay que pegar ningún archivo de personalidad.

Instalarlo como plugin (común a Claude Code / Claude Desktop, recomendado)

El registro de plugins se comparte entre Claude Code y Claude Desktop. Si lo registras una vez en Claude Code, el mismo plugin aparece en «Configuración → Plugins» en el lado de Desktop (a la inversa, la interfaz de añadir de Desktop solo permite añadir desde GitHub; no se puede especificar una carpeta local).

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

Si se instala desde GitHub, especifica Uncle-Peke/ui-chan-mcp (aunque, como dist/ no está commiteado, se necesita una copia real clonada por separado y con npm install).

Al instalar el plugin, también se registra el conector (servidor MCP) (.mcp.json). No hace falta registrar el conector manualmente; si haces ambas cosas, el mismo servidor se iniciará dos veces.

Usar solo el servidor MCP (solo conector)

Para cuando no necesitas skills ni hooks y solo bastan las herramientas y la personalidad. En Claude Desktop, abre claude_desktop_config.json desde Configuración → Desarrollador → Editar configuración, añade lo siguiente, cierra la aplicación por completo (⌘Q) y vuelve a iniciarla. Pon en command el resultado de which node (el entorno de Claude Desktop es distinto del de la terminal, por lo que si escribes solo node puede que no lo encuentre).

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

Si quieres hacer lo mismo con un solo comando (se conserva la configuración existente y se deja un .bak):

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

Para registrarlo manualmente en Claude Code, sigue lo siguiente. Las credenciales se leen desde .env, así que no necesitas env.

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

Diferencias según el método de instalación

No es una diferencia entre Claude Code y Claude Desktop, sino una diferencia en cómo se instala. En cualquiera de las dos aplicaciones, si lo instalas como plugin podrás usar lo mismo.

Related MCP server: pov

Arquitectura

El servidor MCP es un puente delgado y todo el estado está centralizado en el lado de la aplicación Electron. Aunque varios agentes se conecten a la vez, el estado no diverge.

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

• Puerto — el port de ui-chan.config.json, o la variable de entorno UI_CHAN_PORT

• Inicio automático — la aplicación se reactiva si está caída al inicio de la sesión (hook SessionStart) y en cada llamada a una herramienta; VoiSona Talk, al arrancar MCP y cada vez que se llama a set_cue

• Nombre del agente — se obtiene automáticamente de la información del cliente MCP (se puede sobrescribir con UI_CHAN_AGENT_NAME)

Consulta la guía de implementación más detallada en CLAUDE.md.

Lista de comandos

Herramientas MCP (las llama el agente)

La lista de Cues se genera en cada inicio desde cues/*.json mediante el prompt persona (y el hook SessionStart) y se pasa al contexto del agente.

Comandos de barra (al instalar el plugin)

Scripts de npm

Q&A

Solo cuando hayas modificado el TypeScript de src/. npm install compila una vez en prepare, así que no hace falta ejecutar npm run build justo después de clonar. Los Cues y ui-chan.config.json son JSON, por lo que no necesitan compilación (los Cues se recargan en cuanto se guardan).

Sin embargo, el servidor MCP sigue ejecutándose con el código que tenía al inicio de la sesión. Aunque lo recompiles, no se reflejará en esa sesión, así que vuelve a conectar MCP o abre una sesión nueva.

Ejecuta npm run doctor. Las causas habituales son que VoiSona Talk no esté iniciado, que no haya credenciales en .env, o que la REST API no esté habilitada en VoiSona.

Incluso sin voz, el globo de diálogo aparece y la sincronización labial se mueve a partir de los kana de reading. VoiSona se reactiva en cada set_cue (como máximo una vez cada 30 segundos) y espera hasta 20 segundos a que la REST responda. El motivo aparece en warnings de get_state. Más detalles en docs/TTS.md.

Primero prueba a iniciarla sola con npm run app para aislar el problema. Con el plugin instalado, el hook SessionStart intenta iniciarla, así que normalmente basta con abrir la sesión para que aparezca. Si no hay un PSD en assets/, se muestra un marcador de posición.

Basta con crear un archivo cues/<名前>.json. Sin herencia y totalmente autocontenido; se recarga en cuanto lo guardas. Si quieres crearlo visualmente, npm run editor. El formato y la especificación de capas están en docs/CUES_AND_CONFIG.md, y la tabla rápida de nombres de capas del PSD en docs/CUES.md.

Son persona/ui-chan.md (personalidad base y política de uso de herramientas) y context/*.md (SOUL.md valores / VOCABULARY.md vocabulario y palabras prohibidas / AFFINITY.md afinidad). Todos los Markdown colocados en context/ se inyectan al agente en orden de nombre de archivo. Más detalles en docs/PERSONA.md.

El intervalo se ajusta con minSec / maxSec (por defecto 120–300 segundos) en idle.idlingCues de ui-chan.config.json, y la probabilidad de que aparezcan con el weight de cada IdlingCue. Con minAffinity / maxAffinity también puedes condicionarlos por nivel de afinidad.

Está en eventCues.events de ui-chan.config.json. Hay un conjunto de líneas por cada nombre de evento, y el nivel de ruido se ajusta con cooldownSec (compartido por eventos con el mismo throttleKey) y chance. Como el contenido tiene la misma forma que IdlingCue, se pueden usar weight / minAffinity / maxAffinity / hours.

Eventos disponibles: permission (esperando permiso), idle_wait (esperando entrada), tool_failure, turn_done, compact, agent_out (envío de subagente), agent_back (regreso).

Para comprobarlo, event <イベント名> en npm run debug. El lado del hook (hooks/) solo lanza el nombre del evento, así que no necesitas tocar JavaScript para cambiar las líneas.

Revisa los nombres de capa con npm run dump-psd -- path/to/file.psd y modifica ui-chan.config.json y cues/*.json (la base es cues/default.json). En cuanto a la personalidad, reemplaza por completo persona/ y context/. Las rutas de capa inexistentes se ignoran y aparecen en warnings de get_state, por lo que no se cae durante el reemplazo.

No has llegado al umbral de afinidad (65). Sube con agradecimiento, consideración y que recuerdes las cosas. Las expresiones de afecto demasiado directas más bien la bajan.

Documentación