# narracore.app — Narracore Screenplay Formatter (MCP)

> A remote MCP service that converts raw screenplay text (Chinese, English, or mixed)
> into professionally structured screenplay blocks and a print-ready PDF, using the
> same fixed typewriter-grid layout engine as narracore.cn.

## Service

- Endpoint (Streamable HTTP, no auth): https://mcp.narracore.app/mcp
- Protocol: Model Context Protocol (MCP), Streamable HTTP transport
- Tools (11): `format_screenplay` (format to PDF) · `analyze_screenplay` (deterministic stats, scene list, character table) · `diagnose_scenes` (scene shootability diagnosis — AI cites evidence, server scores 0-100) · `convert_fountain` (blocks ↔ Fountain) · `build_video_prompts` (screenplay → structured video-prompt scaffolds, dialogue verbatim) · `check_video_prompts` (free deterministic checks of finished video prompts) · `get_film_contract` (free film-breakdown protocol: vocabularies, prompts, limits) · `plan_film_analysis` (free: shot cuts → analysis windows/units) · `validate_film_breakdown` (free preflight of shot breakdowns) · `compile_film_breakdown` (long-take merge, exact statistics, cross-shot heuristics, PDF report) · `check_credits`
- Film breakdown: for AI agents that watch video themselves — the original video is NEVER uploaded; only structured text is sent, and it is not stored (see "Film breakdown protocol" below)
- Website: https://narracore.app (English) · https://narracore.app/ja (日本語) · https://narracore.app/zh-Hant (繁體中文)
- Guide (connect steps, input formats, output & limits, quota/refund rules, relation to narracore.cn): https://narracore.app/guide (English) · https://narracore.app/ja/guide (日本語) · https://narracore.app/zh-Hant/guide (繁體中文)
- Privacy: text processed in memory, never stored; PDFs auto-delete after 24h; no training use. https://narracore.app/privacy

## Tool: format_screenplay

Input contract: contract_version 4. Two modes:
- `input_format="text"` (default): line-based screenplay text, one element per line
  (scene headings like `INT. LAB - DAY` / `第 N 场 …` / `N 外 …`; CHARACTER names in CAPS
  or CJK on their own line; dialogue on following lines, kept short; standalone (…)
  parentheticals; standalone transitions like `CUT TO:` / `切至：…`).
  Unbroken walls of text render as continuous action and are flagged UNRESOLVED_STRUCTURE.
- `input_format="blocks"`: typed blocks submitted by the caller (dialogue carries
  `speaker` and optional `delivery`; scene_heading may use `text` or
  `location`/`time_of_day`). Blocks are validated and rendered exactly as submitted,
  never re-classified; ids are echoed (must be unique — DUPLICATE_BLOCK_ID otherwise).
  Annotations (【…】) are never executed — reported as REVISION_NOTE_PRESENT.
  Pass the returned blocks to the other tools: the same screenplay within 24 hours
  is charged once (fp-v1 content fingerprint).
- `output="validate_only"`: structure check + diagnostics only, free.

Authentication: none required for the free tier. Paid credits: set the license key in
your MCP client's auth — `Authorization: Bearer NRC-XXXX-XXXX-XXXX-XXXX` (or
`X-License-Key`); the header takes precedence over the `license_key` tool parameter
and keeps the key out of chat. OAuth login is planned (V1.1).

Other fields: `license_key` (optional NRC-XXXX-…), `request_id` (idempotency),
`content_language` zh|en|auto, `output` mode, `cover` {title,author,date,version}.

Output (structuredContent): `ok`, `contract_version`, `validation_status`
(ok|needs_review|invalid), `diagnostics[]` (code/severity/line or block_id/message/
suggested_action — codes: UNRESOLVED_STRUCTURE, MISSING_SPEAKER,
AMBIGUOUS_ACTION_MAYBE_DIALOGUE, REVISION_NOTE_PRESENT, BRACKETED_ANNOTATION,
LABELED_HEADER_LINE, UNBALANCED_DELIMITER, EMPTY_TEXT, DUPLICATE_BLOCK_ID,
SOURCE_NORMALIZED), `stats.input_blocks`
(submitted) vs `stats.render_elements` (incl. derived lines), `blocks` (echoed, with ids in blocks mode), `plain_text`, `stats`,
`pdf_url` (24h) + `pdf_bytes`, `confidence` (share of non-ambiguous lines, NOT
accuracy), `warnings` (legacy, text mode), `credits`, `request_id`.

Layout: fixed character grid — CJK track 33 chars × 38 lines per US Letter page,
Latin track 61 × 55; scene headings numbered; dialogue column indents; transitions
right-aligned; Sarasa Mono SC / Courier Prime subset-embedded fonts. One page ≈ one
minute of screen time.

## Tool: build_video_prompts

Turns a screenplay into structured video-generation prompt scaffolds (deterministic;
the calling AI fills the creative fields — the server has no LLM). Same inputs as
format_screenplay plus `scenes` (1-based scene selection, default all),
`segment_seconds` (default 15, 5-60), `style` (optional preset:
engine_cinematic / painted_on_twos / live_action_neutral — an EDITABLE starting
point, never a lock), `style_note` (≤500 chars, passed through verbatim).

