TT Agent Bridge

Permite que agentes CLI externos (ZCode / Claude Code, etc.) operen directamente sobre TauriTavern a través de MCP: leer datos de runtime (chat / variables / activación de world info / logs / payload sin procesar de las peticiones LLM / runtime de la barra de estado en iframe), ejecutar acciones (STScript / enviar mensajes / escribir variables / cambiar de personaje / saltar a entradas de world info) y ejecutar JS arbitrario en el documento principal o dentro del iframe de mensajes para diagnosticar tarjetas de tavern.

Arquitectura

外部 Agent（ZCode / Claude Code）           dev 脚本（tteval / ttdiag / regress）
      ↕  MCP over stdio                           ↕  agent 角色直连（ws + JSON）
bridge server（Node，仅监听 127.0.0.1，token 鉴权，支持常驻 daemon）
      ↕  WebSocket（扩展/agent 主动连出，多 agent 并存）
TauriTavern 扩展「TT Agent Bridge」
      ├─→ window.__TAURITAVERN__.api   检测：日志 / 世界书激活 / LLM 请求 / 聊天搜索 / console 捕获
      └─→ SillyTavern.getContext()     操作：STScript / 变量 / 消息 / 事件

• Fuente única de verdad del contrato del protocolo: src/core/protocol.ts (el bridge lo importa directamente; no copiar).

• La extensión solo usa los límites públicos (ABI del host TT + miembros públicos de getContext() de upstream), sin tocar módulos internos.

• bind-or-attach: cuando el servidor MCP arranca, si ya hay un hub (daemon) vivo con el mismo token en el puerto, se monta automáticamente como agente: los clientes MCP concurrentes ya no provocan conflictos de puerto.

Related MCP server: macOS Companion MCP Server

Instalación de la extensión (dentro de TauriTavern)

1. Abre TauriTavern → panel «Extensiones» de la parte superior → Gestionar extensiones → Instalar extensión

2. Introduce la URL Git de este repositorio (TauriTavern solo acepta remotes Git https anónimos), por ejemplo: https://github.com/<你的用户名>/tt-agent-bridge.git

3. Tras la instalación, aparece una insignia de estado «Bridge» en la esquina inferior derecha (se pone verde cuando el hello es aceptado)

También se puede colocar el directorio manualmente (data/extensions/third-party/tt-agent-bridge/), pero se recomienda la instalación por Git para poder actualizarlo después. Aviso de actualización: la versión del protocolo evoluciona con el repositorio (actualmente v2); la extensión y el bridge se publican juntos desde el mismo repositorio. Tras traer el repositorio nuevo, hay que actualizar también la extensión dentro de TT (actualización por Git o sincronizar dist/ + manifest.json y recargar la página); de lo contrario, la extensión será rechazada con 4003 (insignia roja, reintentos periódicos).

Arranque

Recomendado: daemon residente (la extensión mantiene una conexión persistente; los scripts/MCP se montan en segundos, sin esperar cada vez a que la extensión se reconecte):

cd bridge
npm install
npm run daemon -- --port 18789 --token <你的token>   # 或 TTAB_PORT / TTAB_TOKEN 环境变量

O ejecutar directamente el servidor MCP (bind automático si no hay daemon; attach automático si lo hay):

npm run start                          # 随机 token，打印在 stderr，并写入 .bridge-token
# 或固定 token：
npm run start -- --port 18789 --token <你的token>

Token de emparejamiento

Haz clic en la insignia Bridge de la esquina inferior derecha de TT → pega el token (el token: ... del log de arranque del server) → pulsa «Reconectar» → cuando la insignia se pone verde, la conexión se ha establecido. Si el token es rechazado (4001), la extensión reintenta lentamente durante 30 segundos y se recupera sola una vez corregido el token.

Montar en un agent (ZCode / Claude Code)

Registro mediante MCP stdio (comando de ejemploo; ajústalo a la sintaxis de tu cliiente):

zcode mcp add tt-agent-bridge -- npm run start --prefix <bridge目录绝对路径>

Lista de herramientas MCP (21)

Clase de detección (lectura)

Clase de operación (escritura)

Clase de depuración

bridge local

Escenarios típicos de depuración (tarjetas de tavern)

1. Barra de estado en blanco / no se leen variables: tt_mvu_stat para ver si existe stat_data → tt_iframes para localizar el frame de la barra de estado → tt_eval frame=TH-message--0--2 para inspeccionar getAllVariables() y el DOM dentro del iframe → tras tt_console_capture {enabled:true}, usa tt_logs kind=frontend para ver el error (SyntaxError suele deberse a la doble decodificación de entidades HTML).

2. Interacción rota (las pestañas no responden al clic / los botones no reaccionan): dentro de tt_eval frame=..., lee el código fuente del script, comprueba el montaje de Vue (el.__vue_app__) y lanza dispatchEvent para simular clics en un experimento comparativo.

3. World info sin efecto: tt_worldinfo_last para ver el lote de activación → tt_llm_logs en raw para ver qué se llegó a ensamblar en el prompt → tt_worldinfo_open para saltar directamente a esa entrada.

4. Verificación tras modificar la tarjeta: tt_exec_stscript dispara /go para recargar → tt_read_messages para comprobar el resultado renderizado.

5. Revisión de la estructura de la tarjeta: tt_get_character section=regexes|scripts|character_book lee los componentes integrados por secciones, evitando inundar el contexto con el JSON de varios MB de toda la tarjeta.

Scripts de desarrollo (bridge/scripts/)

Límites de seguridad

• WS solo escucha en 127.0.0.1; el handshake debe incluir el token (--token / TTAB_TOKEN, generado aleatoriamente por defecto).

• No actúa como proxy de sistema de archivos / comandos arbitrarios: las operaciones con archivos las realiza el agent con sus propias herramientas locales.

• Las operaciones de escritura y tt_eval están marcadas como destructive; dependen de la política de confirmación del lado del agent.

• El token se almacena en texto plano en el localStorage de la extensión y en .bridge-token del bridge; ambos son archivos locales de la máquina.

Limitaciones conocidas

• El texto de /send se transmite escapado a través de la tubería; si contiene caracteres extremos, se usa tt_eval para operar sobre el context directamente como respaldo.

• set_variables scope=global depende del comportamiento de serialización de objetos de /setvar scope=global.

• En modo attached, tt_poll_events solo contiene eventos posteriores al attach (los eventos históricos están en el ring buffer del daemon y no se reproducen por la ruta de attach vía MCP); extConnected de tt_bridge_status es una instantánea del momento del attach.

• El context.characterId de TauriTavern resulta ser en la práctica una cadena numérica (en el ST de upstream es number); el bridge ya lo maneja de forma compatible internamente.

• Si el daemon muere, las llamadas del servidor MCP attached fallan (el mensaje de error indica claramente reiniciar el daemon); no se vuelve automáticamente a bind.

Desarrollo

npm install && npm run build     # 构建扩展（typecheck + vite -> dist/）
cd bridge && npm install         # bridge 依赖
cd bridge && npm run typecheck   # bridge 侧类型检查

La raíz del repositorio es la propia extensión (manifest.json + dist/); los artefactos de build de dist se suben junto con el repositorio, de modo que tras la instalación por Git, TT la carga directamente. Tras modificar el código fuente, basta con npm run build y hacer commit para que la actualización de extensiones de TT lo recoja.