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: creative-subagent-runner-mcp

기능

• 엄격한 워크플로우: 편집자 이후에만 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

환경 변수

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