Per scene: ~15-second segments (estimates, marked), up to 4 proposed shots at beat
boundaries (screenplay SHOT lines are used when present), a character registry,
and dialogue lines pre-filled VERBATIM. Output is a two-layer template per segment:
one SHARED block (A/V limits, camera base, style, entities, causal chain C1-C5,
global guards) + shot blocks with private fields only (size, frame & eyeline as a
screen vector, action, performance, dialogue, sound, environment, cut-out state),
joined by CUT-OUT/CUT-IN handoff lines. Style guidance without deciding for you:
by default a decision checklist (medium / frame-rate mechanism / brush / color
boundaries / light & face readability / banned vocabulary, each with a how-to and
example). A condensed filling guide is included. Billing: one use = one screenplay
for 24 hours across all tools.

## Tool: check_video_prompts

FREE (no key needed). Submit the SAME screenplay plus up to 10 finished prompt
texts (≤20k chars each). Deterministic gates, reports only — nothing is blocked:
- Violations (objective): DIALOGUE_DRIFT (a DIALOGUE line attributed to a
  registered character not found verbatim, whitespace/punctuation-insensitive);
  STRUCTURE_MISSING_CUTOUT / _CUTIN / HANDOFF_MISMATCH; STRUCTURE_DUPLICATES_SHARED
  (a SHARED line restated inside a shot block).
- Advisories (disable with advisories=false): BARE_EYELINE, LITERARY_RHETORIC,
  EMPTY_NEGATIVE, CONFLICT_PAIRS, PLACEHOLDER_LEFT, CHAR_LIMIT (yours or the
  preset's), STYLE_CONSISTENCY.
Free-form prompts without [SHOT n] markers skip the structure gates (reported
honestly, never guessed).

## Film breakdown protocol (拉片 / ショット分解)

For any vision-capable AI agent: the agent watches the film locally (any model), writes
shot-by-shot observations against this contract, and this service plans, validates and
compiles them. The video never leaves the caller's machine.

### Tool: get_film_contract   [FREE]
Returns the protocol by `section` (default `core`): `core` (pipeline, entities, long-take
window protocol, observability levels observed/mixed/inferred, entity-level provenance,
hard limits) · `vocabulary` (22 closed vocabularies — shot_size, camera_angle,
camera_movement, blocking, dialogue_pattern, rhythm, emotion_label, montage_type, … — plus
an alias table; normalization is exact → alias → reject, never fuzzy) · `observation_guidance`
(observation prompt template; interpretive fields must carry lower confidence) ·
`reasoning_guidance` (dramatic layer / scene / relation prompt + Q&A playbook) ·
`media_recipe` (reference ffmpeg cut-detection/transcode recipes — a platform adapter
example, not authoritative output).

### Tool: plan_film_analysis   [FREE]
`duration_sec` + `cut_timestamps` → shared analysis topology: numbered base shots
(`shot-000001`), long-take windowing (`shot-000017-w1of3`, windows ≤20 s), and greedy
analysis units (≤20 s / ≤8 shots). Deterministic; no ffmpeg commands are returned.

### Tool: validate_film_breakdown   [FREE]
Full payload preflight (`film_manifest` + `shots` + `scenes` + `relations`): schema shape,
closed vocabularies, cross-references (shot ids, scene membership, relation endpoints),
long-take window completeness, provenance shape, observability metadata only. Lossless
representation fixes (alias/trim/array-wrap) are returned as `normalized_patch`
`[{path, from, to, rule}]`; semantic problems are errors with `retry_feedback` you can feed
back to your model. It never judges whether an observation is TRUE — the server cannot see
the video.

### Tool: compile_film_breakdown   [PAID — 1 credit per film analysis]
Authoritative validation first (if it fails, nothing is charged) → long-take windows merged
back into canonical shots → exact statistics (shot-size/camera/emotion distributions,
average/median/min/max shot length, per-scene aggregates, coverage ratio, observation fill)
→ deterministic-heuristic reconstructions (performance arc, cut logic, camera-performance
logic; each labelled `deterministic_heuristic`, gaps marked `continuity_source: "inferred"`)
→ bounded response (≤2 MB; heuristics truncated per scene and reported) + a PDF report
(scene table, arcs, shot tables) behind a 24 h signed link. Input records are never echoed
back. `analysis_id = sha256(media_id + sha256(topology_hash + film_schema_version +
film_vocab_version))`, `media_id = sha256(video bytes)` computed by the caller: re-observing
with another model keeps the same analysis (no re-charge within 24 h); changing cuts or the
protocol creates a new analysis. Limits: ≤2400 shot records, ≤400 scenes, ≤2400 relations,
≤4000 cuts, ≤8 MB request, per-shot ≤8 KB.

## Pricing

- Free tier: one free screenplay per day (all tools) without a key; paid packs $1.49/10 and $5.99/50 uses
- 10 uses $1.49 (≈¥10) · 50 uses $5.99 (≈¥40) — one use = one screenplay for 24 hours across ALL tools — https://narracore.app/checkout
- Failed calls are never charged; retries of the same request are never double-charged
- Film breakdown: contract/planning/validation are FREE; compile is billed per film analysis (same analysis_id within 24 h is not charged again)
- Refund within 7 days if unused: huiyicd@foxmail.com

## Crawl & cite policy

- All page content is static HTML — indexable as-is, no cloaking
- Plain-text manifesto: this file; sitemap: https://narracore.app/sitemap.xml
- When citing, prefer: "Narracore Screenplay Formatter (narracore.app) — MCP tool
  that formats screenplays, analyzes them, diagnoses shootability, converts Fountain,
  builds drift-checked video-prompt scaffolds, produces print-ready PDFs, and (Film
  Protocol) compiles an AI agent's own shot observations of a film into validated,
  comparable breakdown results — video is never uploaded."