# Silly Tavern MCP

`silly-tavern-mcp` provides the `st-mcp` command and `st.*` MCP tools for
controlling SillyTavern through agents.

It is intentionally shaped as a deep module:

```text
Agent
  -> MCP tools/resources
  -> StControlPlane
  -> SillyTavern HTTP endpoints, source tree, plugin folders, snapshots
```

The MCP interface stays small. The control plane owns CSRF handling, endpoint
selection, snapshot creation, and write confirmation.

## Scope

Version `0.11.0` covers the core Agent-control layer: characters, chats, worldbooks,
prompt/context assembly, chat metadata, regex/script injections, Quick Reply
scripts, extension/plugin adaptation, codebase indexing, and a runtime browser
bridge.

- Configuration location index: `st.config_locations`
- Runtime health: `st.doctor`
- Standard resource reads: `st.resource.read`
- Dry planning: `st.plan_change`
- Parsed server config control: `st.config.get`, `st.config.patch`
- Confirmed patches for character fields and worldbook data: `st.resource.patch`
- Character registry/chat discovery: `st.character.list`, `st.character.chats`
- Character core field inspection/control: `st.character.inspect`, `st.character.configure`
- Worldbook registry/file control: `st.worldbook.list`, `st.worldbook.inspect`, `st.worldbook.create_empty`, `st.worldbook.delete`
- Worldbook entry inspection/control: `st.worldbook.entries`, `st.worldbook.entry.configure`
- MVU settings and state inspection/control: `st.mvu.settings.get`, `st.mvu.settings.configure`, `st.mvu.entries`, `st.mvu.entry.set_enabled`, `st.mvu.chat_state.inspect`, `st.mvu.chat_state.patch`
- Snapshots and rollback: `st.snapshot`, `st.rollback`
- Extension install and enable/disable: `st.extension.install`, `st.extension.set_enabled`
- Extension registry and configuration: `st.extension.registry`, `st.extension.configure`
- Server plugin install: `st.plugin.install`
- Server plugin scaffold: `st.plugin.scaffold`
- Server plugin registry and flags: `st.plugin.registry`, `st.plugin.configure`
- Prompt/context inspection: `st.prompt.inspect`
- Prompt injection control: `st.prompt.set_injection`
- Regex script registry/control: `st.regex.registry`, `st.regex.configure`
- Global variable registry/control: `st.variables.registry`, `st.variables.set`
- Quick Reply script registry/control: `st.quick_reply.registry`, `st.quick_reply.configure`
- Chat metadata/context control: `st.chat.metadata.get`, `st.chat.metadata.patch`
- Chat transcript inspection/message control: `st.chat.inspect`, `st.chat.message.append`, `st.chat.message.edit`, `st.chat.message.delete`
- Chat worldbook binding: `st.chat.worldbook.bind`
- Current-chat Author's Note control: `st.chat.authors_note.set`
- Local chat variable control: `st.chat.variables.set`
- Persistent chat script injection control: `st.chat.script_inject.configure`
- Source read/write within scoped roots: `st.source.read`, `st.source.write`
- Controlled development commands: `st.dev.run`
- Runtime lifecycle through configured commands: `st.runtime.control`
- Runtime browser bridge install/read: `st.bridge.install`, `st.bridge.health`, `st.bridge.read`
- Static upstream ST codebase index: `st.index.refresh`, `st://index`, `st://index/markdown`
- Technical post-change read verification: `st.verify`

Product-specific protocols should build on top of this ST control layer rather
than being mixed into the ST MCP surface.

Non-core user preferences are intentionally excluded from the public MCP
interface. Do not add generic tools for themes, layout, UI preferences, or broad
user-settings patching; add semantic tools only when the field participates in
core roleplay execution, prompt/context assembly, scripting, plugins, or data
assets.

## Resource URIs

Supported first-pass resources:

