# Storywriting & Screenplay MCP Server (67 Tools)

A custom **Model Context Protocol (MCP)** server for AI-assisted storywriting, narrative world-building, character depth development, industry-standard screenplay generation (Fountain, Final Draft `.fdx`, Courier PDF), visual storyboards, generic outline ingestion, and line production analytics.

---

## Project Structure (Refactored Clean Core Engine)

```
d:\Studio\MCP -Storywriting\
├── server.py                        # MCP Server entrypoint (stdio, sse, streamable-http)
├── requirements.txt                 # Dependencies
├── SETUP_GUIDE.md                   # Dedicated Claude Connector Setup Guide
├── LLM_COMPATIBILITY.md             # ChatGPT, Gemini, Kimi, DeepSeek Guide
└── story_engine/                    # Generic Core Engine
    ├── models.py                    # Schemas for Story Bible, Screenplay, Storyboards, Pitch Decks
    ├── storage.py                   # Storage persistence (.story/ directory)
    ├── batch_processor.py           # Category P: Generic Batch & Pipeline Generator
    ├── brainstorm.py                # Category A: Concept & Brainstorming (4 tools)
    ├── character.py                 # Category B: Character Architect & Dynamics (4 tools)
    ├── world.py                     # Category C: World-Building & Lore (4 tools)
    ├── beats.py                     # Category D: Structural Plotting & Beat Sheets (5 tools)
    ├── drafting.py                  # Category E: Interactive Drafting Engine (5 tools)
    ├── story_doctor.py              # Category F: Story Doctor & Continuity (4 tools)
    ├── screenplay.py                # Category G: Screenplay Adaptation & PDF/FDX (4 tools)
    ├── storyboard.py                # Category H: Storyboard & Visual Shotlists (3 tools)
    ├── dialogue_engine.py           # Category I: Character Voice & Dialogue Polish (4 tools)
    ├── analytics_engine.py          # Category J: Screenplay Timing & Analytics (4 tools)
    ├── directing_engine.py          # Category K: Visual Directing, Camera & Audio (5 tools)
    ├── production_engine.py         # Category L: Line Production & Stripboards (4 tools)
    ├── marketing_engine.py          # Category M: Pitch Deck & Marketing Suite (4 tools)
    ├── writers_room.py              # Category N: Writers' Room Mechanics (6 tools)
    └── exporters.py                 # Category O: Multi-Format Exporters & Visual Prompters (5 tools)
```

---

## 🛠️ How to Setup & Install This MCP Server

### 1. Prerequisite Installation & Python Virtual Environment Setup

1. Open PowerShell or Terminal in the project directory:
   ```powershell
   cd "d:\Studio\MCP -Storywriting"
   ```
2. Create and activate a Python virtual environment:
   ```powershell
   python -m venv venv
   .\venv\Scripts\Activate.ps1
   ```
3. Install required packages:
   ```powershell
   pip install -r requirements.txt
   ```

---

### 2. Setting Up in Claude Code / Claude Web (Remote Connector via Ngrok)

To connect Claude Web / Claude Code to your local MCP server:

#### Step 2A: One-Time Ngrok Authtoken Setup
Authenticate ngrok to resolve remote connection errors:
```bash
ngrok config add-authtoken <your-ngrok-authtoken>
```

#### Step 2B: Start the MCP Server in Streamable HTTP Mode
Run the server on port `8000`:
```powershell
& "d:\Studio\MCP -Storywriting\venv\Scripts\python.exe" server.py --transport streamable-http --port 8000
```
*(Keep this terminal open!)*

