Storywright MCP

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):

   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):

   {
     "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):

   {
     "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

cd storywright-mcp
uv sync --extra dev

Environment

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)

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

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:

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):

$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