Novel Workspace MCP

English · 中文 · 日本語

From a single idea to a complete long-form novel.

Novel Workspace MCP is a production-oriented AI writing workspace for long-form fiction. It keeps world-building, characters, chapter plans, timelines, facts, foreshadowing, context, and revisions in one auditable project state.

Three ways to use it

1. Local web studio — a focused browser workspace for planning, drafting, reviewing, and exporting.

2. MCP server — a tool surface for LM Studio, Claude Desktop, Codex, and other MCP clients.

3. Codex Skill — install skills/novel-workspace/ and invoke $novel-workspace for state-aware writing workflows. Source and package installs can locate it with novel-workspace skill-path.

Related MCP server: story-architect-mcp

Model backends

Use a local LM Studio server by default, or connect to any OpenAI-compatible API. Set NOVEL_LLM_PROVIDER=local or api in a private .env file. API keys never belong in source code, screenshots, or Git history.

The web studio defaults to English. Use the Language menu in the sidebar to switch to Chinese or Japanese; the preference is stored only in your browser. Release notes are maintained in English in CHANGELOG.md.

Source checkouts keep runtime data under the repository for portable local development. Package installations use the operating system's user data directory. Set NOVEL_WORKSPACE_HOME to choose an explicit location; model credentials remain in environment variables or a private .env file.

novel-workspace config --json produces a support-friendly report with paths and provider settings while exposing only whether secrets are configured. novel-workspace backup creates CRC-verified, atomic archives for every novel project; add --novel NAME to select one project.

What it does

Batch planning and reports (v2.13)

Select foreshadows, preview per-record changes, then atomically reschedule, resolve, reopen, reprioritize, or retag the whole selection. Every selected revision is checked; one conflict cancels the batch. Ownership filters and quick views help separate author plans from automatic tracking.

Export all filtered matches as JSON or Markdown, with notes/evidence opt-in and explicit completeness limits. The same engine is available through novel-workspace foreshadows list|export|batch, two new MCP tools, and the bundled Skill. No model calls or chapter rewrites are required. See batch workflow, CLI examples, and report limits.

Foreshadow planner (v2.12)

Open Timeline → Foreshadow planner to plant, edit, reschedule, resolve, cancel, or reopen a foreshadow. Use due-window, status, priority, tag, and text filters; inspect payoff deadlines, evidence, and the last 50 changes. The planner supports English, Chinese, and Japanese and can copy the visible page as JSON.

Manual creation or editing makes a record author-managed: derived-state rebuilds preserve it, and automatic summaries no longer resolve it. New automatic resolutions require one exact ID or text match, never a substring guess. MCP exposes get_foreshadow_board, create_foreshadow, and update_foreshadow with optional revision checks. See lifecycle rules and examples.

Manuscript diagnostics workbench (v2.11)

Open Dashboard → Manuscript diagnostics for chapter inventory, length trends, optional length targets, estimated reading time, missing/empty chapters, filename conflicts, and exact cross-chapter repeated paragraphs with chapter/line evidence. Filter an inclusive chapter range and download JSON or Markdown. The controls support English, Chinese, and Japanese; structured findings and exported reports are English.

The same read-only engine is available through MCP inspect_manuscript(start_chapter=1, end_chapter=20) and novel-workspace inspect --novel NAME --json. It makes no model calls and never rewrites chapters or stored word counts. Excerpts are off by default. See diagnostic metrics, limits, and CLI examples.

Inspectable project backups (v2.10)

Click Project backups beside the global search button to create a backup, browse existing ZIPs, verify integrity, or download a copy. New controls support English, Chinese, and Japanese. Verification is read-only and never overwrites a novel. Use Import novel / project to restore a downloaded archive as a separate project.

For scripts, use novel-workspace backup --list --novel NAME --json or novel-workspace backup --verify FILENAME --json. Both accept --output-dir to inspect a custom backup directory; filenames must belong to that directory, not arbitrary filesystem paths. Verification checks CRC, paths, and a JSON-object state.json, and reports SHA-256. Limits are 10,000 entries, 1 GB expanded, and 2 MB for project state. A passing result is not proof of authorship, narrative completeness, or a full restore rehearsal. Inventory alone does not imply successful verification.

NPC and character relationships