#### Step 2C: Start Ngrok HTTPS Tunnel
In a **second** terminal window, start ngrok:
```bash
ngrok http 8000
```
Copy the generated `https://` forwarding URL (e.g. `https://a1b2-34-56-78-90.ngrok-free.app`) and append `/mcp`:
$$\rightarrow \text{\texttt{https://a1b2-34-56-78-90.ngrok-free.app/mcp}}$$

#### Step 2D: Configure Claude Connector UI
1. In Claude Web or Claude Code, open **Add custom connector**.
2. Set:
   * **Name**: `Storywriting & Screenplay Engine`
   * **Remote MCP server URL**: `https://a1b2-34-56-78-90.ngrok-free.app/mcp`
3. Click **Save / Connect**. All **67 tools, 4 resources, and 2 prompts** will be instantly available in Claude!

---

### 3. Setting Up in ChatGPT (GPT-4o)

You can use this MCP server with **ChatGPT (GPT-4o / O3-mini)** in two easy ways:

#### Option A: Inside Cursor / Antigravity / Windsurf IDEs (Recommended)
1. In your IDE MCP settings, add:
   ```json
   {
     "mcpServers": {
       "storywriting-engine": {
         "command": "d:\\Studio\\MCP -Storywriting\\venv\\Scripts\\python.exe",
         "args": ["d:\\Studio\\MCP -Storywriting\\server.py"]
       }
     }
   }
   ```
2. Select **GPT-4o** or **o3-mini** in the AI model dropdown.
3. ChatGPT will natively execute all 67 screenplay tools, draft prose, and render storyboards!

#### Option B: Via Open-WebUI / LibreChat / Custom GPT Actions
1. Launch the server in HTTP mode (`server.py --transport streamable-http --port 8000`).
2. Open **Open-WebUI Settings** $\rightarrow$ **Tools** $\rightarrow$ Add MCP Server URL: `http://localhost:8000/mcp`.
3. Select GPT-4o as your active LLM.

---

### 4. Live Integration with VS Code "Better Fountain" Extension

This server natively generates industry-standard Fountain 1.1 screenplay files (`.story/screenplay.fountain`).

1. Install the **Better Fountain** extension in VS Code.
2. Open `d:\Studio\MCP -Storywriting\.story\screenplay.fountain`.
3. Whenever Claude or the MCP engine commits screenplay scenes, **Better Fountain** instantly updates:
   - Live side-by-side formatted screenplay preview
   - Real-time page count and scene duration estimates
   - Interactive scene outline sidebar

---

## 16 Production Tool Categories (67 MCP Tools)

1. **Category A: Concept & Brainstorming (4 tools)**: `initialize_story_project`, `brainstorm_high_concept`, `develop_thematic_core`, `generate_title_bank`.
2. **Category B: Character Architect & Dynamics (4 tools)**: `create_character_profile`, `map_character_relationships`, `generate_character_backstory`, `generate_name_bank`.
3. **Category C: World-Building & Lore Engine (4 tools)**: `build_setting_location`, `define_world_rules`, `create_faction_or_culture`, `generate_world_timeline`.
4. **Category D: Structural Plotting & Beat Sheets (5 tools)**: `generate_beat_sheet`, `weave_subplots`, `outline_scene`, `calculate_pacing_and_stakes`, `import_one_line_orders_file`.
5. **Category E: Interactive Drafting Engine (5 tools)**: `draft_scene_prose`, `write_dialogue_pass`, `expand_sensory_details`, `propose_branching_options`, `generate_cliffhanger_or_twist`.
6. **Category F: Story Doctor & Continuity (4 tools)**: `check_narrative_continuity`, `scene_doctor_diagnostic`, `rebalance_show_vs_tell`, `analyze_pacing_and_rhythm`.
7. **Category G: Screenplay Adaptation & Export (4 tools)**: `narrative_to_scene_breakdown`, `generate_fountain_scene`, `export_screenplay`, `approve_and_commit_screenplay_scene`.
8. **Category H: Storyboard Engine (3 tools)**: `generate_storyboard_shotlist`, `update_frame_approval`, `render_storyboard_html`.
9. **Category I: Character Voice & Dialogue Polish (4 tools)**: `dialect_and_subtext_tuner`, `dialogue_rhythm_and_meter_analyzer`, `character_arc_tracker`, `generate_character_voice_bible`.
10. **Category J: Screenplay Timing & Analytics (4 tools)**: `estimate_screenplay_runtime`, `character_screen_time_matrix`, `scene_tension_and_pacing_heat_map`, `screenplay_table_read_simulator`.
11. **Category K: Visual Directing, Camera & Audio (5 tools)**: `soundtrack_and_audio_cues_designer`, `color_palette_and_lighting_guide`, `aspect_ratio_and_lens_advisor`, `scene_transitional_hook_generator`, `motif_and_symbolism_tracker`.
12. **Category L: Line Production & Stripboards (4 tools)**: `stripboard_element_breakdown`, `day_night_location_grouping`, `vfx_and_stunt_manifest`, `fountain_syntax_linter`.
13. **Category M: Pitch Deck & Marketing Suite (4 tools)**: `generate_pitch_deck_outline`, `generate_synopsis_suite`, `comparable_titles_analyzer`, `audience_emotional_engagement_predictor`.
14. **Category N: Writers' Room Mechanics (6 tools)**: `pitch_alternative_endings`, `generate_character_interview`, `red_herring_and_twist_architect`, `character_archetype_chemistry_analyzer`, `magic_or_tech_limitation_auditor`, `act_climax_escalator`.
15. **Category O: Multi-Format Exporters (5 tools)**: `comic_book_page_script_converter`, `fountain_to_epub_markdown`, `subtext_and_unspoken_desire_doctor`, `world_sensory_palette_builder`, `storyboard_frame_prompter`.
16. **Category P: Generic Batch Execution Engine (2 tools)**: `ingest_any_outline_file`, `generate_batch_screenplay`.

---

## ⚡ Quick Start: Running Local CLI Modes

```powershell
# Local stdio mode (Claude Desktop, Antigravity, Cursor)
& "d:\Studio\MCP -Storywriting\venv\Scripts\python.exe" server.py --transport stdio

# Streamable HTTP mode (Claude Connectors / Web UI / ChatGPT)
& "d:\Studio\MCP -Storywriting\venv\Scripts\python.exe" server.py --transport streamable-http --port 8000
```