StoryForge: MCP Tools
Reference of all 95 tools of the StoryForge MCP server, grouped by task, with parameters and purpose. Explains the GateResult format of the checker tools.
StoryForge: MCP Tools
Deutsche Version
← Back to overview
The MCP server storyforge-mcp provides 95 tools. They are defined in the modules under servers/storyforge-server/routers/. The skills call them themselves, you do not have to invoke them by hand. A question mark after a parameter means: optional.
Book, author and series state (status, rules, canon, session, cache) goes through these tools. Skills write the prose itself directly with Claude Code's file tools (Write, Edit), for example chapter-writer into draft.md and export-engineer into the export files. That is why the hooks check every such change.
Books and chapters
| Tool |
Purpose |
list_books() |
All book projects with status and word count |
find_book(query) |
Find a book by slug or title (partial match) |
get_book_full(slug) |
Complete book data including chapters and characters |
get_book_progress(slug) |
Chapter statuses, word counts, completion |
list_chapters(book_slug) |
All chapters with status and word count |
count_words(book_slug, chapter_slug?) |
Words of one chapter or the whole book |
create_book_structure(title, author?, genres?, book_type?, book_category?, language?, target_word_count?, series_slug?) |
New book project with directory scaffold; author is always written to the README frontmatter; with series_slug a slug collision with an already existing book of the same slug elsewhere (standalone or another series volume) is rejected |
create_chapter(book_slug, title, number, pov_character?, summary?) |
New chapter directory with README and empty draft; for fiction it also creates the chapter writer's raw draft copy |
create_character(book_slug, name, role?, description?) |
New character file (fiction) |
start_chapter_draft(book_slug, chapter_slug) |
Mark a chapter as being drafted |
Briefs before writing and checking
| Tool |
Purpose |
get_chapter_writing_brief(book_slug, chapter_slug) |
Bundled JSON for chapter-writer (story anchor, timelines, characters, rules, tone rules, callbacks, banlist, tactics) |
get_review_brief(book_slug, chapter_slug) |
Data basis for chapter-reviewer |
get_continuity_brief(book_slug) |
Full book state for continuity-checker |
get_canon_brief(book_slug, chapter_slug, pov_character?, scope_chapters?) |
Bounded canon excerpt for a chapter |
get_current_story_anchor(book_slug, chapter_slug?) |
Story-time anchor and mapping of relative time phrases |
get_recent_chapter_timelines(book_slug, n?) |
Intra-day time grids of the last N chapters |
verify_tactical_setup(book_slug, scene_outline_text, characters_present) |
Check of combat and travel scenes (walking order) |
register_chapter_promises(book_slug, chapter_slug, promises) |
Store a chapter's setup elements |
get_chapter_promises(book_slug, chapter_slug) |
Read a chapter's stored promises |
add_canon_fact(book_slug, chapter_num, subject, fact, book_num?, domain?, is_revision?, old_value?, revision_impacts?) |
Store a canon fact in the database |
Quality checks
Most of these tools return a uniform result (see below). The exceptions are scan_chapter_ai_tells and check_replacement_text.
| Tool |
Purpose |
validate_chapter(book_slug, chapter_slug) |
The same rules as the prose hook, as a tool |
scan_manuscript(book_slug, min_occurrences?, write_report?, max_findings_per_category?) |
Cross-chapter scan for repetition and prose patterns |
validate_timeline_consistency(book_slug) |
Time drift between chapters against plot/timeline.md |
verify_callbacks(book_slug) |
Callback register against all drafted chapters |
analyze_plot_logic(book_slug, scope?, chapter_slug?) |
Plot-hole detection (see Technical details) |
check_memoir_consent(book_slug) |
Consent status of all people in the memoir |
validate_book_structure(book_slug) |
Completeness of the project structure |
run_pre_export_gates(book_slug) |
Pre-export check |
run_quality_gates(book_slug) |
Run all checkers and aggregate |
scan_chapter_ai_tells(book_slug, chapter_slug, author_slug?, em_dash_per_1k_limit?) |
Deterministic pre-scan for AI constructions, used by chapter-humanizer (own result format, no GateResult) |
check_replacement_text(book_slug, text, author_slug?) |
Checks a proposed replacement against the humanizer patterns (own result format, no GateResult) |
The GateResult
The checker tools other than scan_chapter_ai_tells and check_replacement_text return their result under the key gate, next to their tool-specific fields. The envelope contains a status of PASS, WARN or FAIL, plus reasons, findings and metadata. run_pre_export_gates additionally carries the older verdict field (READY or BLOCKED) at the top level, repeated in gate.metadata. It also carries the list of individual gates.
The global catalog behind scan_chapter_ai_tells and check_replacement_text only applies to books written in English; for any other book language both return a warning and no catalog hits. Banned patterns from plot/tone.md are checked alongside it, with bullet points that have no backticks showing up only as an advisory. See Technical Details for more.
Review feedback and draft states
These tools log verified review decisions and keep track of draft states for fiction chapters. They are called by chapter-voice-harvest and the other checker skills, you do not have to invoke them by hand.
| Tool |
Purpose |
log_review_feedback(book_slug, chapter_slug, source_skill, decision, comment_text?, before_text?, after_text?, proposal_text?, dimension?, direction?, normalized_rule?) |
Log one verified piece of feedback (source_skill: writer, reviewer, fixer, rewriter, humanizer, proofreader or self_edit; decision: accepted, reworked, rejected or self_edit); duplicates are ignored; memoir books never store raw text, classification and rule are required |
list_pending_feedback(book_slug, chapter_slug?) |
The author's open entries, including from earlier chapters and books |
set_feedback_classification(book_slug, feedback_id, dimension, direction, normalized_rule) |
Classify an open entry using the fixed vocabulary |
get_voice_candidates(author_slug, book_slug?) |
Promotion candidates, conflicts and deferred patterns from the classified entries |
mark_feedback_harvested(book_slug, ids) |
Close entries as adopted |
discard_feedback(book_slug, ids) |
Close entries as discarded |
get_self_edit_hunks(book_slug, chapter_slug, offset?) |
Your own changes to draft.md against the version Claude last wrote (at most 20 per call; fiction only) |
refresh_draft_baseline(book_slug, chapter_slug) |
Remember the current draft.md as the new comparison baseline |
list_raw_drafts(book_slug) |
List chapters that have a chapter writer raw draft copy (fiction only) |
read_raw_draft(book_slug, chapter_slug) |
Read a chapter's raw draft copy |
The full flow is described in the Chapter Voice Harvest section of the quality system.
Book rules and book CLAUDE.md
A book's rules, workflows and callbacks live in the database. The CLAUDE.md in the book directory serves as a readable view and carries the frontmatter value linter_mode.
| Tool |
Purpose |
init_book_claudemd(book_slug, book_title?, pov?, tense?, genre?, writing_mode?, overwrite?) |
Create CLAUDE.md from the template |
get_book_claudemd(book_slug) |
Read CLAUDE.md |
append_book_rule(book_slug, text, validate?) |
Append a rule |
list_book_rules(book_slug) |
List all rules |
update_book_rule(book_slug, rule_index?, rule_match?, new_text?, delete?, validate?, include_callbacks?) |
Replace or remove a rule |
lint_book_rules(book_slug) |
Audit rules for scanner blind spots |
append_book_workflow(book_slug, text) |
Append a workflow instruction |
append_book_callback(book_slug, text) |
Append a callback |
sync_book_claudemd_from_text(book_slug, text) |
Extract entries prefixed Regel:, Workflow:, Callback: from text and store them |
update_character_snapshot(book_slug, character_slug, snapshot_json, book_category?) |
Store a character's state at chapter end |
Author profiles
| Tool |
Purpose |
list_authors() |
All profiles |
get_author(slug) |
Full profile including writing discoveries |
create_author(name, genres?, tone?, voice?, tense?) |
New profile with template files, seeds 19 default AI-tell words as donts; on a DB error the response carries a warning |
update_author(slug, field, value) |
Change a profile frontmatter field; normalizes author_writing_mode: structured→outliner, accumulative→plantser |
delete_author(slug, force?) |
Delete a profile with its discoveries; also removes the author's logged review feedback; refuses while books reference it, unless force is set |
harvest_book_rules(book_slug, author_slug?) |
Classify a book's rules as promotion candidates |
write_author_discovery(author_slug, section, text, book_slug, year_month?, validate?, example?, genres?, universal?) |
Store a discovery; for a memoir book, without example and without the name of a person from the book |
write_author_banned_phrase(author_slug, phrase, reason?) |
Store a banned phrase |
add_vocabulary_entry(author_slug, entry_type, text, source?) |
Store a vocabulary entry |
delete_discovery(author_slug, discovery_type, text) |
Remove a discovery by exact text |
update_discovery_metadata(author_slug, book_slug, source_genres) |
Set source_genres on all discoveries of a book |
extract_text_from_file(file_path) |
Extract text from PDF, EPUB, DOCX, TXT or MD for style analysis |
Ideas, genres and craft references
| Tool |
Purpose |
create_idea(title, genres?, logline?, concept?, book_category?) |
New idea file |
list_ideas(status?, genre?) |
Ideas with filters |
get_idea(slug) |
Content of an idea |
update_idea(slug, field, value) |
Change a frontmatter field |
promote_idea(slug, book_slug) |
Mark an idea promoted and link it to the book |
list_genres() |
All genres from the plugin and user directory; a user genre with the same name wins |
get_genre(name) |
Genre README from the plugin or user directory, the user genre takes precedence |
list_craft_references() |
All craft and genre references |
get_craft_reference(name) |
Load one reference, for example story-structure; chapter-writer, plot-architect and book-conceptualizer also call it per genre as {genre}-craft |
Memoir, scenes and cover
| Tool |
Purpose |
create_person(book_slug, name, relationship, person_category, consent_status?, anonymization?, real_name?, description?) |
Profile of a real person in the memoir |
set_memoir_structure_type(book_slug, structure_type) |
Store the structure type: chronological, thematic, braided or vignette |
create_scene_list(book_slug, scenes) |
Create or overwrite plot/scenes.md |
update_scene(book_slug, scene_number, chapter?, pov?, summary?, est_words?, status?) |
Change one scene row |
import_cover_image(book_slug, source_path, is_final?) |
Copy an externally generated cover into the project |
get_cover_image(book_slug) |
Determine the cover for export |
get_post_processing_config() |
Configured typography tool |
Series
| Tool |
Purpose |
create_series(title, genres?, planned_books?, author?) |
Series directory with series.yaml |
add_book_to_series(series_slug, book_slug, number, status?) |
Assign a book to a series |
create_character_tracker(series_slug, name, slug, role, recurs_in, species?, tracker_type?, book_slug?) |
Series character tracker from the template |
list_series_trackers_for_book(series_slug, band) |
Trackers that recur in the volume |
read_character_for_harvest(book_slug, character_slug, book_category?) |
Read a character file for the harvest |
write_series_evolution_section(series_slug, tracker_slug, band, kind, content, log_message, date?) |
Write a start, end or planned value into a tracker |
copy_recurring_chars_to_new_book(series_slug, prev_book_slug, new_book_slug, new_band, book_category?) |
Copy recurring characters into the new book |
read_tracker_for_bootstrap(series_slug, tracker_slug, prev_band, new_band, prev_book_slug?) |
Bootstrap data of one tracker |
bootstrap_character_for_new_book(series_slug, tracker_slug, prev_book_slug, new_book_slug, prev_band, snapshot_json, log_message?, book_category?, date?) |
Create a recurring character for the new book |
State and paths
| Tool |
Purpose |
get_session() |
Read the current session context |
update_session(last_book?, last_chapter?, last_phase?, active_author?) |
Store the session context |
get_review_handle_config() |
Configured review handle |
rebuild_state() |
Rebuild the state cache from the file system; raises the book status in the README where needed |
update_field(file_path, field, value) |
Change a field in Markdown frontmatter or a YAML file |
resolve_path(book_slug, component?, sub_path?) |
Resolve the path of a book component |
get_book_category_dir(category) |
Knowledge directory of a book category |