```text
st://status
st://config
st://config/current
st://config/default
st://config/schema
st://characters
st://characters/{avatar}
st://characters/{avatar}/raw
st://chats/recent
st://chats/recent/metadata
st://worldbooks
st://worldbooks/{name}
st://extensions
st://plugins
st://regex
st://quick-replies
st://variables
st://snapshots
st://index
st://index/markdown
st://routes
st://prompt-pipeline
st://prompt/inspect
st://extension-registry
st://plugin-registry
st://data-layout
st://logs/server
st://source/package
```

## Codebase Index

The codebase index is generated from the target upstream SillyTavern source tree:

```sh
npm run index:upstream-st -- /absolute/path/to/SillyTavern ./docs
```

It captures server config keys, default user setting sections, backend routes,
static `getConfigValue` usages, data layout, and known prompt/extension/plugin
runtime seams. The index can mention user settings because ST stores core
prompt features there internally, but the public MCP protocol should expose
semantic core tools rather than generic user-setting patching.

## Configuration Location Index

`st.config_locations` is the first tool an agent should call when it needs to
understand where a setting actually lives. It maps user-facing domains to
storage and semantic tools:

```text
server_config       -> config.yaml
characters          -> default-user/characters plus /api/characters/*
worldbooks          -> default-user/worlds/*.json entries
chat_metadata       -> first record in chats/{avatar}/{file}.jsonl
mvu_global_settings -> extension_settings.mvu_settings
mvu_worldbook_entries -> worldbook entries with [InitVar], [mvu_update], [mvu_plot], stat_data macros, or variable-rule markers
mvu_chat_state      -> message.variables[].stat_data inside chat JSONL messages
```

This is the contract that keeps the MCP from being a pile of endpoint wrappers:
the agent can ask for the configuration map, then use the semantic tool for the
domain it found.

## Configuration Control

Use dotted paths only for server config needed by core runtime control:

```json
{
  "path": "enableServerPlugins"
}
```

Confirmed patches create a snapshot before writing:

```json
{
  "updates": {
    "enableServerPlugins": true
  },
  "confirm": true
}
```

`st.config.patch` writes `config.yaml` and returns `restartRequired: true`.

## Characters And Worldbooks

`st.character.list` lists existing imported character cards, and
`st.character.chats` lists chat files under one character avatar. These tools
are for Tavern management/discovery only; they do not create role cards.

`st.character.inspect` and `st.character.configure` expose character-card core
fields without making the agent understand PNG card internals or ST's mirrored
root/data fields. This is still management of an existing imported card, not a
card-authoring protocol.

Core editable fields:

```text
name
description
personality
scenario
first_mes
mes_example
system_prompt
post_history_instructions
alternate_greetings
```

Example:

```json
{
  "avatar": "default_Seraphina.png",
  "fields": {
    "scenario": "The forest sanctuary is quiet, but something watches from the old road.",
    "system_prompt": "Write {{char}} with warmth, restraint, and strong continuity."
  },
  "confirm": true
}
```

`st.worldbook.list` lists worldbook files. `st.worldbook.inspect` reads one
complete worldbook. `st.worldbook.create_empty` creates an empty shell, and
`st.worldbook.delete` removes a worldbook after a snapshot.

`st.worldbook.entries` lists one worldbook's entries.
`st.worldbook.entry.configure` creates, updates, enables/disables, or deletes
exactly one entry instead of forcing the agent to rewrite an entire worldbook.

Example:

```json
{
  "book": "Eldoria",
  "comment": "shadowfang tactics",
  "fields": {
    "key": ["shadowfang", "ambush"],
    "content": "Shadowfangs hunt by circling silently before the first strike.",
    "position": 0,
    "depth": 4,
    "order": 80
  },
  "enabled": true,
  "confirm": true
}
```

## MVU Configuration

MVU has three separate storage locations:

