Official operating guideUpdated July 14, 2026

BookWriter MCP,from first call to finished book.

BookWriter MCP is a stateful book-writing server with 20 tools for project setup, chapter drafting, exact prose updates, accepted-chapter revisions, and manuscript completion. This page is the human-readable companion to the instructions and operating guide delivered directly through MCP.

Connect BookWriterBrowse all tools
Server endpoint
https://www.bookwriter.vip/api/mcp/v1
20Total tools
14Book tools
6Idea tools

The fast answer

Three rules prevent most MCP writing failures.

Connected assistants receive a concise version of these rules during initialization and can read the full guide as an MCP resource. The public documentation gives authors and developers the same contract in a searchable format.

Pass the prose

A path is not content

If a chapter lives in a local file, the connected client must read it and pass the full text. BookWriter cannot fetch prose from a filename alone.

Keep sequence intact

Current advances. Earlier updates.

Accept the current chapter to move forward. Send full content for an earlier accepted chapter to replace it without moving the cursor.

Recover safely

Check status before retrying

A client can show a generic failure after a save succeeds. Read book status first so a retry does not duplicate work or create confusion.

Tool reference

All 20 tools, in working order.

Use the narrowest tool that matches the author’s intent. Read-only calls restore context; mutating calls create, edit, accept, extend, or finish book state.

Project and progress

Create a persistent book, find it again, and inspect the current writing position.

create_book
Steering WheelWrites book state

Create a persistent book with a title, word goal, and story setup.

Best for: Starting a new book after gathering its premise, ending, character arc, tone, boundaries, and time period.

Watch: Returns the run ID used by the other book tools and may consume plan capacity.
list_books
Steering WheelRead-only

List recent books and their current chapter positions.

Best for: Finding the correct project before resuming work.

Watch: Read-only; it does not select or change a book.
get_book_status
Steering WheelRead-only

Return the current chapter, accepted count, word goal, and finish or extension state.

Best for: Confirming where the cursor is and verifying a write after any ambiguous client response.

Watch: Read-only; pass a run ID or book ID when more than one project exists.
catch_me_up
Steering WheelRead-only

Summarize recent chapters, characters, and open story threads.

Best for: Restoring narrative context before continuing a long-running book.

Watch: Read-only; it does not create or save prose.
get_credit_status
Steering WheelRead-only

Show plan availability, book slots used, and the reset date.

Best for: Checking capacity before creating or extending a book.

Watch: Read-only; availability can change after a new book or paid extension.

Draft and refine

Create the current chapter, tune it, or replace its working draft before acceptance.

handoff
Steering WheelWrites book state

Draft the current chapter from an author opener, scene direction, or both.

Best for: The normal chapter-writing loop; author prose supplied as the opener is preserved.

Watch: Works on the current chapter. Prefer acceptance once the chapter reads well.
retry_handoff
Steering WheelWrites book state

Generate a different version of the current chapter from revised input.

Best for: A structurally wrong draft that needs a fresh attempt.

Watch: Use sparingly; sharpen or a targeted edit is usually better for smaller corrections.
sharpen
Steering WheelWrites book state

Polish the generated portion of the current draft with a lighter or stronger pass.

Best for: Tone, rhythm, and prose refinement without replacing the chapter.

Watch: It is unavailable when the draft no longer has a preserved author/generated boundary.
self_edit_chapter
Steering WheelWrites book state

Apply exact find-and-replace edits to the current working draft.

Best for: Small continuity, factual, or line-level corrections.

Watch: Edits the current unaccepted chapter only; each operation replaces the first exact match.
set_draft
Steering WheelWrites book state

Replace the entire working draft of the current chapter.

Best for: Pushing a fully corrected local chapter before accepting it.

Watch: Requires the complete replacement text and only changes the current unaccepted draft.
set_story_energy
Steering WheelWrites book state

Set or clear the book-wide tone and intensity direction used by later drafts.

Best for: Changing the standing energy once instead of repeating it in every chapter request.

