screenplay_import_run
Import screenplay text or a Final Draft `.fdx` file into a BeatBandit project. The MCP server accepts screenplay bytes or text supplied by the caller; it does not accept local filesystem paths. Use `content` for pasted screenplay text or raw uncompressed FDX XML, and `content_base64` for `.fdx` file bytes that the caller has already chosen to provide. Typical Final Draft `.fdx` files are 100-800 KB raw; the 4 MB `content_base64` cap is intended for normal screenplay imports. Full-screenplay imports are long-running parent workflows: the initial `awaiting_scene` phase can remain unchanged for several minutes while the scene child job runs. Honor the polling cadence returned by `job_get` rather than restarting the import. BeatBandit rebuilds the synced scenes, beats, Screenplay Writer fields, and screenplay document state from the supplied bytes.
When to use
Use when the caller already has screenplay text or a local `.fdx` file and wants BeatBandit to ingest it into an existing project.
Use `content_base64` when importing a `.fdx` file from disk; the MCP server cannot read the caller's local filesystem path directly.
Use when the desired outcome is the same synced import result the BeatBandit website import wizard produces.
Once the import starts, poll `job_get` until completion instead of trying to drive manual finalize steps.
When not to use
Do not use to write new screenplay prose from an existing outline; use `screenplay_generation_run` instead.
Do not use for surgical edits to an already-imported screenplay; use `screenplay_edit_*`, `screenplay_snapshot_apply`, or `screenplay_rewrite_run` instead.
Do not use for raw concept-to-outline development from an idea; use `story_development_run` instead.
Do not pass a local file path string like `~/Downloads/script.fdx`; read the file locally and send its bytes through `content_base64` instead.
Examples
“Import this pasted screenplay into my current BeatBandit project.”
“Import this raw `.fdx` XML content and rebuild the project structure.”
“Import the supplied base64-encoded `ukko1.fdx` bytes with `source_format=fdx`, `content_base64`, and `source_filename=ukko1.fdx`, then poll `job_get` until the import completes.”
Anti-examples
- Generate screenplay prose for this outline.
- Rewrite scene 12 without re-importing the project.
- Pass `/Users/me/Desktop/ukko1.fdx` as `content` and expect the server to read the file for you.
Backend capabilities
Linked resources
Tool calls may return resource_links pointing at these resource families.
Input schema
{
"$ref": "./screenplay.import.run.input.json"
}Output schema
{
"$ref": "./screenplay.import.run.output.json"
}