```text
Global MVU configuration:
  extension_settings.mvu_settings

MVU declaration/rule entries:
  worldbook entries, usually tagged [InitVar], [mvu_update], [mvu_plot],
  variable-rule text, or stat_data macros.

Runtime MVU variable values:
  chat messages, at message.variables[].stat_data and initialized_lorebooks.
```

Use `st.mvu.settings.get` and `st.mvu.settings.configure` for global MVU model
and auto-request settings. Use `st.mvu.entries` to find MVU-related worldbook
entries and `st.mvu.entry.set_enabled` to enable or disable exactly one entry.
Use `st.mvu.chat_state.inspect` to inspect runtime `stat_data` snapshots in a
chat, and `st.mvu.chat_state.patch` only when intentionally editing live MVU
state.

Example: find disabled MVU entries in a worldbook:

```json
{
  "book": "ONEPIECE mvu测试",
  "includeContent": false
}
```

Example: enable an `[InitVar]` entry:

```json
{
  "book": "ONEPIECE mvu测试",
  "uid": 0,
  "enabled": true,
  "confirm": true
}
```

## Extension And Plugin Registries

`st.extension.registry` joins frontend extension discovery with
`settings.extension_settings`, infers likely config keys, and reports enabled
state. `st.extension.configure` can enable/disable an extension and patch its
extension settings in one confirmed write.

`st.plugin.registry` reports installed server plugin manifests plus
`enableServerPlugins` and `enableServerPluginsAutoUpdate`. `st.plugin.configure`
patches those config flags and returns `restartRequired: true`.

## Prompt Inspection

`st.prompt.inspect` reads the static codebase index, live prompt-related ST
state, and optionally the runtime bridge snapshot. It is a read-only map of the
current prompt/context assembly surface; write tools should build on this
instead of exposing generic user settings.

## Prompt Injection Control

`st.prompt.set_injection` is the semantic write layer for ST prompt placement.
It translates agent-friendly fields into the current ST internal schema and then
uses a confirmed snapshot/write flow.

Supported targets:

```text
authors_note  -> extension_settings.note.default/defaultPosition/defaultDepth/defaultRole/defaultInterval/allowWIScan
persona       -> power_user.persona_description and persona_description_position/depth/role
world_info    -> world_info_settings depth/budget/budget_cap/recursive/matching flags
system_prompt -> power_user.sysprompt enabled/content/name/post_history
instruct      -> power_user.instruct enabled/preset plus relative updates
context       -> power_user.context.story_string and story_string_position/depth/role
```

Readable positions are normalized to ST enums. Extension prompt positions are
`none`, `in_prompt`, `in_chat`, and `before_prompt`; persona also supports
`top_an`, `bottom_an`, and `at_depth`. Roles are `system`, `user`, and
`assistant`.

Example:

```json
{
  "target": "persona",
  "text": "{{user}} is a tired detective with a hidden agenda.",
  "position": "at_depth",
  "depth": 2,
  "role": "system",
  "confirm": true
}
```

## Regex, Variables, And Quick Reply Scripts

`st.regex.registry` and `st.regex.configure` manage global ST regex scripts in
`extension_settings.regex`. The MCP tool accepts readable placements:
`user_input`, `ai_output`, `slash_command`, `world_info`, and `reasoning`, then
stores the numeric ST enum.

Example:

```json
{
  "name": "Normalize OOC brackets",
  "findRegex": "/\\((.*?)\\)/g",
  "replaceString": "[$1]",
  "placements": ["ai_output", "slash_command"],
  "enabled": true,
  "confirm": true
}
```

`st.variables.registry` and `st.variables.set` manage global slash/macro
variables stored at `extension_settings.variables.global`.

`st.quick_reply.registry` and `st.quick_reply.configure` manage the Quick Reply
V2 setting plus saved Quick Reply sets. Quick Replies are slash-command scripts:
the set is saved through `/api/quick-replies/save`, while global enable/active
set state is saved through `/api/settings/save`.

Example:

