mcp-writing

An MCP service for AI-assisted reasoning and editing on long-form fiction projects.

Designed to work with OpenClaw but compatible with any MCP-capable AI gateway.

Quick launch

For local stdio MCP clients, run the published package directly:

WRITING_SYNC_DIR=/path/to/sync-dir DB_PATH=./writing.db npx -y @hanna84/mcp-writing

The CLI wrapper defaults to stdio transport and adds the Node 22 SQLite flag automatically when needed.

VS Code extension

For VS Code-native setup flows (including prose styleguide setup), use:

• hannasdev/mcp-writing-vscode

What it does

Instead of feeding an entire manuscript to an AI and hoping it fits in the context window, mcp-writing builds a structured index from your scene files. The AI queries that index first — finding relevant characters, beats, and loglines — then loads only the specific prose it needs.

Current status:

• Core platform complete: Metadata-first analysis, SQLite-canonical structural and relationship metadata, compatibility sidecar maintenance, AI-assisted prose editing with confirmation + git history, review bundles, and Scrivener Direct extraction are all implemented.
• Recently completed: Human Input Forgiveness made selected request-boundary inputs more forgiving, clarified keyword metadata search boundaries, and recorded temp-fixture replay validation while preserving stable canonical IDs.
• Active development: No initiative is currently selected.
• Deferred backlog: OpenClaw integration, client-agnostic setup, divisions, and embeddings search.
• Ideas and open questions: tracked separately so future exploration does not distort the active roadmap.

Who it is for

• Novelists and writing teams working on long manuscripts with many scenes, characters, and continuity constraints.
• AI-assisted editing workflows where you want targeted context retrieval instead of full-manuscript prompting.
• Projects that need traceable, reversible edits with metadata that stays synchronized as drafts evolve.

Documentation

Breaking changes

describe_workflows surface redesign

describe_workflows now exposes an outcome-first, discovery-first workflow map. This was a breaking change if your prompts or automation depend on previous workflow IDs or ordering; the newer recommended_next_actions tier is additive and appears before the full catalogue.

Update integrations using this mapping:

• manuscript_exploration -> question_driven_discovery (or targeted_scene_reading when the task is prose inspection)
• prose_editing -> safe_scene_revision
• character_management -> character_understanding
• place_management -> place_understanding
• review_bundle -> review_preparation

New workflow IDs added:

• thread_understanding
• parity_recovery

Styleguide workflows are still available, but no longer positioned as part of the primary daily workflow surface.

find_scenes and get_arc response-shape standardization

find_scenes and get_arc now always return structured envelopes, including non-paginated calls.

• Envelope fields: results, total_count.
• Pagination fields are included when paging is active.
• warning / next_step are included when relevant.

If your integration previously handled raw arrays for non-paginated calls, update it to parse envelopes consistently.

Safe parsing pattern:

const parsed = JSON.parse(toolText);
if (parsed.ok === false) throw new Error(parsed.error?.message ?? "tool error");
const scenes = parsed.results ?? [];
const totalCount = parsed.total_count ?? scenes.length;
const warning = parsed.warning ?? null;
const nextStep = parsed.next_step ?? null;

get_character_sheet, get_place_sheet, list_scene_references, get_relationship_arc response-shape standardization

These metadata-read tools now return structured envelopes instead of flat objects or raw arrays.

• get_character_sheet and get_place_sheet: previously returned a flat object of field values; now return { results: [row], total_count: 1, next_step }.
• list_scene_references: previously returned { references, scene_id, project_id }; now returns { results, total_count, scene_id, project_id }.
• get_relationship_arc: previously returned a raw JSON array; now returns { results, total_count, from_character, to_character }.

Safe parsing pattern for sheet tools:

const parsed = JSON.parse(toolText);
if (parsed.ok === false) throw new Error(parsed.error?.message ?? "tool error");
const sheet = parsed.results?.[0] ?? {};
const nextStep = parsed.next_step ?? null;

Safe parsing pattern for list/arc tools:

const parsed = JSON.parse(toolText);
if (parsed.ok === false) throw new Error(parsed.error?.message ?? "tool error");
const items = parsed.results ?? [];
const totalCount = parsed.total_count ?? items.length;

Canonical IDs and forgiving inputs

Stable IDs remain the canonical identity for projects, chapters, scenes, characters, places, and relationship writes. When you already know the ID, pass it exactly.

Some request-boundary fields now accept unambiguous human-shaped inputs, such as scene titles, character names, place names, or case variants. Successful tools still write and return canonical IDs, with resolved_from details when the input was resolved from a non-canonical value. Ambiguous matches, near matches, or suggested-only values fail or return advisory suggestions without mutating canonical state.

Tags and Save the Cat beats remain freeform editorial vocabulary. find_scenes can match existing tag and beat casing variants, and metadata updates can suggest nearby existing vocabulary, but supplied tag and beat text is preserved unless you intentionally change it.

search_metadata is keyword/FTS metadata search over indexed titles, loglines, tags, characters, places, and versions. It is not semantic search and does not search prose text; use get_scene_prose after metadata search or structured filters identify likely scenes. Semantic/prose search remains deferred to the Embedding-Based Search backlog.

Usage scenarios

1) Continuity pass before sending chapters to beta readers

Goal: catch inconsistencies before sharing pages.

1. Run sync after your latest writing session.
2. Ask find_scenes for scenes involving a specific character or tag (for example, all scenes tagged injury or promise). Canonical IDs remain preferred, but character/POV filters can resolve unambiguous project-scoped character names, tag and beat filters can suggest near matches, and chapter_id accepts exact IDs or unambiguous case variants.
3. Use get_arc to review that character's ordered progression across the manuscript.
4. Load only the suspect scenes with get_scene_prose.
5. Attach follow-up notes with flag_scene where continuity needs a fix.

Outcome: you review one narrative thread at a time instead of rereading the entire novel to find contradictions.

2) Planning and tracking subplot beats during revisions

Goal: make sure subplot threads progress intentionally and resolve on time.

1. Run list_threads for the project.
2. Use get_thread_arc to inspect scene order and beat labels for each thread.
3. When a beat is missing, call track_thread_arc to add or update it on the right scene.
4. Re-run get_thread_arc to confirm pacing and coverage.

Outcome: subplot structure stays visible and auditable, which reduces dropped threads in late drafts.

3) Tightening scene metadata after heavy prose edits

Goal: keep indexes accurate without manually re-tagging everything.