TT Agent Bridge

외부 CLI agent（ZCode / Claude Code 등）가 MCP를 통해 TauriTavern을 직접 조작할 수 있게 합니다: 런타임 데이터（채팅 / 변수 / 월드북 활성화 / 로그 / LLM 요청 원문 / iframe 상태 표시줄 러타임）를 읽고, 조작（STScript / 메시지 보내기 / 변수 쓰기 / 캐릭터 전환 / 월드북 항목 이동）을 실헹하며, 메인 문서 또는 메시지 iframe 안에서 임의 JS를 실헹해 Tavern 카드를 진단할 수 있습니다.

아키텍처

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

• 프로토콜 계약의 단일 진실 공급원: src/core/protocol.ts（bridge가 직접 import하며, 복사하지 말 것）.

• 확장은 공개 경계（TT 호스트 ABI + 업스트림 getContext() 공개 멤버）만 사용하며 내부 모듈을 건드리지 않습니다.

• bind-or-attach: MCP server가 시각될 때 포트에 같은 token의 살아있는 hub（daemon）가 이미 있으면 자동으로 agent로 attach합니다 — 여러 MCP 클라이언트가 동시에 실헹되어도 더 이상 포트 충돌이 없습니다.

Related MCP server: macOS Companion MCP Server

확장 설치（TauriTavern 내）

1. TauriTavern을 열고 → 상단의 '확장' 서랍 → 확장 관리 → 확장 설치

2. 이 저장소의 Git 주소를 입혁합니다（TauriTavern은 익명 https Git remote만 허용합니다）. 예: https://github.com/<你的用户名>/tt-agent-bridge.git

3. 설치 후 오른쪽 아래에 'Bridge' 상태 배지가 나탑니다（hello가 수락되면 초록색이 됩니다）.

수동으로 디렉터리를 두는 방법（data/extensions/third-party/tt-agent-bridge/）도 가능하지만, 이후 업데이트를 위해 Git 설치는 권장합니다. 업그레이드 주의: 프로토콜 버전은 저장소와 함께 진화합니다（현재 v2）. 확장과 bridge는 같은 저장소에서 함께 릴리스됩니다. 새 저장소를 당겨온 후 TT 내 확장도 함께 업데이트해야 합니다（Git 업데이트 또는 dist/ + manifest.json 동기화 후 페이지 리로드）. 그렇지 않으면 확장은 4003에 거부됩니다（배지 빨간색, 주기 재시도）.

시작

권장: 상주 daemon（확장이 장기 연결을 유지, 스크립트/MCP가 초 단위로 attach, 더 이상 매번 확장 재연결을 기다릴 필요 없음）:

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

또는 MCP server를 직접 실행（daemon이 없으면 자동 bind, daemon이 있으면 자동 attach）:

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

페어링 token

TT 오른쪽 아래 Bridge 배지를 클릭 → token（server 시작 로그의 token: ...）을 붙여넣고 → '재연결' 클릭 → 배지가 초록색이 되면 연결 성공입니다. token이 거부（4001）되면 확장은 30초 간 느린 재시도를 유지하며, token을 고치면 자동으로 회복됩니다.

agent（ZCode / Claude Code）에 연결

stdio MCP 방식으로 등록합니다（명령 예시는 클라이언트 문법에 맞게 조정하세요）:

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

MCP 도구 일람（21개）

감지류（읽기）

조작류（쓰기）

디버깅류

bridge 로컬

일반적인 debug 시나리오（Tavern 카드）

1. 상태 표시줄이 비어 있음 / 변수를 읽지 못함: tt_mvu_stat로 stat_data 존재 여부 확인 → tt_iframes로 상태 표시줄 frame 찾기 → tt_eval frame=TH-message--0--2로 iframe 안의 getAllVariables()와 DOM 확인 → tt_console_capture {enabled:true} 후 tt_logs kind=frontend로 오류 확인（SyntaxError는 대부분 HTML 엔터티가 이중 디코딩되어 발생）.

2. 상호작용 불가（tab이 클릭되지 않거나 / 버튼이 반응 없음）: tt_eval frame=...에서 스크립트 소스를 읽고, Vue 마운트（el.__vue_app__）를 확인하며, dispatchEvent로 클릭을 시뮬레이션해 대조 실험을 합니다.

3. 월드북이 적용되지 않음: tt_worldinfo_last로 활성화 배치 확인 → tt_llm_logs raw로 prompt에 실제로 무엇이 조립되었는지 확인 → tt_worldinfo_open으로 해당 항목으로 바로 이동.

4. 카드 수정 후 검증: tt_exec_stscript로 /go 리로드 트리거 → tt_read_messages로 렌더링 결과 확인.

5. 카드 구조 검토: tt_get_character section=regexes|scripts|character_book로 내장 구성 요소를 부분별로 읽어, 카드 전체의 MB급 JSON이 context에 넘치지 않도록 합니다.

dev 스크립트（bridge/scripts/）

보안 경계

• WS는 127.0.0.1만 리슨합니다; 핸드셰이크에 반드시 token이 필요합니다（--token / TTAB_TOKEN, 기본값은 임의 생생）.

• 임의 파일 시스템 / 명령 프록시는 제공하지 않습니다 — 파일 작업은 agent가 로컬 도구로 직접 수행합니다.

• 쓰기류와 tt_eval은 destructive로 표시되며, agent 측 확인 정책에 의존합니다.

• token은 확장 localStorage와 bridge의 .bridge-token에 평문으로 저장되며, 모두 로컬 파일입니다.

알려진 제한 사항

• /send 텡스트는 파이프 이스케이프로 전달되며, 극단 문자가 포함되면 tt_eval로 context를 직접 조작해 폴백합니다.

• set_variables scope=global은 /setvar scope=global의 객체 직렬화 동작에 의존합니다.

• attached 모드에서 tt_poll_events는 attach 이후의 이벤트만 포함합니다（과거 이벤트는 daemon의 ring buffer에 있으며, MCP attach 경로에서는 재생되지 않습니다）；tt_bridge_status의 extConneted는 attach 시점의 스냅샷입니다.

• TauriTavern의 context.characterId는 실측상 숫자 문자열입니다（업스트림 ST는 number）. bridge 내부는 이미 호환됩니다.

• daemon이 죽으면 attached인 MCP server 호출이 실패합니다（오류 메시지에 daemon 재시작이 명시적으로 안내됨）. bind로 자동 폴백하지 않습니다.

개발

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

저장소 트가 곧 확장입니다（manifest.json + dist/）. dist 빌드 산출물이 저장소에 함께 커밋되므로, TT Git 설치 후 바로 로드됩니다. 소스를 수정한 뒤 npm run build 후 커밋하면 TT의 확장 업데이트가 가져갈 수 있습니다.