Guide

Connect once. Format from any AI.

Everything about using the Narracore Screenplay Formatter: connecting your AI app, what the input should look like, what you get back, how the quota and refunds work — and how this service relates to narracore.cn.

1 · Connect

One URL, any MCP client.

https://mcp.narracore.app/mcp copied

Claude (claude.ai / Desktop)

Settings → Connectors → Add a custom connector
Paste the URL above; no authentication needed for the free tier
In chat: “Format this screenplay for me”

ChatGPT (Developer mode)

Settings → Apps & Connectors → Developer mode
Create a dev connector with the URL above
Then just ask in chat

Cursor

Settings → MCP → Add new global MCP server
Type url, value: the URL above

Gemini & every MCP client

Streamable HTTP endpoint, no auth header for the free tier
Tools: format_screenplay and check_credits

Paid key? Put it in your client's auth (Authorization: Bearer NRC-… or X-License-Key) — the header keeps the key out of chat and takes precedence over the license_key tool parameter. Or simply paste “My key: NRC-…” into the chat and let the AI pass it along.

2 · Input format

Plain text in — or typed blocks.

Text mode (default)

One element per line:

Scene headings: INT. LAB - DAY · 第 N 场 … · N 外 …
Character names in CAPS or Chinese, alone on their line
Dialogue on the following lines, kept short
Standalone (parentheticals) and transitions like CUT TO: / 切至：

Blocks mode (exact)

For text the line-based parser can't trust (e.g. Latin names + “V.O.”), submit typed blocks instead:

Dialogue carries speaker and optional delivery
Blocks are rendered exactly as submitted, never re-classified
Annotations in【…】are reported, never executed

Free structure check: pass output="validate_only" — diagnostics only, costs nothing and never touches your quota. Unbroken walls of text render as continuous action and are flagged UNRESOLVED_STRUCTURE.

Diagnostic code	Meaning
`UNRESOLVED_STRUCTURE`	The text couldn't be split into screenplay elements with confidence (often one long paragraph).
`MISSING_SPEAKER`	A dialogue block has no character name attached.
`AMBIGUOUS_ACTION_MAYBE_DIALOGUE`	A line reads like dialogue but has no speaker — the engine keeps it as action and flags it.
`LABELED_HEADER_LINE`	A “Label: text” line that looks like a scene heading with a label prefix.
`REVISION_NOTE_PRESENT`	【…】 or （…） contains revision-intent keywords — reported as a note, not executed.
`BRACKETED_ANNOTATION`	Other【…】markers found in the text (informational).
`UNBALANCED_DELIMITER`	An opening/closing marker (brackets, quotes) is missing its pair.
`EMPTY_TEXT`	An empty line or block where content was expected.

3 · Output & limits

Blocks, clean text, and a print-ready PDF.

Every call returns structured blocks, a clean plain-text screenplay, and a download link to a PDF that auto-deletes after 24 hours. A confidence score tells your AI how much of the input was unambiguous — it is a share of clear lines, not an accuracy promise.

INT. RESEARCH LAB - DAY 1 John stares at the monitors, gauges climbing steadily. CHANG (quietly) We are still boiling water. This is our only shot. CUT TO: — US Letter · Latin track 61 chars × 55 lines · CJK track 33 × 38 — scene numbers on the right · Sarasa Mono / Courier Prime embedded

The grid is fixed on purpose: one page ≈ one minute of screen time, and the PDF matches narracore.cn's print preview line for line. Text is processed in memory; script content is never logged and never used for training.

4 · Quota, pricing & refunds

One free format every day.

Free tier — $0

One free format per day, no account or key
validate_only structure checks are always free

Paid packs — $1.49 / 10 · $5.99 / 50

Buy at /checkout (PayPal, cards inside the PayPal window); key shown right after payment
Top-ups land on the same key; unused formats don't expire

The honest rules: you pay for successful formatting only — rendering failures are never charged; retries with the same request_id never double-charge; full refund within 7 days if unused (email huiyicd@foxmail.com with your order id). No subscription, no wallet, no auto-renewal. We store only a SHA-256 hash of your key plus its last 4 characters.

5 · narracore.app vs narracore.cn

Two products, one layout engine.

narracore.cn — the workbench

A full screenwriting workbench in your browser: structured editor with eight block types, autosave, print preview and PDF export
Cloud projects, version history, characters / locations / props, and deterministic script statistics (account features are in invite-only beta; the editor itself needs no account)

narracore.app — the formatter

A remote MCP tool: your AI client pastes in rough text and gets structure + PDF back
No editor, no projects — just formatting, on exactly the same fixed-grid layout engine as narracore.cn

Write in the browser at narracore.cn; let your AI do the formatting at narracore.app. Install docs and real-input examples also live in the public repository.