MCP / Tools / Screenplay / screenplay_import_run

screenplay_import_run

orchestrationbetaauth: screenplay:writeapproval: suggeststatus: v1

Import screenplay scenes, beats and canonical pages. Quote first; after accepting use billing_quote_id, a stable billing_request_id UUID and identical source/options. Inline content supports text/FDX XML; content_base64 supports local FDX bytes. ChatGPT attachments use their verified mounted file path in file at quote; ChatGPT supplies the download object. Never use a file ID as that path or fabricate a URL. Use source_format=plain_text for TXT/Fountain or fdx for FDX, then source_handle at Start. Supports TXT/Fountain and XML/zipped FDX. Poll job_get until complete.

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.
For a ChatGPT attachment, pass its verified host-local path in `file`; ChatGPT transfers it and supplies the required download object to MCP. This differs from asking BeatBandit to open a path on the caller's computer.
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

screenplay_import.runscreenplay_import.quote

Linked resources

Tool calls may return resource_links pointing at these resource families.

project_canon_summary screenplay_document

Input schema

screenplay_import_run input

{
  "$ref": "./screenplay.import.run.input.json"
}

Output schema

screenplay_import_run output

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": [
    "project_id"
  ],
  "properties": {
    "async": {
      "type": "boolean"
    },
    "job_id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "project_id": {
      "type": "integer"
    },
    "project_name": {
      "type": "string"
    },
    "project_mode": {
      "type": "string"
    },
    "workflow_phase": {
      "type": "string"
    },
    "import_stage": {
      "type": "string"
    },
    "active_child_job_id": {
      "type": "string"
    },
    "source_format": {
      "type": "string",
      "enum": [
        "plain_text",
        "fdx"
      ]
    },
    "source_filename": {
      "type": [
        "string",
        "null"
      ]
    },
    "estimated_credits": {
      "type": "integer",
      "minimum": 0
    },
    "reserved_credits": {
      "type": "integer",
      "minimum": 0
    },
    "credit_reservation_id": {
      "type": "string"
    },
    "credits_charged": {
      "type": "integer",
      "minimum": 0
    },
    "credits_skipped_reason": {
      "type": "string"
    },
    "steps": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "summary": {
      "type": "object"
    },
    "resource_links": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "pipeline_state": {
      "$ref": "./_common/pipeline_state.schema.json"
    },
    "next_actions": {
      "type": "array",
      "items": {
        "$ref": "./_common/next_action.schema.json"
      }
    },
    "recommended_action": {
      "type": "string"
    },
    "result": {
      "type": "object"
    },
    "phase": {
      "type": "string",
      "enum": [
        "quote",
        "start"
      ]
    },
    "quote": {
      "type": "object"
    },
    "source_handle": {
      "type": "string",
      "format": "uuid"
    }
  },
  "additionalProperties": true
}