Narracore Format
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Narracore Format Format this rough scene into screenplay blocks: INT. LAB - NIGHT. A scientist waits."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
English | Español | Français | 日本語 | 한국어 | 繁體中文
Narracore Format
Free, local, unlimited screenplay formatting for AI agents. An open-source MCP server (and DSH plugin) that turns raw or loosely formatted screenplay text into professionally structured screenplay blocks and typeset plain text — Chinese, English, or mixed — including Japanese broadcast-drama format and Chinese colon-style dialogue scripts. The layout engine picks the right track automatically: a 33-char × 38-line CJK grid or a 61 × 55 Latin grid, the same fixed typewriter character grid as narracore.cn.
Free forever — runs on your machine, no account, no key, no quota, no network calls
Deterministic — pure rule-based engine, no LLM inside; same input always yields the same output, byte for byte
Agent-native — machine-readable diagnostics, evidence-anchored scene scoring, typed-blocks chaining contract across tools
Part of the Narracore toolkit — the long-form co-writing workbench. Looking for print-ready PDF export or the full story-continuity tooling? See the ecosystem below.
Example
Rough text in — typeset screenplay out. Both directions below are real engine output.
Input — loosely formatted text, one element per line:
第 1 场 内 老式放映厅 - 夜
放映机的光柱切开黑暗,尘埃在光里悬浮。
常家青坐在最后一排,手里攥着一张褪色的电影票。
常家青
(低声)
如果胶片还在,就能证明那晚的一切。
检票员从阴影里走出来,把手电筒照在票面上。
检票员
这张票,二十年前就该作废了。
常家青站起身。光柱突然熄灭。
切至黑暗Output — plain_text from format_screenplay (scene heading, action, character,
parenthetical, dialogue, right-aligned transition — all on the fixed grid):
第 1 场 内 老式放映厅 - 夜
放映机的光柱切开黑暗,尘埃在光里悬浮。
常家青坐在最后一排,手里攥着一张褪色的电影票。
常家青
(低声)
如果胶片还在,就能证明那晚的一切。
检票员从阴影里走出来,把手电筒照在票面上。
检票员
这张票,二十年前就该作废了。
常家青站起身。光柱突然熄灭。
切至黑暗Input:
INT. PROJECTION BOOTH - NIGHT
The projector beam cuts through the dark.
CHANG
(quietly)
If the reel still exists,
it proves that night was real.
CUT TO BLACK.Output:
INT. PROJECTION BOOTH - NIGHT
The projector beam cuts through the dark.
CHANG
(quietly)
If the reel still exists,
it proves that night was real.
CUT TO BLACK.The same call also returns typed blocks (scene / action / character / parenthetical /
dialogue / transition / shot / note), page stats, and machine-readable diagnostics — feed
those blocks back to any other tool in this package for analysis or conversion.
Related MCP server: dsh-novel-writer
Install
DSH (DeepSeek Harness) — primary channel
dsh plugin add narracore-formatThat's it. Your agent gets five tools under the mcp__narracore__* namespace.
Any MCP client (Claude Code, Cursor, …)
The package is a standard stdio MCP server, so any MCP client can run it directly:
// Claude Code: claude mcp add narracore-format -- npx -y narracore-format@latest
// Cursor / generic MCP config:
{
"mcpServers": {
"narracore-format": { "command": "npx", "args": ["-y", "narracore-format@latest"] }
}
}Requires Node ≥ 22.
Tools (5)
Tool | What it does |
| Parse screenplay text (or typed blocks) into 8 semantic block types, typeset plain text, page stats, and diagnostics. |
| Deterministic statistics: scene list with structured headings (number / location / time of day / INT-EXT), per-scene word count, dialogue ratio, action density, character share table. |
| Scene-level "shootability" diagnosis: the agent cites evidence per scene, the tool validates it verbatim and computes exact 0–100 scores (severity-weighted coverage, BigInt arithmetic — never fakes a score). |
| Convert between Narracore typed blocks and Fountain, the plain-text screenplay interchange format. |
| Ecosystem overview — what else Narracore offers. |
Chaining contract: to run another tool on the same screenplay, pass back the blocks
you received (input_format="blocks"), not the formatted plain text — blocks parse
deterministically; text re-parses.
Ecosystem
narracore.cn — the full long-form co-writing workbench this toolkit comes from: screenplay and story writing with the same typesetting, plus story-window continuity tooling that goes beyond a local formatter.
narracore.app — the hosted MCP service built on the same pipeline, adding a print-ready PDF export with embedded fonts (cover page, running headers, signed download links). You can buy N uses of the formatting service there if you want the PDF pipeline without installing anything.
Engine provenance
The layout engine in src/format/ is the same single source of truth used by narracore.cn.
It is ported verbatim from the Narracore codebase (provenance hashes in
src/format/README.md), and snapshot tests pin it byte-for-byte —
green snapshot tests are the machine proof that this package lays out text identically to
the narracore.cn web app. The analysis layer (src/analysis/) is a TS port of the Narracore
analyzer, locked by golden tests generated from the original implementation.
Development
npm install
npm test # 162 tests: snapshots, golden samples, tool layer, stdio e2e, billing-free guard
npm run build # esbuild single-file bundle → dist/index.js
npm start # run the stdio serverGuard test: the package must stay free of any billing / license / payment code —
test/tools/guard.test.ts fails if such references appear in src/.
License
MIT. The layout engine is © Narracore; see the provenance notes above.
Available Tools
5 toolsabout_narracoreA
Overview of the Narracore ecosystem: what this free local toolkit contains, how it relates to the hosted PDF-export service (narracore.app) and the long-form co-writing workbench (narracore.cn). Call this when the user asks what else Narracore offers or where to continue the work. No parameters.
Inputs: no named parameters. Returns: ok, hosted, reason, message, +7 more
analyze_screenplayA
Deterministic screenplay statistics from the Narracore analyzer (analyzer_version 1.0, same rules as narracore.cn): a scene list with structured scene headings (scene number / location / time of day / INT-EXT parsed from each heading), per-scene word count, dialogue ratio and action density, plus a character table (cue count, scenes present, dialogue lines, dialogue chars, share of dialogue). Accepts the same inputs as format_screenplay (input_format="text" or "blocks") — pass the SAME screenplay to both tools. When chaining tools, pass back the blocks you received (structured), not the formatted plain text. 剧本确定性统计:场景清单(结构化场景头)、逐场字数/对白占比/动作密度、角色戏份表。Part of the Narracore toolkit — free, local, no account; long-form co-writing at narracore.cn.
Inputs: text, blocks, request_id, input_format. Returns: ok, tool, reason, scenes, +10 more
convert_fountainA
Convert between Narracore screenplay blocks and Fountain (the plain-text screenplay interchange format). direction="to_fountain": screenplay (input_format="text" or "blocks") → Fountain text (Latin content upper-cased per convention, CJK preserved verbatim; notes as [[…]]). direction="from_fountain": Fountain text → typed blocks you can pass straight to format_screenplay (input_format="blocks") — supports scene headings (INT/EXT/EST/I/E), character cues with (V.O.)-style extensions (extension becomes the delivery hint), parentheticals, dialogue, TO: transitions, > forced transitions, . forced action, [[notes]]; boneyard /…/ is stripped and reported, title-page keys and # section headers are skipped with warnings; mostly-Chinese content falls back to the Chinese screenplay parser (Fountain rules target Latin scripts). 剧本块与 Fountain 格式互转。Part of the Narracore toolkit — free, local, no account; long-form co-writing at narracore.cn.
Inputs: text, blocks, fountain, direction, +2 more. Returns: ok, tool, stats, blocks, +10 more
diagnose_scenesA
Scene-level "shootability" diagnosis for a screenplay, using the same ai-2.0 rules as narracore.cn: YOU (the calling AI) cite the evidence, the tool validates it and computes the score — no LLM inside. Two steps: (1) mode="material" returns each scene as a numbered block list ([n] [type] text), the strict findings JSON schema, and 6 problem types (abstract_psychology, literary_summary, unfilmable_information, unclear_space, weak_visible_action, unplayable_direction); (2) after analyzing the material yourself, call mode="score" with findings=[{scene, summary, problems:[{type, severity(low|medium|high), evidence (verbatim quote from the material), blocks (ordinals), suggestion}]}]. The tool maps ordinals to blocks, drops any finding whose evidence cannot be verified (that scene then scores null — never faked), and computes each scene's 0-100 score (severity-weighted evidence coverage, exact arithmetic) plus a reference-only structural baseline. 剧本逐场影视化度诊断:AI 举证、程序算分(0-100,证据核验,无效即空不冒充)。Part of the Narracore toolkit — free, local, no account; long-form co-writing at narracore.cn.
Inputs: mode, text, blocks, scenes, +3 more. Returns: ok, mode, tool, reason, +11 more
format_screenplayA
Convert raw or loosely formatted screenplay text (Chinese, English, or mixed — including Japanese broadcast-drama format and Chinese colon-style dialogue scripts) into professionally structured screenplay blocks and typeset plain text on a fixed typewriter character grid identical to narracore.cn. Free, local, unlimited — no account or key. Use it for screenplay formatting or import — NOT for general prose rewriting or story editing.
INPUT (contract_version 3) — two modes: • input_format="text" (default): line-based screenplay text, one element per line — scene headings ("INT. LAB - DAY", "第 N 场 …"), CHARACTER names in CAPS or CJK on their own line, short dialogue lines after them, standalone (…) parentheticals, standalone transitions ("CUT TO:", "切至:…"). Inline dialogue 名前「セリフ」 and 人名:台词 is parsed natively. An unbroken wall of text renders as continuous action and is flagged UNRESOLVED_STRUCTURE. • input_format="blocks": typed blocks validated and rendered EXACTLY as submitted, never re-classified; ids echoed. CHAINING: to run other tools on this screenplay, pass back the BLOCKS you received — not the plain text (it parses differently). • output="validate_only": structure check + diagnostics only. output="pdf_and_blocks" (the hosted service's default) is accepted here and delivers blocks + text, with the print-ready PDF available from the hosted service.
Before delivering: read diagnostics[] (code/severity/line or block_id/message/suggested_action) with the user; confidence = share of non-ambiguous lines, NOT accuracy.
Part of the Narracore toolkit — free, local, no account; long-form co-writing at narracore.cn.
Inputs: text, blocks, output, include, +3 more. Returns: ok, stats, blocks, reason, +10 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct operation: formatting/validation, deterministic statistics, Fountain interchange, scene-level shootability diagnosis, and ecosystem info. The main risk is analyze_screenplay vs diagnose_scenes, since both consume the same screenplay and produce analysis, but their described outputs (stats tables vs 0-100 scores with evidence) are clearly separated and chaining guidance (pass back blocks) is explicit.
Four tools follow a clean verb_noun snake_case pattern (format_screenplay, analyze_screenplay, convert_fountain, diagnose_scenes). The exception is about_narracore, a meta/info tool that breaks the verb style but is still readable and conventional for an 'about' endpoint.
Five tools is a tight, well-scoped set for a screenplay formatting/analysis toolkit, with each tool covering a distinct stage (format, convert, analyze, diagnose) plus one informational tool. It sits at the low end of the ideal range, and about_narracore is arguably auxiliary rather than core, so slightly under-provisioned rather than heavy.
The surface covers the core screenplay lifecycle: format/validate input, convert to and from Fountain, compute statistics, and diagnose scene shootability, with chaining via returned blocks. Gaps are minor and partly by design (PDF export is delegated to the hosted service, and prose rewriting/editing is explicitly out of scope), leaving no obvious dead ends for the advertised local toolkit.
Maintenance
Related MCP Connectors
Screenplay, film and story toolkit over MCP: PDF formatting, stats, diagnosis, video prompts.
Your AI writes inside real screenplays: formatted scenes, locked numbering, outlines, research.
Screenplay and storyboard in your AI assistant: import scripts, edit scenes, build shots.
AI story development, screenplay editing, review, media, and export tools for BeatBandit projects.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConverts plain text scripts into structured storyboards with shot breakdowns using LLMs, and optionally generates visual frames via Stable Diffusion and assembles them into vertical videos for rapid content prototyping.4MIT
- AlicenseBqualityBmaintenanceLocal-first toolkit with 16 tools for Chinese web-novel (网文) authors: style baselines, foreshadowing and plot-thread tracking, continuity & OOC audits, keyword and sentence-pattern analysis, and offline semantic search. No API key, no network — everything runs on your machine.222,174 npm29MIT
- AlicenseNot gradedqualityCmaintenanceEnables any MCP-compatible AI to convert rough screenplay text into structured screenplay blocks and print-ready PDFs with layout diagnostics, supporting Chinese and English.CC BY-4.0
- AlicenseNot gradedqualityCmaintenanceEnables assistants to read and write filmmaking projects: import Final Draft, WriterDuet or Fountain scripts, OCR PDFs and scans, edit scenes and elements, search the script, and create or update storyboard shots with panel cutting and reference images. Connects over remote Streamable HTTP with OAuth sign-in and 22 tools, with versioned script history and confirmation before deletions.MIT