Watch: Affects future handoffs and retries; it does not rewrite existing prose.

Accept, revise, and finish

Save chapters into the manuscript, correct earlier chapters, and close or extend the book.

accept_chapter
Steering WheelWrites book state

Accept the current chapter or replace an earlier accepted chapter with corrected text.

Best for: Advancing the book or synchronizing a revised local chapter with BookWriter.

Watch: An earlier chapter requires full content and does not move the current chapter cursor; a future chapter is rejected.
complete_book
Steering WheelWrites book state

Finish and lock a book that has reached its word goal.

Best for: Delivering the final manuscript once the author is ready to stop writing.

Watch: A finished book is locked against later chapter changes; check status first.
extend_book
Steering WheelWrites book state

Raise a book’s word goal so writing can continue.

Best for: Continuing beyond the current target before the book is completed.

Watch: If added capacity costs a book slot, quote first and apply only after the author confirms.

Free idea tools

Brainstorm book components before or alongside the persistent writing workflow.

outline_generator
Free accountRead-only

Turn a premise into a chapter-by-chapter outline.

Best for: Planning structure before creating a book.

Watch: Returns ideas; it does not create or change a persistent book.
character_builder
Free accountRead-only

Build a character profile with motivation, flaw, voice, and defining detail.

Best for: Developing a protagonist, antagonist, or supporting role.

Watch: Returns ideas; save selected details in the book setup or chapter direction.
title_generator
Free accountRead-only

Generate marketable title options from a premise and genre.

Best for: Early title exploration.

Watch: Returns suggestions and does not rename an existing book.
pitch_generator
Free accountRead-only

Create a logline and a compact back-cover blurb.

Best for: Testing the hook or preparing promotional copy.

Watch: Returns suggestions and does not update the book record.
first_paragraph
Free accountRead-only

Generate an opening-paragraph idea from a premise.

Best for: Breaking a blank page before the first handoff.

Watch: Returns an idea; pass chosen prose into the writing workflow yourself.
plot_hole_finder
Free accountRead-only

Identify logic gaps and suggest quick repairs from a supplied synopsis.

Best for: A continuity review before revising chapters.

Watch: It only evaluates the synopsis provided and does not modify the manuscript.

Canonical workflows

Use state, then write.

1

Start a new book

  1. 1Ask for the premise, ending, protagonist arc, tone reference, standing story energy, boundaries, and time period.
  2. 2Call get_credit_status, then create_book with the useful setup details.
  3. 3Keep the returned run_id and use it for every later call on that book.
2

Resume an existing book

  1. 1Call list_books instead of guessing an identifier.
  2. 2Call get_book_status to confirm the current chapter and accepted count.
  3. 3Call catch_me_up when the author needs story context before continuing.
3

Write and accept the current chapter

  1. 1Call handoff with the author’s opener, direction, or both—or pass complete external prose as accept_chapter content.
  2. 2Use sharpen for prose polish, self_edit_chapter for exact small fixes, or set_draft for a full working-draft replacement.
  3. 3Call accept_chapter at the current chapter index. A successful current-chapter acceptance advances the cursor.
4

Revise an accepted chapter

  1. 1Read the corrected chapter from the client workspace or collect the complete replacement text from the author.
  2. 2Call accept_chapter with the same runId, the earlier chapterIndex, and the full content; title is optional.
  3. 3Confirm updated: true. The current chapter cursor must remain unchanged.
5

Recover from an apparent failure

  1. 1Do not immediately repeat a mutating call after a client transport error or generic 500 display.
  2. 2Call get_book_status and compare the current chapter, accepted count, and word total with the expected result.
  3. 3Retry only if the status proves the original write did not land.
6

Finish or extend the book

  1. 1Call get_book_status and inspect whether the word goal has been reached.
  2. 2Use complete_book when the author is ready to lock the manuscript.
  3. 3Use extend_book before completion when the author wants to keep writing; obtain confirmation before spending another book slot.
Accepted chapters are editable

