# st-card-tools

MCP Server for reading and writing SillyTavern character cards and world books.

Designed for use with Claude Code to enable AI-assisted editing of character cards (PNG with embedded JSON) and world books (lorebooks).

## Installation

One command:

```bash
claude mcp add st-tools -e ST_ROOT=/path/to/SillyTavern -- npx -y st-card-tools
```

Replace `/path/to/SillyTavern` with your actual SillyTavern installation path.

That's it. Claude Code will automatically have access to all character card and world book editing tools.

## Tools

### Character Cards

| Tool | Description |
|------|-------------|
| `st_list_cards` | List all character card PNG files |
| `st_read_card` | Read full character card JSON from PNG |
| `st_write_card` | Write complete character card JSON to PNG |
| `st_read_card_field` | Read a specific field (dot notation, e.g. `data.description`) |
| `st_write_card_field` | Modify a specific field and save back to PNG |

### World Books

| Tool | Description |
|------|-------------|
| `st_list_worlds` | List all world book JSON files |
| `st_read_world` | Read world book entry summaries |
| `st_read_world_entry` | Read full content of a specific entry |
| `st_write_world_entry` | Create or update a world book entry |
| `st_delete_world_entry` | Delete a world book entry |

## Usage Examples

Once configured, you can ask Claude Code:

- "List all my character cards"
- "Read the description of 角色名.png"
- "Update the personality field of this character to be more tsundere"
- "Show me all entries in the 世界书.json world book"
- "Add a new entry about the magic system to the world book"

## Configuration

Uses environment variables (set via `claude mcp add -e`):

| Env Var | Description |
|---------|-------------|
| `ST_ROOT` | SillyTavern root directory. Auto-resolves `characters` and `worlds` paths |
| `ST_CARDS_DIR` | Override character cards directory |
| `ST_WORLDS_DIR` | Override world books directory |

Tool parameters accept either bare filenames (resolved against configured directories) or full absolute paths

## Supported Formats

- Character cards: PNG with embedded tEXt metadata (chara v2 / ccv3 v3)
- World books: SillyTavern JSON lorebook format

## License

MIT