Integration

MCP server integration

Narrarium exposes a local stdio MCP server for repository mutations and a public HTTP MCP surface for setup and research. This page is generated from the MCP source files, so the tool list reflects the implementation.

Local stdio MCP

Use it for canon creation, chapter and scene work, assets, renames, validation, resumes, evaluations, and EPUB export.

npx narrarium-mcp-server

Public HTTP MCP

Use it for setup guidance, repository spec help, and Wikipedia research. It is intended for `/mcp` and `/health` deployment on Vercel.

https://narrarium.space/mcp

Health: https://narrarium.space/health

OpenCode config

{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "build",
  "agent": {
    "build": {
      "temperature": 0.45,
      "top_p": 1,
      "options": {
        "reasoningEffort": "high",
        "reasoningSummary": "detailed",
        "textVerbosity": "high",
        "include": ["reasoning.encrypted_content", "usage"],
        "store": false
      }
    },
    "plan": {
      "temperature": 0.2,
      "top_p": 1,
      "options": {
        "reasoningEffort": "high",
        "reasoningSummary": "detailed",
        "textVerbosity": "high",
        "include": ["reasoning.encrypted_content", "usage"],
        "store": false
      }
    }
  },
  "watcher": {
    "ignore": ["conversations/sessions/**", "conversations/*.json"]
  },
  "mcp": {
    "narrarium": {
      "type": "local",
      "command": ["node", "packages/mcp-server/dist/index.js"],
      "enabled": true,
      "timeout": 15000
    }
  }
}

Continuity workflow

Final chapter and paragraph mutations refresh plot.md and resumes/ automatically, but structured continuity state stays manual by design.

After stable rewrites, add or refine state_changes in the relevant chapter resume, then run sync_story_state to rebuild state/current.md, state/chapters/, and clear state/status.md.

What doctor checks

doctorBook() and generated reader doctor scripts now flag missing or stale state/ snapshots, alongside broken references, spoiler issues, asset metadata gaps, and stale plot or resume files.

Local MCP tools

Other

Tool Description
apply_dialogue_action_beats Apply confirmed dialogue action beat selections to a final paragraph after review_dialogue_action_beats. This only updates the chosen beats and then writes the paragraph.
chapter_writing_context Assemble the point-in-time context that should be read before writing or polishing a chapter: prose defaults, scoped story-so-far context, prior chapter state, and matching chapter draft without leaking later story material. In prose, keep canon names as plain text instead of markdown links; the reader resolves visible mentions.
paragraph_writing_context Assemble the point-in-time context that should be read before writing or polishing a paragraph: prose defaults, scoped story-so-far context, prior scenes only, and the matching paragraph draft or final paragraph without leaking later story material. In prose, keep canon names as plain text instead of markdown links; the reader resolves visible mentions.
prepare_paragraph_evaluation Compute objective text metrics and style context for a single paragraph and return them as structured data so the LLM can perform the editorial reading before calling write_paragraph_evaluation. Call this first, read the result carefully, then call write_paragraph_evaluation with your editorial judgment.
promote_book_item Promote a structured book-level idea or note out of the active queue. You can move it into notes or story design, or archive it as promoted after you already used it in a draft.
promote_chapter_item Promote a structured chapter-level idea or note out of the active queue. You can move it into chapter notes or archive it as promoted after using it in draft work.
query_canon Answer a natural-language canon question by combining structured state, summaries, chapters, and repository search. Use this for questions like where a character is, what they know, who holds a secret, when something first appears, or how a relationship/condition/open loop changes across a chapter range.
resume_book_context Assemble restart context for a book project using prose rules, stable context, summaries, and exported conversations. You can also scope it to a target chapter or paragraph so the canon only reflects the story up to that writing point.
review_dialogue_action_beats Review a final paragraph beat by beat to judge whether dialogue-adjacent actions are purposeful, weak, or better replaced with a simple speech tag. This is proposal-only and may also suggest new beats or recurring tics worth observing for character canon.
revise_chapter Propose a chapter-level editorial pass without writing files. Use this when you want diagnosis plus scene-by-scene rewrite proposals for an existing final chapter. The result can also suggest merged state_changes review if multiple scenes touch continuity-sensitive beats.
revise_paragraph Propose a revision for an existing final paragraph without writing files. Use this for targeted editorial passes like clarity, pacing, tension, dialogue, voice, show-dont-tell, or redundancy cleanup. Show the proposal to the user first, then apply it with update_paragraph only after clear confirmation. The result can also suggest state_changes to review if the paragraph carries continuity-sensitive beats.
save_book_item Create or update a structured idea or note entry at book level. Use this for active idea queues and note queues rather than freeform body edits.
save_chapter_item Create or update a structured idea or note entry tied to a chapter draft.
write_paragraph_evaluation Write the final paragraph evaluation file using LLM-supplied editorial strengths, concerns, canon notes, next steps, and verdict explanation combined with objective metrics recomputed from the current chapter state. Call prepare_paragraph_evaluation first to obtain the objective data before calling this tool.

