mootoo4499/KS_Screenwriter

KS_Screenwriter

A comprehensive Python MCP (Model Context Protocol) server for parsing Fountain screenplay files and creating knowledge graphs in Neo4j. This project provides tools for screenplay analysis, conversion, and graph-based data management.

Note: This is a personal copy of the original screenwriter repository, customized for Kevin's development needs.

Features

• Fountain Parser: Parse Fountain screenplay files into structured data
• Neo4j Integration: Create and manage knowledge graphs in Neo4j database
• Screenplay Conversion: Convert plain text screenplays to Fountain format
• Character Resolution: AI-powered character name resolution using OpenAI
• MCP Server: Expose functionality through Model Context Protocol
• Batch Processing: Process multiple screenplays efficiently
• Quality Control: Validate and format Fountain files

Architecture

The project follows a modular architecture with clear separation of concerns:

• Parser: Core parsing logic for Fountain files
• Schemas: Pydantic models for all screenplay elements
• Converter: Tools for converting plain text to Fountain format
• MCP Server: API endpoints for external access
• Character Resolver: AI-powered character name resolution

Installation

Prerequisites

• Python 3.12+
• Neo4j database
• Docker (for Neo4j container)

Setup

1. Clone the repository:

   git clone <repository-url>
   cd screenwriter
   

2. Install dependencies:

   uv sync
   

3. Set up environment variables: Create a .env file with the following variables:

   SCREENWRITER_NEO4J_URI=bolt://localhost:7687
   SCREENWRITER_NEO4J_USER=neo4j
   SCREENWRITER_NEO4J_PASSWORD=somepassword
   SCREENWRITER_OPENROUTER_API_KEY=your-api-key
   SCREENWRITER_NEO4J_IMPORT_DIR=/absolute/path/to/neo4j_import
   

4. Start Neo4j database:

   docker compose up -d
   

Usage

MCP Server Setup

To use the MCP server in Cursor, create a .cursor/mcp.json file:

{
  "mcpServers": {
    "screenwriter": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/screenwriter",
        "run",
        "screenwriter-mcp"
      ],
      "env": {
        "SCREENWRITER_NEO4J_URI": "bolt://localhost:7687",
        "SCREENWRITER_NEO4J_USER": "neo4j",
        "SCREENWRITER_NEO4J_PASSWORD": "somepassword",
        "SCREENWRITER_OPENROUTER_API_KEY": "your-api-key",
        "SCREENWRITER_NEO4J_IMPORT_DIR": "/absolute/path/to/neo4j_import"
      }
    }
  }
}

Available MCP Tools

• sync_knowledge_graph: Parse a Fountain file and create a knowledge graph
• get_schema: Get the Neo4j database schema
• delete_everything: Clear all data from the database
• format_fountain_file: Format or validate Fountain files
• line_range_to_elements: Get elements within a line range
• element_ids_to_line_ranges: Get line ranges for specific elements
• convert_screenplay_to_fountain: Convert plain text to Fountain format
• batch_convert_screenplays: Convert multiple screenplays

Python API

from screenwriter.parser import Parser
from screenwriter.converter import ScreenplayToFountain

# Parse a Fountain file
parser = await Parser.from_file(Path("script.fountain"))

# Convert plain text to Fountain
converter = ScreenplayToFountain()
result = converter.convert_file(Path("script.txt"), Path("script.fountain"))

Project Structure

screenwriter/
├── src/screenwriter/
│   ├── __init__.py
│   ├── mcp.py                 # MCP server implementation
│   ├── parser.py              # Core parsing logic
│   ├── schemas.py             # Pydantic models
│   ├── config.py              # Configuration settings
│   ├── character_resolver.py  # AI character resolution
│   ├── dependencies.py        # Dependency injection
│   └── converter/             # Screenplay conversion tools
│       ├── __init__.py
│       ├── converter.py       # Main converter
│       ├── patterns.py        # Pattern matching
│       ├── cleaner.py         # Text cleaning
│       ├── validator.py       # Validation logic
│       └── batch_processor.py # Batch processing
├── tests/                     # Test suite
├── fountain_scripts/          # Sample Fountain files
├── tools/                     # Command-line tools
├── pyproject.toml            # Project configuration
└── README.md

Database Schema

The Neo4j knowledge graph uses the following structure:

Nodes (PascalCase)

• TitlePage: Script title page
• Scene: Individual scenes
• Character: Character entities
• Action: Action/description elements
• Dialogue: Character dialogue
• SceneHeading: Scene headings
• CharacterAppearance: Character appearances in scenes
• Parenthetical: Parenthetical elements
• Transition: Scene transitions
• Note: Script notes
• Boneyard: Comment blocks
• Section: Script sections
• Synopsis: Scene synopses
• PageBreak: Page breaks
• Metadata: Script metadata

Relationships (ALL_CAPS)

• PRECEDES_ELEMENT: Element ordering
• BELONGS_TO: Scene membership
• SPOKEN_BY: Dialogue attribution
• IS_CHARACTER: Character identification
• MODIFIES: Parenthetical relationships
• IS_PART_OF: Title page membership
• PRECEDES_SCENE: Scene ordering

Development

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/screenwriter

# Run specific test file
uv run pytest tests/test_parser.py

Code Quality

The project uses several tools for code quality:

• Ruff: Linting and formatting
• MyPy: Type checking
• Pytest: Testing framework
• Pydantic: Data validation

Adding New Features

1. Create feature branch
2. Add tests for new functionality
3. Implement the feature
4. Run quality checks
5. Submit pull request

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run quality checks
6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with Fountain Tools for Fountain parsing
• Uses Neo4j for graph database
• Powered by OpenAI for character resolution
• Implements Model Context Protocol for AI integration