Skip to main content
Glama

Storywright MCP

用于 Cursor、Claude Desktop、OpenCode 或任何支持通过 stdio 进行 MCP 通信的主机的多智能体 书籍写作 MCP 服务器。它结合了受保护的章节流水线(作者 → 编辑 → 可配置的第三方审核 → 批准)、磁盘上的 JSON/Markdown 项目、书籍大纲规划、连贯性追踪、手稿搜索、标记扫描、前序章节上下文预算以及 导出/差异对比 辅助工具。

黄金路径(第一小时)

  1. 安装(从本仓库):

    cd C:\Apps\claude_plugins\storywright-mcp
    uv sync --extra dev
  2. 设置 API 密钥(用户环境变量或 MCP env 块):

    • ANTHROPIC_API_KEY 和/或 ANTHROPIC_AUTH_TOKEN — 作者/编辑/第三方审核所需(MiniMax 通常使用 Bearer + ANTHROPIC_BASE_URL)。

  3. 在 Cursor 中注册 MCP — 创建或编辑 mcp.json:

    作用域

    路径 (Windows)

    用户 (所有工作区)

    %USERPROFILE%\.cursor\mcp.json

    仅此仓库

    <repo>\.cursor\mcp.json

    如果文件已包含其他服务器,请将 storywright 合并到现有的 "mcpServers" 对象中。

    Anthropic API 密钥(通过 Windows 环境变量设置密钥 — 设置用户环境变量,然后引用它们):

    {
      "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(与您的工作 shell 相同 — Bearer + 基础 URL + 模型):

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

    在 Windows 环境变量 (用户) 中设置 ANTHROPIC_AUTH_TOKEN,或者仅在您接受其存储在磁盘上的风险时才临时嵌入该值。将 STORYWRIGHT_PROJECTS_ROOT 编辑为您希望 book_projects/ 存放的任何位置。

    重新加载 MCP:命令面板 → “Cursor: Reload MCP Servers”(或重启 Cursor)。Cursor 启动服务器的终端必须在 PATH 中包含 uv。

  4. 在聊天中,按顺序运行工具:

    • check_environment — 确认密钥 + 模型 + 版本。

    • `create_book_project(project_name="my-novel", book_title="My Novel", third_agents=["comedy","pacing"])

    • plan_book() … 完成各阶段(可选),或直接跳至章节。

    • 根据需要 add_chapter / add_character。

    • get_pipeline_status — 显示每章的 确切下一个工具。

    • 每章操作:start_chapter → run_writer_agent → run_editor_review → 每个 run_third_agent → approve_chapter。

  5. 需要了解的制品:

    • briefs/revision_queue.json — 来自 request_revision 的备注(作者提示词会读取这些内容)。

    • reports/chapter-NN-editor-meta.json — 编辑解析后的结论 + 元数据块。

    • manuscript/chapter-NN-draft.prev.md — 每次作者覆盖前的备份;使用 diff_chapter。

    • EXPORT-manuscript.md — export_manuscript 的可选输出。

Related MCP server: Nyxdoc

功能

  • 严格的工作流:第三方审核仅在编辑之后进行;除非 force=true,否则批准需要所有配置的第三方智能体通过。

  • 流水线提示:get_pipeline_status 列出每章的下一个工具调用。

  • API 就绪检查:check_environment 在消耗会话额度前验证 Anthropic 凭据(ANTHROPIC_API_KEY 和/或 ANTHROPIC_AUTH_TOKEN)。

  • 前序正文预算:作者包含最近 已批准 的章节文本,直至可配置的字数/章节限制(相比转储整本书,节省了上下文)。

  • 重试机制:瞬态 Anthropic 错误(429/5xx,超时)会通过退避策略重试(STORYWRIGHT_ANTHROPIC_MAX_RETRIES)。

  • 结构化编辑元数据:编辑报告应以 ---STORYWRIGHT_META_START--- … END--- 结尾;Markdown 报告旁会解析出 JSON。

  • 导出 / 差异对比:export_manuscript,diff_chapter(草稿 vs .prev.md)。

  • 资源:storywright://project/*,storywright://meta/version。

安装

cd storywright-mcp
uv sync --extra dev

环境

变量

用途

ANTHROPIC_API_KEY

如果使用下方的 Bearer 则可选 — 作者/编辑/第三方审核调用

ANTHROPIC_AUTH_TOKEN

可选 — Bearer 令牌(与 Claude Code 模式相同;MiniMax 通常使用此项而非 API_KEY)

ANTHROPIC_BASE_URL

可选 — 例如 MiniMax 的 Anthropic 兼容 API:https://api.minimax.io/anthropic

STORYWRIGHT_ANTHROPIC_MODEL

模型 ID(例如使用 MiniMax 时的 MiniMax-M2.7)

STORYWRIGHT_PROJECTS_ROOT

父目录;项目存放于 {root}/book_projects/<slug>/

STORYWRIGHT_STATE_DIR

用于 load_last_book_project 的 last_project.json(默认 ~/.storywright)

STORYWRIGHT_PRIOR_CHAPTERS_MAX_WORDS

注入作者提示词的前序已批准正文的最大字数(默认约 12000)

STORYWRIGHT_PRIOR_CHAPTERS_MAX_COUNT

考虑的前序章节最大数量(默认约 8)

STORYWRIGHT_ANTHROPIC_MAX_RETRIES

瞬态 API 失败的重试次数(默认约 2)

STORYWRIGHT_ANTHROPIC_RETRY_DELAY_SECONDS

重试之间的基础延迟(默认约 2.0)

MiniMax (Anthropic 兼容网关)

Storywright 使用官方的 anthropic Python SDK,它读取 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 的方式与 Claude Code 相同。将您的 ~/.claude/settings.json 中的 env 镜像到 Cursor(或 shell)的 Storywright MCP env 块 中,例如:

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

  • ANTHROPIC_AUTH_TOKEN = 您的 MiniMax 令牌 (Bearer)

  • STORYWRIGHT_ANTHROPIC_MODEL = MiniMax-M2.7(或您的提供商期望的任何模型 ID)

请不要提交 API 密钥;优先使用操作系统环境变量或 Cursor 密钥。

运行 (stdio)

uv run storywright-mcp
uv run python -m storywright_mcp

Claude Desktop / OpenCode

如果您的应用程序支持 MCP stdio 服务器,请使用与 Cursor 相同的 command / args。

典型工作流

  1. create_book_project(..., third_agents=[...]) 或 load_book_project("C:/absolute/.../book_projects/my-book")

  2. plan_book() … (可选)

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

当您迷失方向时,请使用 get_pipeline_status。

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)

像 run_editor_review(1) 这样的名称是 MCP 工具(在 Cursor/聊天中使用),而不是 shell 命令。在 PowerShell 中,您可以在 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))"

测试 MiniMax (或任何 Anthropic 兼容代理)

在 PowerShell 中,设置与 ~/.claude/settings.json 中相同的变量,然后从仓库运行 smoke(凭据仅保留在您的 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

如果您在输出中看到 STORYWRIGHT_SMOKE_OK,则说明路由和身份验证工作正常。使用 smoke --with-book 来确认 create_book_project → run_writer_agent 是否针对实时推理有效(会消耗更多 Token;文件将存放在临时 storywright-smoke-* 目录下)。

CI

GitHub Actions 在推送/PR 时运行 ruff + pytest (.github/workflows/ci.yml)。

许可证

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