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 — Chinese, English, Japanese broadcast-drama format, Chinese
colon-style dialogue scripts, or mixed — into professionally structured screenplay blocks and
typeset plain text on 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.
Install
DSH (DeepSeek Harness) — primary channel
dsh plugin add narracore-format
That'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 |
|---|
format_screenplay | Parse screenplay text (or typed blocks) into 8 semantic block types, typeset plain text, page stats, and diagnostics. output="validate_only" checks structure without formatting. |
analyze_screenplay | 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. |
diagnose_scenes | 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_fountain | Convert between Narracore typed blocks and Fountain, the plain-text screenplay interchange format. |
about_narracore | 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 server
Guard 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.
