# Final Draft MCP Server

## Description

**`fdx-mcp-server`** is a Model Context Protocol (MCP) server that lets AI agents read, analyze, and manipulate [Final Draft](https://www.filedropper.com/finaldraft) screenplay files (`.fdx`). It exposes tools for parsing scene headings, character arcs, dual dialogues, SmartType dictionaries, pagination maps, script breakdowns, and more — effectively giving an LLM the ability to understand and edit screenplay structure.

Written in TypeScript, it runs on **Bun** or **Deno** using the stdio transport protocol, making it suitable for integration with any MCP-compatible client such as Claude Desktop.

**Repository:** [github.com/dmongrel/fdx-mcp-server](https://github.com/dmongrel/fdx-mcp-server) · **Changelog:** [CHANGELOG.md](https://unpkg.com/fdx-mcp-server/CHANGELOG.md)

---

## Table of Contents

- [Installation](#installation)
  - [Prerequisites: Node.js](#prerequisites-nodejs)
  - [Option A — Direct from GitHub (Bun or Deno)](#option-a--direct-from-github-bun-or-deno)
  - [Option B — Global NPM Install](#option-b--global-npm-install)
- [Usage](#usage)
- [Features](#features)
- [Publishing](#publishing)

---

## Installation

### Prerequisites: Node.js

Node.js is required for **Option B** (Global NPM Install). If you plan to use that option, install it first using one of these methods:

- **Windows / macOS**: Download the LTS installer from [nodejs.org](https://nodejs.org/) and run it.
- **Linux (apt)**: `curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs`
- **Homebrew (macOS / Linux)**: `brew install node`

Verify the installation by running `node --version` and `npm --version` in your terminal.

### Option A — Direct from GitHub (Bun or Deno)

If you have **Bun**, **Deno**, or **both** installed, you can run the server directly from `raw.githubusercontent.com` without installing it locally. No compilation or OS code-signing warnings needed.

> ⚠️ **Rate-limit notice:** This path fetches the server from `raw.githubusercontent.com` every time your MCP client starts. GitHub enforces an anonymous usage policy that limits unauthenticated requests to **60 per hour** (across all of `github.com` and its subdomains). If you exceed this limit, requests will be rejected with a `403 Forbidden` error until the window resets. Frequent restarts can trigger this — for heavy use, see [Option B](#option-b--global-npm-install) which caches everything locally.

### Option B — Global NPM Install

If you prefer a traditional Node.js/NPM setup, install the package globally from the npm registry. This downloads all dependencies locally so the server boots instantly and works 100% offline.

```bash
npm install -g fdx-mcp-server
```

To update later: `npm update -g fdx-mcp-server`

Because this installs a pre-built package from the registry (rather than cloning and building the repo locally), it avoids the Windows npm/node-tar `ENOENT` race that git-based (`github:user/repo`) installs are prone to.

---

## Usage

Add a configuration block to your MCP client's config file (e.g., `claude_desktop_config.json` or `.mcp.json`). Select the entries that apply to you:

**Using Bun only:**

```json
{
  "mcpServers": {
    "fdx-mcp-server-bun": {
      "command": "bun",
      "args": ["run", "https://raw.githubusercontent.com/dmongrel/fdx-mcp-server/master/src/index.ts"]
    }
  }
}
```

**Using Deno only:**

```json
{
  "mcpServers": {
    "fdx-mcp-server-deno": {
      "command": "deno",
      "args": ["run", "--allow-env", "--allow-read", "--allow-write", "https://raw.githubusercontent.com/dmongrel/fdx-mcp-server/master/src/index.ts"]
    }
  }
}
```

**Using both Bun and Deno:**

```json
{
  "mcpServers": {
    "fdx-mcp-server-bun": {
      "command": "bun",
      "args": ["run", "https://raw.githubusercontent.com/dmongrel/fdx-mcp-server/master/src/index.ts"]
    },
    "fdx-mcp-server-deno": {
      "command": "deno",
      "args": ["run", "--allow-env", "--allow-read", "--allow-write", "https://raw.githubusercontent.com/dmongrel/fdx-mcp-server/master/src/index.ts"]
    }
  }
}
```

**Using global NPM install:**

```json
{
  "mcpServers": {
    "fdx-mcp-server": {
      "command": "fdx-mcp-server",
      "args": []
    }
  }
}
```

---

## Features

Key capabilities exposed by `fdx-mcp-server`:

- **Document lifecycle** — open, save, reload, create new `.fdx` files; manage server-side document cache.
- **Batch edits & savepoints** — apply an ordered list of edits atomically (all-or-nothing, with automatic rollback on failure), or take a manual savepoint around any sequence of edits and roll back to it on demand.
- **Document integrity** — detect and repair paragraphs that silently share a duplicated id (a FinalDraft copy/paste artifact that otherwise makes id-addressed edits land on the wrong paragraph); list every proofing-flag (spellcheck squiggle) hit with `get_flagged_words`, or just its count via `get_script_stats`, to confirm a sweep didn't alter anything; list or exclude drafting placeholders (`[FIX - ...]`-style whole-bracket paragraphs) with `get_placeholders` and `get_script_stats`'s `excludePlaceholders`, so a paragraph-count baseline stays usable while they're still in the document.
- **Scene analysis** — parse scene headings (INT./EXT., location, time of day), extract scene index and properties, compute script stats and page maps; set a scene's Color and/or Title with `edit_scene_properties`, or color a newly created Scene Heading in the same call via `edit_par action=create`'s `color` parameter.
- **Character tracking** — retrieve character lists, extension metadata (V.O., O.S.), per-character scene appearance counts, and arc beats across scenes; rename or merge a character across every place its name is stored (cue paragraphs, dictionary, cast, arc beats, highlighting) in one call; create a new Character/[Parenthetical]/Dialogue speech as one atomic insertion.
- **Dual dialogue support** — read and create side-by-side dialogue blocks.
- **SmartType dictionaries** — manage the FinalDraft autocomplete lists: characters, extensions, transitions, scene intros, times of day, spell-check lists, and paragraph types.
- **Location usage** — see actual location usage parsed from Scene Heading text (not just the autocomplete dictionary) and rename a location across every scene that uses it in one call.
- **Formatting & styling** — query and edit element settings (fonts, indentation, spacing) for every paragraph type; manage header/footer content.
- **Title page management** — read and write title, author, contact block, copyright, and based-on credits.
- **Script breakdowns** — generate full production breakdown reports (props, vehicles, camera, cast) as text or HTML/PDF.
- **Macro system** — query macro aliases and their activation scopes.
- **Search & navigation** — find paragraphs by text, list sections and section contents, retrieve revision colors and display board data; diff two documents' paragraphs by id (added/removed/modified) — useful for confirming what a versioned save actually changed.

---

## Publishing

Maintainer notes for releasing a new version to npm:

```bash
bun run build     # rebuilds dist/index.js, which is checked into the repo
npm publish
```

If the npm account has two-factor authentication enabled, **each `npm publish` requires its own
live 2FA approval** — logging in beforehand is not enough, and the approval from one publish does
not carry over to the next. Because of this, `npm publish` has to be run interactively, in a real
terminal, by whoever holds the authenticator — it cannot be scripted or run non-interactively (e.g.
from an AI coding assistant's shell tool) without a fresh prompt failing with an `EOTP` error.