TT Agent Bridge

Befähigt externe CLI-Agenten (ZCode / Claude Code usw.), über MCP direkt auf TauriTavern zuzugreifen: Laufzeitdaten lesen (Chat / Variablen / Weltbuch-Aktivierung / Logs / rohe LLM-Anfragen / Statusleisten-Runtime der iframes), Aktionen ausführen (STScript / Nachrichten senden / Variablen schreiben / Charakter wechseln / zu Weltbuch-Einträgen springen) sowie beliebiges JS zur Diagnose von Tavern-Karten im Hauptdokument oder im Nachrichten-iframe auszuführen.

Architektur

外部 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 / 变量 / 消息 / 事件

• Einzige Quelle der Wahrheit für den Protokollvertrag: src/core/protocol.ts (vom bridge direkt importiert, nicht kopieren).

• Die Erweiterung nutzt nur öffentliche Grenzen (TT-Host-ABI + öffentliche Mitglieder des upstream getContext()), fasst keine internen Module an.

• bind-or-attach: Wenn beim Start des MCP-Servers bereits ein lebender Hub (daemon) mit demselben Token auf dem Port läuft, hängt sich der Server automatisch als agent an – bei mehreren gleichzeitigen MCP-Clients gibt es keinen Portkonflikt mehr.

Related MCP server: macOS Companion MCP Server

Erweiterung installieren (in TauriTavern)

1. TauriTavern öffnen → oberes „Erweiterungen“-Drawer → Erweiterungen verwalten → Erweiterung installieren

2. Die Git-Adresse dieses Repositories eintragen (TauriTavern akzeptiert nur anonyme https-Git-Remotes), z. B.: https://github.com/<你的用户名>/tt-agent-bridge.git

3. Nach der Installation erscheint unten rechts das Statusabzeichen „Bridge“ (wird grün, sobald hello akzeptiert wurde)

Das manuelle Platzieren des Verzeichnisses (data/extensions/third-party/tt-agent-bridge/) ist ebenfalls möglich, aber die Git-Installation wird für spätere Updates empfohlen. Hinweis zum Upgrade: Die Protokollversion entwickelt sich mit dem Repository weiter (aktuell v2); Erweiterung und bridge werden im selben Repository gemeinsam veröffentlicht. Nach dem Ziehen des neuen Repositories muss auch die Erweiterung in TT aktualisiert werden (Git-Update oder dist/ + manifest.json synchronisieren und dann die Seite neu laden), sonst wird die Erweiterung mit 4003 abgelehnt (Abzeichen rot, periodische Wiederholung).

Start

Empfohlen: Dauerhaft laufender daemon (die Erweiterung hält eine Langzeitverbindung aufrecht, Skripte/MCP hängen sich in Sekundenschnelle an, nicht mehr jedes Mal auf die Wiederverbindung der Erweiterung warten):

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

Oder MCP server direkt ausführen (ohne daemon automatisch bind; mit daemon automatisch attach):

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

token-Paarung

Klicke auf das Bridge-Abzeichen unten rechts in TT → token einfügen (token: ... aus dem Server-Startprotokoll) → auf „Neu verbinden“ klicken → das Abzeichen wird grün, sobald die Verbindung erfolgreich ist. Wird der token abgelehnt (4001), unternimmt die Erweiterung 30 Sekunden lang langsame Wiederholungsversuche; sobald der token korrigiert ist, heilt sie sich selbst.

An agent anbinden (ZCode / Claude Code)

Per stdio MCP registrieren (Befehlsbeispiel, an die Syntax deines Clients anpassen):

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

MCP-Werkzeugübersicht (21)

Ermittlung (lesen)

Aktionen (schreiben)

Debugging

bridge-lokal

Typische Debug-Szenarien (Tavern-Karten)

1. Statusleiste leer / Variablen nicht lesbar: Mit tt_mvu_stat prüfen, ob stat_data existiert → mit tt_iframes die Statusleisten-frame finden → mit tt_eval frame=TH-message--0--2 in der iframe getAllVariables() und DOM prüfen → nach tt_console_capture {enabled:true} mit tt_logs kind=frontend die Fehler ansehen (SyntaxError ist meist auf doppelte Dekodierung von HTML-Entitäten zurückzuführen).

2. Interaktion defekt (Tab nicht klickbar / Button reagiert nicht): In tt_eval frame=... Skriptquellen lesen, Vue-Mount prüfen (el.__vue_app__), mit dispatchEvent Klicks simulieren für Kontrollexperimente.

3. Weltbuch wirkungslos: Mit tt_worldinfo_last die Aktivierungsrunde ansehen → mit tt_llm_logs raw prüfen, was tatsächlich in den Prompt eingebaut wurde → mit tt_worldinfo_open direkt zu diesem Eintrag springen.

4. Nach Kartenänderungen verifizieren: tt_exec_stscript löst /go-Reload aus → mit tt_read_messages das Rendering-Ergebnis prüfen.

5. Kartenstruktur überprüfen: Mit tt_get_character section=regexes|scripts|character_book eingebettete Komponenten abschnittsweise lesen, um zu vermeiden, dass die MB-große JSON der gesamten Karte den Kontext flutet.

Dev-Skripte (bridge/scripts/)

Sicherheitsgrenzen

• WS lauscht nur auf 127.0.0.1; der Handshake muss einen token enthalten (--token / TTAB_TOKEN, standardmäßig zufällig generiert).

• Kein Proxy für beliebige Dateisystem- oder Befehlszugriffe – für Dateioperationen nutzt der agent seine eigenen lokalen Werkzeuge.

• Schreiboperationen und tt_eval sind als destructive markiert; die Bestätigungsrichtlinie liegt bei der agent-Seite.

• Der token wird im Klartext in der localStorage der Erweiterung und in .bridge-token des bridges gespeichert; beides sind lokale Dateien.

Bekannte Einschränkungen

• /send-Text wird per Pipe-Escaping übertragen; bei extremen Zeichen greift als Fallback tt_eval, um direkt auf den context zuzugreifen.

• set_variables scope=global hängt vom Objekt-Serialisierungsverhalten von /setvar scope=global ab.

• Im attached-Modus enthält tt_poll_events nur Ereignisse nach dem attach (historische Ereignisse liegen im Ringbuffer des daemons und werden über den MCP-attach-Pfad nicht wiedergegeben); extConnected von tt_bridge_status ist eine Momentaufnahme zum Zeitpunkt des attach.

• context.characterId von TauriTavern ist in der Praxis ein numerischer String (bei upstream ST ist es eine number); der bridge ist intern bereits damit kompatibel.

• Wenn der daemon stirbt, schlagen Aufrufe des attached MCP-Servers fehl (die Fehlermeldung weist deutlich auf einen Neustart des daemons hin); ein automatischer Rückfall auf bind erfolgt nicht.

Entwicklung

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

Der Repository-Root ist die Erweiterung selbst (manifest.json + dist/); die dist-Build-Artefakte werden mit dem Repository committet und nach der TT-Git-Installation direkt geladen. Nach Quellcode-Änderungen genügt npm run build und ein Commit, damit TT die Änderungen über das Erweiterungsupdate ziehen kann.