Skip to main content
Glama

Storywright MCP

Servidor MCP de escritura de libros multi-agente para Cursor, Claude Desktop, OpenCode o cualquier host que utilice MCP sobre stdio. Combina un flujo de trabajo de capítulos supervisado (escritor → editor → terceras revisiones configurables → aprobación), proyectos en JSON/Markdown en disco, planificación de la "biblia" del libro, seguimiento de continuidad, búsqueda en el manuscrito, escaneo de marcadores, presupuesto de contexto de capítulos anteriores y herramientas de exportación/diferencias.

Camino ideal (primera hora)

  1. Instalar (desde este repositorio):

    cd C:\Apps\claude_plugins\storywright-mcp
    uv sync --extra dev
  2. Configurar la clave API (Variable de entorno de usuario o bloque env de MCP):

    • ANTHROPIC_API_KEY y/o ANTHROPIC_AUTH_TOKEN — requerido para el escritor/editor/tercera revisión (MiniMax suele usar Bearer + ANTHROPIC_BASE_URL).

  3. Registrar MCP en Cursor — crear o editar mcp.json:

    Ámbito

    Ruta (Windows)

    Usuario (todos los espacios de trabajo)

    %USERPROFILE%\.cursor\mcp.json

    Solo este repositorio

    <repo>\.cursor\mcp.json

    Fusiona storywright en el objeto "mcpServers" existente si el archivo ya tiene otros servidores.

    Clave API de Anthropic (secretos mediante variables de entorno de Windows — configura las variables de usuario y luego haz referencia a ellas):

    {
      "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 (igual que tu shell de trabajo — Bearer + URL base + modelo):

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

    Configura ANTHROPIC_AUTH_TOKEN en las Variables de entorno de Windows (Usuario), o incrusta temporalmente el valor solo si aceptas el riesgo de que permanezca en el disco. Edita STORYWRIGHT_PROJECTS_ROOT a la ubicación donde quieras que residan los book_projects/.

    Recargar MCP: Paleta de comandos → “Cursor: Reload MCP Servers” (o reinicia Cursor). uv debe estar en el PATH de la terminal donde Cursor inicia los servidores.

  4. En el chat, ejecuta las herramientas en orden:

    • check_environment — confirma la clave, el modelo y la versión.

    • `create_book_project(project_name="mi-novela", book_title="Mi Novela", third_agents=["comedia","ritmo"])

    • plan_book() … a través de las fases (opcional), o salta directamente a los capítulos.

    • add_chapter / add_character según sea necesario.

    • get_pipeline_status — muestra la siguiente herramienta exacta por capítulo.

    • Por capítulo: start_chapter → run_writer_agent → run_editor_review → cada run_third_agent → approve_chapter.

  5. Artefactos a conocer:

    • briefs/revision_queue.json — notas de request_revision (el prompt del escritor las lee).

    • reports/chapter-NN-editor-meta.json — veredicto analizado + bloque meta del editor.

    • manuscript/chapter-NN-draft.prev.md — copia de seguridad antes de cada sobrescritura del escritor; usa diff_chapter.

    • EXPORT-manuscript.md — salida opcional de export_manuscript.

Related MCP server: Nyxdoc

Características

  • Flujo de trabajo estricto: La tercera revisión solo ocurre después del editor; la aprobación requiere todos los agentes de tercera revisión configurados a menos que force=true.

  • Sugerencias de flujo: get_pipeline_status enumera la siguiente llamada a herramienta por capítulo.

  • Preparación para API: check_environment valida las credenciales de Anthropic (ANTHROPIC_API_KEY y/o ANTHROPIC_AUTH_TOKEN) antes de consumir una sesión.

  • Presupuesto de prosa anterior: El escritor incluye texto de capítulos aprobados recientes hasta límites configurables de palabras/capítulos (ahorra contexto en comparación con volcar todo el libro).

  • Reintentos: Los errores transitorios de Anthropic (429/5xx, tiempos de espera) se reintentan con retroceso exponencial (STORYWRIGHT_ANTHROPIC_MAX_RETRIES).

  • Meta del editor estructurada: Los informes del editor deben terminar con ---STORYWRIGHT_META_START--- … END---; JSON analizado junto al informe en markdown.

  • Exportación / diferencias: export_manuscript, diff_chapter (borrador vs .prev.md).

  • Recursos: storywright://project/*, storywright://meta/version.

Instalación

cd storywright-mcp
uv sync --extra dev

Entorno

Variable

Propósito

ANTHROPIC_API_KEY

Opcional si se usa Bearer a continuación — llamadas de escritor/editor/tercera revisión

ANTHROPIC_AUTH_TOKEN

Opcional — token Bearer (mismo patrón que Claude Code; MiniMax a menudo usa esto en lugar de API_KEY)

ANTHROPIC_BASE_URL

Opcional — ej. https://api.minimax.io/anthropic para la API compatible con Anthropic de MiniMax

STORYWRIGHT_ANTHROPIC_MODEL

ID del modelo (ej. MiniMax-M2.7 al usar MiniMax)

STORYWRIGHT_PROJECTS_ROOT

Directorio principal; los proyectos van a {root}/book_projects/<slug>/

STORYWRIGHT_STATE_DIR

last_project.json para load_last_book_project (por defecto ~/.storywright)

STORYWRIGHT_PRIOR_CHAPTERS_MAX_WORDS

Máximo de palabras de prosa aprobada anterior inyectada en el escritor (~por defecto 12000)

STORYWRIGHT_PRIOR_CHAPTERS_MAX_COUNT

Número máximo de capítulos anteriores considerados (~por defecto 8)

STORYWRIGHT_ANTHROPIC_MAX_RETRIES

Reintentos para fallos transitorios de API (~por defecto 2)

STORYWRIGHT_ANTHROPIC_RETRY_DELAY_SECONDS

Retraso base entre reintentos (~por defecto 2.0)

MiniMax (puerta de enlace compatible con Anthropic)

Storywright utiliza el SDK oficial de Python anthropic, que lee ANTHROPIC_BASE_URL y ANTHROPIC_AUTH_TOKEN de la misma manera que Claude Code. Refleja tu env de ~/.claude/settings.json en el bloque env de Storywright MCP en Cursor (o shell), por ejemplo:

  • ANTHROPIC_BASE_URL = https://api.minimax.io/anthropic

  • ANTHROPIC_AUTH_TOKEN = tu token de MiniMax (Bearer)

  • STORYWRIGHT_ANTHROPIC_MODEL = MiniMax-M2.7 (o cualquier ID de modelo que espere tu proveedor)

No confirmes claves API; prefiere variables de entorno del SO o secretos de Cursor.

Ejecución (stdio)

uv run storywright-mcp
uv run python -m storywright_mcp

Claude Desktop / OpenCode

Usa el mismo command / args que Cursor si tu aplicación admite servidores MCP stdio.

Flujo de trabajo típico

  1. create_book_project(..., third_agents=[...]) o load_book_project("C:/absolute/.../book_projects/mi-libro")

  2. plan_book() … (opcional)

  3. start_chapter(1) → run_writer_agent(1) → run_editor_review(1) → run_third_agent(1, …) → approve_chapter(1)

Usa get_pipeline_status siempre que pierdas el hilo.

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)

Nombres como run_editor_review(1) son herramientas MCP (usadas desde Cursor/chat), no comandos de shell. Desde PowerShell puedes llamar a la misma lógica después de 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))"

Probar MiniMax (o cualquier proxy compatible con Anthropic)

Desde PowerShell, configura las mismas variables que en ~/.claude/settings.json, luego ejecuta smoke desde el repositorio (las credenciales permanecen solo en tu shell):

$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

Si ves STORYWRIGHT_SMOKE_OK en la salida, el enrutamiento y la autenticación funcionan. Usa smoke --with-book para confirmar create_book_project → run_writer_agent contra la inferencia en vivo (cuesta más tokens; los archivos se guardan en un directorio temporal storywright-smoke-*).

CI

GitHub Actions ejecuta ruff + pytest en push/PR (.github/workflows/ci.yml).

Licencia

MIT

Available Tools

35 tools
add_chapterC

Register a chapter outline.

Inputs: chapter_num (required), title (required), target_words. Returns: result

add_characterC

Add a character and continuity entry.

Inputs: name (required), role (required), description, voice_notes, +1 more. Returns: result

add_deathC

Schedule a canonical death.

Inputs: character (required), chapter (required), circumstances (required), death_style. Returns: result

add_established_factD

Inputs: fact (required), chapter (required), source. Returns: result

add_inventory_itemD

Track an inventory item.

Inputs: name (required), initial_holder (required), description, acquired_chapter. Returns: result

add_locationD

Inputs: chapter (required), location (required), description. Returns: result

add_running_gagD

Register a running gag.

Inputs: name (required), owner (required), setup_chapter (required), description, +1 more. Returns: result

approve_chapterA

Approve chapter; updates continuity. Requires all configured third passes unless force=true.

Inputs: chapter_num (required), force. Returns: result

check_environmentA

Verify ANTHROPIC_API_KEY and show model / prior-chapter budget / Storywright version.

Inputs: no named parameters. Returns: result

create_book_projectC

Create a new book project under book_projects/ (or STORYWRIGHT_PROJECTS_ROOT). Loads the new project.

Inputs: project_name (required), book_title (required), genre, authors, +2 more. Returns: result

diff_chapterC

Diff current draft vs .prev.md snapshot from last writer overwrite.

Inputs: chapter_num (required), max_lines. Returns: result

export_manuscriptC

Concatenate approved chapters into one markdown file at project root.

Inputs: output_filename. Returns: result

fire_gagD

Inputs: gag_name (required), chapter (required). Returns: result

get_book_bibleD

Readable bible markdown.

Inputs: no named parameters. Returns: result

get_chapter_statusC

Inspect one chapter.

Inputs: chapter_num (required). Returns: result

get_continuity_logC

JSON continuity log.

Inputs: no named parameters. Returns: result

get_inventoryD

Inputs: no named parameters. Returns: result

get_living_charactersD

Inputs: no named parameters. Returns: result

get_pipeline_statusB

Next MCP tool to call per chapter (guarded pipeline hints).

Inputs: no named parameters. Returns: result

get_project_statusB

Markdown table of chapters, statuses, editor verdicts, third-pass completion.

Inputs: no named parameters. Returns: result

get_running_gagsD

Inputs: no named parameters. Returns: result

list_third_agentsA

List built-in third-pass agents.

Inputs: no named parameters. Returns: result

load_book_projectB

Load an existing project from disk (prefer absolute paths).

Inputs: project_path (required). Returns: result

load_last_book_projectA

Load the last successfully opened project from ~/.storywright/last_project.json if valid.

Inputs: no named parameters. Returns: result

mark_character_deadD

Inputs: character_name (required), chapter (required), cause (required). Returns: result

plan_bookC

Phased book bible planning (identity→…→tone); completes with sync to project config.

Inputs: phase, data, reset, status. Returns: result

request_revisionC

Send chapter back to writer with notes.

Inputs: chapter_num (required), notes (required). Returns: result

run_editor_reviewC

Editor pass after writer.

Inputs: chapter_num (required). Returns: result

run_third_agentB

Third-pass reviewer (comedy, pacing, …). Repeat until all project.third_agents covered.

Inputs: chapter_num (required), agent_type. Returns: result

run_writer_agentA

Draft chapter via Claude (DRAW → AWAITING_EDITOR). Requires ANTHROPIC_API_KEY.

Inputs: chapter_num (required), chapter_brief. Returns: result

scan_manuscript_markersA

Find TODO/FIXME/DRAFT/TBD/XXX markers in manuscript markdown.

Inputs: no named parameters. Returns: result

search_manuscriptC

Substring search across manuscript/*.md.

Inputs: query (required), file_glob. Returns: result

start_chapterB

Open drafting for a chapter (NOT_STARTED → DRAFT).

Inputs: chapter_num (required). Returns: result

transfer_itemD

Inputs: item_name (required), new_holder (required), chapter (required). Returns: result

update_planC

Patch book_bible.json; may sync characters/deaths/gags into project.

Inputs: section, changes. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2/5.0

    Scored across 35 tools

    Disambiguation2/5

    Many tool descriptions are blank or minimal (e.g., add_location, fire_gag, get_inventory), and several tools have overlapping purposes (e.g., add_death vs mark_character_dead, add_running_gag vs fire_gag). This makes it difficult for an agent to distinguish between tools.

    Naming Consistency3/5

    Tool names follow a verb_noun pattern but use a wide variety of verbs (add, approve, check, create, diff, export, fire, get, list, load, mark, plan, request, run, scan, search, start, transfer, update). This variety, while not chaotic, lacks a strong consistent theme.

    Tool Count2/5

    35 tools is far above the recommended range of 3-15 for a well-scoped set, and significantly exceeds the 25+ threshold. The high count suggests over-specialization or redundant functionality.

    Completeness3/5

    The tool set covers many aspects of story writing (chapters, characters, inventory, gags, planning, etc.) but lacks basic CRUD operations such as delete or update for most resources, and has redundant tools (e.g., add_death and mark_character_dead). Some obvious gaps in lifecycle management are present.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A local MCP server for maintaining internal consistency in fiction writing, with constraint-based fact checking, branching, and author-oracle conflict resolution.
      27
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for Nyxdoc, a document system where humans and external agents collaborate on documents with version history, agent to-dos, and workspace permissions.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that lets multiple AI coding agents share state, preserve context across sessions, and coordinate via a knowledge graph, messaging, and branch-preserving checkpoint/resume with conflict handling.
      76 npm
      1
      Apache 2.0