# SillyTavern MCP Server

A read-only [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes a SillyTavern user directory (characters, personas, chat-completion presets, lorebooks, chats) to general-purpose agent clients — Claude Desktop, Raycast, BoltAI, etc.

See [`docs/MVP.md`](docs/MVP.md) for the full design spec: architecture, handle scheme, envelope format, and tool inventory.

## Status

The full MVP tool inventory (§6) is implemented and end-to-end tested over real stdio:

- **Characters** — `list-characters`, `get-character`
- **Personas** — `list-personas`, `get-persona`
- **Presets** — `list-presets`, `get-preset`, `export-preset`
- **Lorebooks** — `list-lorebooks`, `get-lorebook`, `search-lorebook`
- **Chats (the ladder)** — `list-chats` → `get-chat-manifest` → `get-chat-summaries` → `search-chat` → `get-messages` → `export-chat`

Remaining work is the explicitly-deferred post-MVP backlog ([`docs/MVP.md` §8](docs/MVP.md#8-deferred-with-rationale)) — track it via `bd` (this repo's issue tracker — run `bd ready` / `bd list`).

## Project layout

```
packages/core/          pure library — no MCP awareness
  fs/                   the ONLY module that touches the filesystem (reads + export writes)
  resolve/               user-dir resolution, startup validation, handles, name resolution
  parse/                 one parser per surface (cards, chats, lorebooks, presets, personas, summaries)
  render/                 transcript assembly, preset outline/full, token estimates, prefix stripping
packages/mcp/            stdio MCP adapter — envelope, tool registration, one file per tool group
packages/cli/            st-mcp CLI — npx entrypoint + `doctor` subcommand
docs/MVP.md              design spec
```

## Getting started locally

```bash
npm install
npm run build
node packages/cli/dist/bin.js --user-dir /path/to/SillyTavern/data/default-user
```

`--user-dir` is optional — see [`docs/MVP.md` §3](docs/MVP.md#3-configuration-and-path-resolution) for the full resolution order (flag > `SILLYTAVERN_USER_DIR` env var > `~/.config/st-mcp/config.json` > platform-default guesses). The server refuses to start and lists every path it tried if none resolve to a valid SillyTavern user directory.

To check your user-dir without starting the server:

```bash
node packages/cli/dist/bin.js doctor --user-dir /path/to/SillyTavern/data/default-user
```

## Running tests

```bash
npm test
```

## Learn more

- [MCP specification](https://spec.modelcontextprotocol.io/)
- [TypeScript SDK documentation](https://github.com/modelcontextprotocol/typescript-sdk)