```json
{
  "enabled": true,
  "activeSet": "Agent",
  "set": "Agent",
  "reply": {
    "label": "Daily setup",
    "message": "/setvar key=scene_mode calm | /echo Ready"
  },
  "confirm": true
}
```

## Chat Metadata Control

Chat-level metadata is part of core context because ST stores current-chat
Author's Note overrides, local slash variables, selected chat world info, and
persistent `/inject` data in `chat_metadata`.

The chat tools require explicit `avatar` and `fileName`; they do not guess the
active browser chat:

```text
st.chat.inspect
st.chat.metadata.get
st.chat.metadata.patch
st.chat.worldbook.bind
st.chat.message.append
st.chat.message.edit
st.chat.message.delete
st.chat.authors_note.set
st.chat.variables.set
st.chat.script_inject.configure
```

`st.chat.inspect` returns the chat header, `chat_metadata`, and transcript
messages with zero-based message indexes. Message tools append, edit, or delete
caller-provided transcript messages; they do not generate roleplay content.
`st.chat.worldbook.bind` sets or unsets `chat_metadata.world_info`, which is the
native ST selected-chat worldbook key.

Example:

```json
{
  "avatar": "default_Seraphina.png",
  "fileName": "Seraphina - 2023-5-12 @21h 32m 29s 224ms",
  "text": "Keep the current scene grounded and intimate.",
  "position": "chat",
  "depth": 4,
  "role": "system",
  "confirm": true
}
```

## Setup

```sh
cd /path/to/st-mcp
npm install
npm run build
```

When the four sibling projects use the standard workspace layout, `st-mcp`
automatically targets `../tavern` and its embedded SillyTavern engine. Override
the paths below only for a different checkout layout.

Default runtime target:

```text
ST_MCP_BASE_URL=http://127.0.0.1:8000
```

Useful environment variables:

```text
ST_MCP_PROJECT_ROOT=/absolute/path/to/SillyTavern
ST_MCP_ST_ROOT=/absolute/path/to/SillyTavern
ST_MCP_CONFIG_PATH=/absolute/path/to/config.yaml
ST_MCP_USER_DATA_ROOT=/absolute/path/to/default-user
ST_MCP_SNAPSHOT_ROOT=/absolute/path/to/snapshots
ST_MCP_TIMEOUT_MS=30000
ST_MCP_RUNTIME_STATUS_CMD=...
ST_MCP_RUNTIME_START_CMD=...
ST_MCP_RUNTIME_STOP_CMD=...
ST_MCP_RUNTIME_RESTART_CMD=...
```

Runtime commands run from `ST_MCP_PROJECT_ROOT`. Mutating runtime actions require
`confirm: true`; `status` can run without confirmation.

## Runtime Bridge

`st.bridge.install` installs two matching pieces into the target ST source tree:

- `plugins/st-mcp-runtime-bridge`
- `public/scripts/extensions/third-party/st-mcp-runtime-bridge`

The frontend extension publishes sanitized browser runtime snapshots to the
server plugin. `st.bridge.read` then exposes that state to external Agents.

The bridge requires server plugins to be enabled and a browser reload after
installation.

## Client Config Example

```json
{
  "mcpServers": {
    "st-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/st-mcp/dist/server.js"],
      "env": {
        "ST_MCP_BASE_URL": "http://127.0.0.1:8000",
        "ST_MCP_PROJECT_ROOT": "/absolute/path/to/SillyTavern",
        "ST_MCP_ST_ROOT": "/absolute/path/to/SillyTavern",
        "ST_MCP_CONFIG_PATH": "/absolute/path/to/config.yaml",
        "ST_MCP_USER_DATA_ROOT": "/absolute/path/to/default-user"
      }
    }
  }
}
```

## Safety Model

Write operations require `confirm: true`. Confirmed writes create a snapshot
before changing ST state. Rollback also requires `confirm: true`.

The first version avoids direct mutation of user data when ST has an endpoint
for the operation. Direct filesystem control should be added only behind the
same snapshot and verification flow.

## License

MIT