# Storywright MCP

Multi-agent **book-writing MCP server** for Cursor, Claude Desktop, OpenCode, or any host that speaks MCP over **stdio**. It combines a guarded chapter pipeline (writer → editor → configurable third passes → approve), JSON/Markdown projects on disk, book-bible planning, continuity tracking, manuscript search, marker scans, **prior-chapter context budgeting**, and **export/diff** helpers.

## Golden path (first hour)

1. **Install** (from this repo):

   ```powershell
   cd C:\Apps\claude_plugins\storywright-mcp
   uv sync --extra dev
   ```

2. **Set API key** (User env or MCP `env` block):

   - `ANTHROPIC_API_KEY` **and/or** `ANTHROPIC_AUTH_TOKEN` — required for writer/editor/third-pass (MiniMax usually uses Bearer + `ANTHROPIC_BASE_URL`).

3. **Register MCP in Cursor** — create or edit **`mcp.json`**:

   | Scope | Path (Windows) |
   |-------|----------------|
   | **User (all workspaces)** | `%USERPROFILE%\.cursor\mcp.json` |
   | **This repo only** | `<repo>\.cursor\mcp.json` |

   Merge `storywright` into the existing `"mcpServers"` object if the file already has other servers.

   **Anthropic API key** (secrets via Windows env — set User env vars, then reference them):

   ```json
   {
     "mcpServers": {
       "storywright": {
         "command": "uv",
         "args": ["run", "--directory", "C:/Apps/claude_plugins/storywright-mcp", "storywright-mcp"],
         "env": {
           "ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}",
           "STORYWRIGHT_PROJECTS_ROOT": "C:/Users/you/Documents/writing",
           "STORYWRIGHT_ANTHROPIC_MODEL": "claude-sonnet-4-20250514"
         }
       }
     }
   }
   ```

   **MiniMax** (same as your working shell — Bearer + base URL + model):

   ```json
   {
     "mcpServers": {
       "storywright": {
         "command": "uv",
         "args": ["run", "--directory", "C:/Apps/claude_plugins/storywright-mcp", "storywright-mcp"],
         "env": {
           "ANTHROPIC_BASE_URL": "https://api.minimax.io/anthropic",
           "ANTHROPIC_AUTH_TOKEN": "${env:ANTHROPIC_AUTH_TOKEN}",
           "STORYWRIGHT_ANTHROPIC_MODEL": "MiniMax-M2.7",
           "STORYWRIGHT_PROJECTS_ROOT": "C:/Users/you/Documents/writing"
         }
       }
     }
   }
   ```

   Set `ANTHROPIC_AUTH_TOKEN` in **Windows Environment Variables** (User), or temporarily embed the value only if you accept the risk of it sitting on disk. Edit **`STORYWRIGHT_PROJECTS_ROOT`** to wherever you want `book_projects/` to live.

   **Reload MCP**: Command Palette → **“Cursor: Reload MCP Servers”** (or restart Cursor). `uv` must be on `PATH` for the terminal where Cursor spawns servers.

4. In chat, run tools in order:

   - `check_environment` — confirms key + model + version.
   - `create_book_project(project_name="my-novel", book_title="My Novel", third_agents=["comedy","pacing"])`
   - `plan_book()` … through phases (optional), or skip to chapters.
   - `add_chapter` / `add_character` as needed.
   - `get_pipeline_status` — shows **exact next tool** per chapter.
   - Per chapter: `start_chapter` → `run_writer_agent` → `run_editor_review` → each `run_third_agent` → `approve_chapter`.

5. **Artifacts to know**:

   - `briefs/revision_queue.json` — notes from `request_revision` (writer prompt reads these).
   - `reports/chapter-NN-editor-meta.json` — parsed verdict + meta block from editor.
   - `manuscript/chapter-NN-draft.prev.md` — backup before each writer overwrite; use `diff_chapter`.
   - `EXPORT-manuscript.md` — optional output from `export_manuscript`.

## Features

- **Strict workflow**: Third-pass only after editor; approve requires all configured third-pass agents unless `force=true`.
- **Pipeline hints**: `get_pipeline_status` lists the next tool call per chapter.
- **API readiness**: `check_environment` validates Anthropic credentials (`ANTHROPIC_API_KEY` and/or `ANTHROPIC_AUTH_TOKEN`) before you burn a session.
- **Prior prose budget**: Writer includes recent **approved** chapter text up to configurable word/chapter limits (saves context vs dumping the whole book).
- **Retries**: Transient Anthropic errors (429/5xx, timeouts) retry with backoff (`STORYWRIGHT_ANTHROPIC_MAX_RETRIES`).
- **Structured editor meta**: Editor reports should end with `---STORYWRIGHT_META_START---` … `END---`; parsed JSON beside the markdown report.
- **Export / diff**: `export_manuscript`, `diff_chapter` (draft vs `.prev.md`).
- **Resources**: `storywright://project/*`, `storywright://meta/version`.