Guided flows

Tool Description
chapter_wizard Return the Narrarium chapter checklist so the agent can gather the right details before creating a chapter.
character_wizard Return the Narrarium character creation checklist so the agent can gather the right information before creating a character file.
faction_wizard Return the Narrarium faction creation checklist so the agent can gather the right details before creating a faction file.
item_wizard Return the Narrarium item creation checklist so the agent can gather the right details before creating an item file.
location_wizard Return the Narrarium location creation checklist so the agent can gather the right details before creating a location file.
paragraph_wizard Return the Narrarium paragraph or scene checklist so the agent can gather the right details before creating a paragraph file.
secret_wizard Return the Narrarium secret creation checklist so the agent can gather the right details before creating a secret file.
start_wizard Start a multi-step guided wizard session for creating canon files or chapter structures. Use this when the user has not provided all required details yet.
timeline_event_wizard Return the Narrarium timeline event checklist so the agent can gather the right details before creating a timeline event file.
wizard_answer Answer the current prompt in a running wizard session and receive the next guided question.
wizard_cancel Cancel a wizard session and discard its in-memory answers.
wizard_finalize Finalize a wizard session and write the corresponding file or folder into the local book repository.
wizard_status Inspect the current state of a wizard session, including collected fields and the next question.

Creation and assets

Tool Description
create_asset_prompt Create an asset prompt markdown file in the canonical assets tree for a book, entity, chapter, or paragraph image.
create_chapter Create a chapter folder, chapter metadata file, and paired resume and evaluation files in the local book repository. In prose bodies, keep canon names as plain text instead of markdown links to canon files.
create_chapter_draft Create a rough chapter draft inside drafts/ using the same chapter slug structure as the final chapter tree. Keep canon names as plain text in the draft prose instead of markdown links.
create_chapter_from_draft Promote a chapter draft into the final chapters/ tree. It copies structural frontmatter from drafts/, accepts polished body text if provided, and syncs plot.md after writing. Final prose should keep canon names as plain text instead of markdown links.
create_character Create a rich character file using the Narrarium character wizard fields. Use this instead of the generic entity tool when the user is adding a real story character.
create_entity Create a canonical entity markdown file inside the local book repository. Use this for quick stubs, items, locations, factions, secrets, and timeline events. Prefer create_character for full story characters.
create_faction Create a rich faction file with mission, ideology, methods, alliances, and optional historical research support.
create_item Create a rich item file with appearance, purpose, significance, ownership, and optional historical research support.
create_location Create a rich location file with atmosphere, story function, landmarks, risks, and optional historical research support.
create_paragraph Create a numbered paragraph or scene markdown file inside an existing chapter folder. In prose bodies, keep canon names as plain text instead of markdown links to canon files.
create_paragraph_draft Create a rough paragraph or scene draft inside drafts/ using the same chapter tree as the final chapter.
create_paragraph_from_draft Promote a paragraph draft into the final chapters/ tree. It copies structural frontmatter from drafts/, accepts polished body text if provided, and syncs plot.md after writing. Final prose should keep canon names as plain text instead of markdown links.
create_secret Create a rich secret file with stakes, holders, protection, reveal strategy, and spoiler thresholds.
create_timeline_event Create a timeline event file with participants, significance, consequences, and optional factual research support.
generate_asset_image Generate an image for a canonical subject, save it into the assets tree, and keep the asset prompt metadata in sync.
init_book_repo Create the local Narrarium repository structure for a book project, including folders, guidelines, summaries, evaluations, and reusable skills.
register_asset Copy an existing image into the canonical assets tree and create its matching prompt metadata file.

