Skip to main content
Glama

Storywright MCP

Cursor, Claude Desktop, OpenCode 또는 stdio를 통해 MCP를 지원하는 모든 호스트를 위한 다중 에이전트 도서 집필 MCP 서버입니다. 가드된 챕터 파이프라인(작가 → 편집자 → 구성 가능한 3차 검토 → 승인), 디스크상의 JSON/Markdown 프로젝트, 도서 바이블 계획, 연속성 추적, 원고 검색, 마커 스캔, 이전 챕터 컨텍스트 예산 관리, 내보내기/diff 도우미 기능을 결합했습니다.

골든 패스 (첫 1시간)

  1. 설치 (이 저장소에서):

    cd C:\Apps\claude_plugins\storywright-mcp
    uv sync --extra dev
  2. API 키 설정 (사용자 환경 변수 또는 MCP env 블록):

    • ANTHROPIC_API_KEY 및/또는 ANTHROPIC_AUTH_TOKEN — 작가/편집자/3차 검토 에이전트에 필요합니다 (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 (작업 중인 셸과 동일 — 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을 설정하거나, 디스크에 저장되는 위험을 감수할 경우에만 값을 일시적으로 포함하세요. book_projects/가 위치할 곳으로 **STORYWRIGHT_PROJECTS_ROOT**를 편집하세요.

    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

기능

  • 엄격한 워크플로우: 편집자 이후에만 3차 검토 가능; force=true가 아닌 경우 모든 구성된 3차 검토 에이전트의 승인이 필요합니다.

  • 파이프라인 힌트: get_pipeline_status는 챕터별 다음 도구 호출을 나열합니다.

  • API 준비 상태: check_environment는 세션을 소모하기 전에 Anthropic 자격 증명(ANTHROPIC_API_KEY 및/또는 ANTHROPIC_AUTH_TOKEN)을 검증합니다.

  • 이전 산문 예산: 작가는 구성 가능한 단어/챕터 제한까지 최근 승인된 챕터 텍스트를 포함합니다 (전체 도서를 덤프하는 것보다 컨텍스트 절약).

  • 재시도: 일시적인 Anthropic 오류(429/5xx, 타임아웃)는 백오프와 함께 재시도됩니다 (STORYWRIGHT_ANTHROPIC_MAX_RETRIES).

  • 구조화된 편집자 메타: 편집자 보고서는 ---STORYWRIGHT_META_START--- … END---로 끝나야 하며, 마크다운 보고서 옆에 JSON이 파싱됩니다.

  • 내보내기 / diff: export_manuscript, diff_chapter (초안 vs .prev.md).

  • 리소스: storywright://project/*, storywright://meta/version.

설치

cd storywright-mcp
uv sync --extra dev

환경 변수

변수

목적

ANTHROPIC_API_KEY

아래 Bearer를 사용하지 않는 경우 선택 사항 — 작가/편집자/3차 검토 호출

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를 사용하며, 이는 Claude Code와 동일한 방식으로 ANTHROPIC_BASE_URL 및 **ANTHROPIC_AUTH_TOKEN**을 읽습니다. ~/.claude/settings.json의 env를 Cursor(또는 셸)의 Storywright MCP env 블록에 미러링하세요. 예:

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

  • ANTHROPIC_AUTH_TOKEN = 귀하의 MiniMax 토큰 (Bearer)

  • STORYWRIGHT_ANTHROPIC_MODEL = MiniMax-M2.7 (또는 제공업체가 기대하는 모델 ID)

API 키를 커밋하지 마세요. OS 환경 변수나 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/채팅에서 사용)이며 셸 명령어가 아닙니다. 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**를 실행하세요 (자격 증명은 셸에만 유지됨):

$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**가 작동하는지 확인하세요 (토큰 비용 발생; 파일은 임시 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