## Install

```bash
cd storywright-mcp
uv sync --extra dev
```

## Environment

| Variable | Purpose |
|----------|---------|
| `ANTHROPIC_API_KEY` | Optional if using Bearer below — writer/editor/third-pass calls |
| `ANTHROPIC_AUTH_TOKEN` | Optional — Bearer token (same pattern as Claude Code; **MiniMax** often uses this instead of `API_KEY`) |
| `ANTHROPIC_BASE_URL` | Optional — e.g. `https://api.minimax.io/anthropic` for MiniMax’s Anthropic-compatible API |
| `STORYWRIGHT_ANTHROPIC_MODEL` | Model id (e.g. `MiniMax-M2.7` when using MiniMax) |
| `STORYWRIGHT_PROJECTS_ROOT` | Parent directory; projects go to `{root}/book_projects/<slug>/` |
| `STORYWRIGHT_STATE_DIR` | `last_project.json` for `load_last_book_project` (default `~/.storywright`) |
| `STORYWRIGHT_PRIOR_CHAPTERS_MAX_WORDS` | Max words of prior approved prose injected into writer (~default 12000) |
| `STORYWRIGHT_PRIOR_CHAPTERS_MAX_COUNT` | Max number of prior chapters considered (~default 8) |
| `STORYWRIGHT_ANTHROPIC_MAX_RETRIES` | Retries for transient API failures (~default 2) |
| `STORYWRIGHT_ANTHROPIC_RETRY_DELAY_SECONDS` | Base delay between retries (~default 2.0) |

### MiniMax (Anthropic-compatible gateway)

Storywright uses the official **`anthropic` Python SDK**, which reads **`ANTHROPIC_BASE_URL`** and **`ANTHROPIC_AUTH_TOKEN`** the same way as Claude Code. Mirror your `~/.claude/settings.json` `env` into the **Storywright MCP `env` block** in Cursor (or shell), for example:

- `ANTHROPIC_BASE_URL` = `https://api.minimax.io/anthropic`
- `ANTHROPIC_AUTH_TOKEN` = your MiniMax token (Bearer)
- `STORYWRIGHT_ANTHROPIC_MODEL` = `MiniMax-M2.7` (or whatever model id your provider expects)

Do **not** commit API keys; prefer OS env or Cursor secrets.

## Run (stdio)

```bash
uv run storywright-mcp
uv run python -m storywright_mcp
```

### Claude Desktop / OpenCode

Use the same `command` / `args` as Cursor if your app supports MCP stdio servers.

## Typical workflow

1. `create_book_project(..., third_agents=[...])` or `load_book_project("C:/absolute/.../book_projects/my-book")`
2. `plan_book()` … (optional)
3. `start_chapter(1)` → `run_writer_agent(1)` → `run_editor_review(1)` → `run_third_agent(1, …)` → `approve_chapter(1)`

Use **`get_pipeline_status`** whenever you lose track.

## CLI

```bash
uv run storywright-mcp agents           # list third-pass agents
uv run storywright-mcp smoke             # ping Anthropic/MiniMax (tiny token use)
uv run storywright-mcp smoke --with-book # temp folder + new project + chapter 1 writer (full pipeline chunk)
```

Names like `run_editor_review(1)` are **MCP tools** (used from Cursor/chat), not shell commands. From PowerShell you can call the same logic after `load_book_project`:

```powershell
uv run python -c "from storywright_mcp import workflow; workflow.load_book_project(r'C:/path/to/book_projects/your-book'); print(workflow.run_editor_review(1))"
```

### Test MiniMax (or any Anthropic-compatible proxy)

From PowerShell, set the same variables as in `~/.claude/settings.json`, then run **`smoke`** from the repo (credentials stay in your shell only):

```powershell
$env:ANTHROPIC_BASE_URL = "https://api.minimax.io/anthropic"
$env:ANTHROPIC_AUTH_TOKEN = "<your-token>"
$env:STORYWRIGHT_ANTHROPIC_MODEL = "MiniMax-M2.7"
cd C:\Apps\claude_plugins\storywright-mcp
uv run storywright-mcp smoke
```

If you see **`STORYWRIGHT_SMOKE_OK`** in the output, routing and auth work. Use **`smoke --with-book`** to confirm **`create_book_project` → `run_writer_agent`** against live inference (costs more tokens; files land under a temp `storywright-smoke-*` directory).

## CI

GitHub Actions runs `ruff` + `pytest` on push/PR (`.github/workflows/ci.yml`).

## License

MIT