Maintenance and output

Tool Description
evaluate_book Refresh the total book evaluation with chapter scorecards, writing-style-aware editorial checks, canon coherence checks, weighted verdict summaries, explicit verdict explanations, and revision priorities, and optionally refresh all chapter and paragraph evaluations too.
evaluate_chapter Refresh a full chapter evaluation by reading the whole chapter across all paragraph files, combining objective text signals with editorial reading against the active writing-style files and canon coherence checks, then writing objective/editorial scores, a weighted verdict, an explanation of why that verdict landed there, and next steps plus paragraph evaluation files.
evaluate_paragraph Refresh the saved evaluation for a single paragraph while still using the full chapter as context, including objective scores, writing-style-aware editorial notes, canon coherence checks, a weighted verdict, an explanation of why that verdict landed there, and concrete next steps.
export_epub Export the current book repository into an EPUB file from the ordered chapter and paragraph markdown files.
sync_all_resumes Refresh every chapter resume and the total book resume in one pass.
sync_plot Refresh the root plot.md file so it tracks chapter progression, revealed secrets, and timeline dates from current canon.
sync_resume Refresh a chapter resume or the total book resume from the current repository state without calling another model.
sync_story_state Refresh state/current.md and per-chapter state snapshots from chapter resume state_changes. This stays manual by design and clears the stale story-state flag.
validate_book Validate Narrarium frontmatter and file placement rules inside the local book repository.

Search and continuity

Tool Description
list_related_canon List canon files that reference or mention a given id or query, useful before writing scenes or revising continuity.
search_book Search the local book repository across canon, chapters, notes, summaries, and research before drafting or editing.

Updates and renames

Tool Description
rename_chapter Rename a chapter title or number, move its folder, and move any matching chapter or paragraph asset folders if present.
rename_entity Rename an entity in a safe way: update its slug and id, move its markdown file, and move any matching asset folder if present.
rename_paragraph Rename a paragraph or scene title or number, move its markdown file, and move any matching paragraph asset folder if present.
update_book_notes Update the global working notes or story-design document. Use appendBody when the user asks you to keep a note without replacing the whole file.
update_chapter Update an existing chapter metadata file and optional chapter notes body. Use this for summary, POV, tags, and chapter notes changes without touching chapter numbering or folder naming. In prose bodies, keep canon names as plain text instead of markdown links.
update_chapter_draft Update an existing chapter draft by patching its frontmatter and replacing or appending rough draft body content.
update_chapter_notes Update or append chapter-specific working notes stored in drafts/<chapter>/notes.md. Use this when the user wants to keep or refine notes tied to a chapter draft.
update_entity Update an existing entity file by patching frontmatter and optionally replacing or appending markdown body content. Use rename_entity when the slug, id, or asset folder must move.
update_paragraph Apply an existing paragraph or scene revision after the user confirmed it. Use this for summary, viewpoint, tags, and body revisions without renumbering or renaming the file. Keep canon names as plain text instead of markdown links; the MCP layer refreshes plot and resume files after the update.
update_paragraph_draft Update an existing paragraph draft by patching its frontmatter and replacing or appending rough scene content. Keep canon names as plain text in the draft prose instead of markdown links.

Setup and research

Tool Description
repository_spec Return the Narrarium repository model and canon rules so clients can understand the book framework structure.
wikipedia_page Fetch English and the user's request language Wikipedia page summaries and save them into research/wikipedia inside the local book repository.
wikipedia_search Search English and the user's request language Wikipedia for historical or factual research before adding canon to the book repository.

Public HTTP MCP tools

Tool Description
repository_spec Return the Narrarium repository model and canon rules so clients can understand the book framework structure.
setup_framework Return the exact npx commands and setup steps to bootstrap a new Narrarium project from scratch.
wikipedia_page Fetch a Wikipedia page summary for setup or factual research.
wikipedia_search Search English or Italian Wikipedia for historical or factual research.
Tool lists are parsed from packages/mcp-server/src/index.ts and packages/mcp-server/src/public-http-server.ts.