Correct chapter 48 without rewinding chapter 51.

Send the earlier index and the complete corrected prose. BookWriter replaces that chapter, recalculates manuscript totals, and leaves the current writing position untouched.

Full content is required
Title is optional
Returns updated: true
Cursor stays on the current chapter

Tool arguments

{
  "runId": "your-run-id",
  "chapterIndex": 48,
  "title": "Optional title",
  "content": "Full corrected text"
}

Success signal

{
  "accepted": true,
  "updated": true,
  "chapter_index": 48,
  "next_chapter": 51
}

Capabilities and limits

What the server will—and will not—do.

It can

  • Maintain persistent book and chapter state across supported clients.
  • Draft, polish, precisely edit, replace, accept, finish, and extend manuscripts.
  • Replace previously accepted prose while preserving the sequential cursor.
  • Report current progress so ambiguous writes can be verified safely.

It cannot

  • BookWriter cannot read a local file merely because its path is mentioned. The connected client must read the file and pass the prose in a content field.
  • An accept_chapter call without content requires a working draft already saved by handoff or set_draft.
  • A future chapter cannot be accepted out of order. Only the current chapter advances the cursor; an earlier accepted chapter can be replaced in place.
  • Small edit and draft-replacement tools operate on the current unaccepted chapter. Use accept_chapter with full content for an earlier accepted chapter.
Once complete_book locks a manuscript, chapter writes and revisions are no longer allowed.
Read-only status calls can confirm state. They do not select a book, save prose, or repair a failed write.

Errors and recovery

Trust the stored state, not a red client bubble.

Treat a generic client error as ambiguous until book status proves the mutation failed. This is especially important for long chapters: retrying a successful write wastes time and can make the author think the manuscript diverged.

The client displays “500” or “tool call failed” after a write

Call get_book_status before retrying. Some clients can reject or misread a valid response after the server has already saved the chapter.

Chapter is out of order

Call get_book_status. Use the returned current chapter, or pass full content for an earlier accepted chapter correction.

Chapter content is empty

Read the source file in the client and pass its full text as content, or create a working draft first.

Chapter is intentionally short

Review the text, then call accept_chapter with allowShortChapter: true only when the author wants to keep it short.

Book is locked

The manuscript has been completed and cannot be changed through chapter tools.

Requests are arriving too quickly

Wait briefly and retry once; avoid parallel mutations against the same book.

Questions, answered

BookWriter MCP FAQ

What is the BookWriter MCP server?

BookWriter MCP is a stateful book-writing server that gives compatible assistants 20 tools for creating books, drafting chapters, preserving project context, revising accepted prose, and finishing manuscripts. The book state lives in BookWriter, so the same project can continue across supported MCP clients.

Can an assistant update a chapter after it has been accepted?

Yes. Call accept_chapter with the book’s runId, the earlier chapterIndex, and the full corrected content. BookWriter replaces that accepted chapter and returns updated: true without changing the current chapter cursor.

Why can a tool show a 500 even when the chapter was saved?

A connected client can occasionally fail while validating or displaying the tool response after BookWriter has completed the write. Call get_book_status before retrying; the current chapter and accepted count reveal whether the save already landed.

Can BookWriter read a chapter from a local file path?

No. The connected assistant or coding client must read the file, then pass its full text to set_draft or accept_chapter. A file name or path alone is not chapter content.

Which tool should be used for chapter corrections?

Use self_edit_chapter for small exact edits to the current draft, set_draft for a complete current-draft replacement, and accept_chapter with full content for an already accepted chapter.

Does revising an accepted chapter change the next chapter?

No. Replacing an earlier accepted chapter updates the stored prose and word totals in place. The book remains positioned at the same current chapter.

Ready to write

Connect once. Keep the whole manuscript in sync.

Use the same persistent BookWriter project from Claude, ChatGPT, Cursor, or another compatible client.

Open connection page Read the writing guide

Canonical URL: https://www.bookwriter.vip/mcp/guide