Open Characters → Character relationships to inspect directed connections, strength scores (-100 to 100), and expandable chapter evidence. Filter by a focal character, role (including NPC), or an inclusive chapter cutoff. NPC filters also show connected characters; a chapter cutoff respects the configured appearance range of registered characters.

MCP provides the same view through get_character_network(chapter=10, role_tier="NPC"); add character="Bob" to focus on one NPC. Each filter is optional and combined filters intersect. Current profile metadata is not a historical roster snapshot. Undated relationship prose is shown only in the latest view, and unresolved descriptions remain notes, not invented people. Observations do not substitute for author approval.

Example legacy descriptions: friend: Bob, Cara: mentor or 朋友：小明，阿青：导师. Names must match existing profiles. Recorded chapter relationships take precedence over undated profile descriptions for the same directed pair.

• Guided novel creation: premise, world, rules, style, outline, volumes, opening plan, and characters.

• Chapter pipeline: brief → plan → draft → quality gate → summary → continuity handoff.

• Long-form continuity: facts, timeline, character arcs, foreshadowing, causal checks, canonical locks, and travel rules.

• Safe editing: working drafts, savepoints, diffs, recovery, imports, exports, and transactional history revision.

• Persistent background jobs with resumable logs and strict single-concurrency model access.

Quick start

Style preset browser (v2.8)

Open Story bible → Style presets to browse built-in and project-specific presets, preview the full instructions, and append them to or replace the style editor. These actions do not save automatically: review your edits, then click Save story bible. Replacing non-empty editor content asks for confirmation. The controls support English, Chinese, and Japanese; preset content keeps its original language.

MCP clients can use get_style_preset(name, source="custom", include_rendered=True) to retrieve the same Markdown preview as the web studio. source accepts auto, builtin, or custom; explicit sources never silently fall back. With auto, prefer_custom=True prioritizes a custom preset. Create project-specific presets with the existing save_style_preset tool.

Product preview

▶ Watch the 11-second product trailer (MP4) · 90-second demo storyboard

See the lightweight demo storyboard and the community launch checklist.

uv sync
uv run novel-workspace doctor
uv run novel-workspace config
uv run novel-workspace serve

Open http://127.0.0.1:8765. For the MCP server:

uv run novel-workspace mcp

See .env.example for local/API configuration and the Chinese README for the complete tool catalog.

For Docker or one-click startup, use docker compose up --build or scripts/start.ps1 / scripts/start.sh. Tagged releases are also published to ghcr.io/lizh132707/novel-workspace-mcp.

docker run --rm -p 127.0.0.1:8765:8765 \
  -e NOVEL_LLM_PROVIDER=api \
  -e NOVEL_LLM_BASE_URL=http://host.docker.internal:1234/v1 \
  -v novel_workspace_storage:/app/storage \
  ghcr.io/lizh132707/novel-workspace-mcp:latest

Secure remote access

The CLI and Docker Compose bind the Web Studio to loopback by default. Before publishing it on a LAN or through a reverse proxy, set a random NOVEL_WEB_ACCESS_TOKEN of at least 16 characters. Browsers use HTTP Basic authentication (novel as the username and the token as the password); API clients may send Authorization: Bearer <token> or X-Novel-Workspace-Token. /healthz and /readyz remain public for probes.

Cross-origin access is disabled by default. If a separate frontend needs it, set NOVEL_WEB_CORS_ORIGINS to an exact comma-separated allowlist such as https://studio.example.com; wildcard origins are rejected. Docker Compose can be deliberately exposed with NOVEL_WEB_BIND_ADDRESS=0.0.0.0 after access protection is configured.

Create on-demand archives without adding runtime data to Git:

uv run novel-workspace backup --json
uv run novel-workspace backup --novel MyNovel --output-dir /safe/backups

The release workflow builds wheel and source distributions and attaches them to GitHub Releases. PyPI Trusted Publishing is available as an explicit maintainer action after the PyPI project is linked to this repository.

Development

python -m pip install -e ".[dev]"
pytest -q

CI validates Python 3.10 and 3.12, the CLI doctor, frontend JavaScript syntax, and the full Python and frontend regression suites.

Project status

The repository is intentionally data-free for public development. Runtime storage, logs, model assets, and local secrets are ignored by Git. Contributions, issue reports, and new provider adapters are welcome; see CONTRIBUTING.md and SECURITY.md.

License

MIT © LiZh132707