A new tool called slugline-mcp has been released on PyPI that provides screenplay analysis using retrieval-augmented generation over a database of real film scripts. The tool applies evidence-based methods to help writers and analysts evaluate screenplays against established industry standards.
MCP server for brutal, evidence-based screenplay analysis via retrieval over a reference database of real scripts.
Mood, next-action suggestions, and "X meets Y" comparisons, backed by retrieval over ~2,200 real screenplays. One MCP server. Zero vibes-based feedback.
Under the hood: a full Retrieval-Augmented Generation (RAG) pipeline — chunking, vector embeddings, semantic search, and local zero-shot classification — exposed entirely as Model Context Protocol (MCP) tools, with zero LLM calls from the server itself.
slugline-mcp doesn't write or judge your scene itself — it retrieves real produced scenes similar to yours (or matching a mood you're chasing) so your own connected Claude can ground its feedback in evidence instead of guessing. It's the retrieval half of RAG, full stop: parse, embed, index, and semantically search real screenplays, then hand that grounded evidence to Claude over MCP.
Try it once it's runnable end-to-end (see the roadmap below):
Full story reconstructed from Pypi.org. Formatting and media may differ from the original.
A screen recording is still coming (see the roadmap below), but docs/demo_walkthrough.md has a full text walkthrough with real tool output — including both the precise tag-matched and semantic-fallback paths of find_mood_reference_scenes — captured against an actual local test index, not fabricated.
slugline-mcp is an MCP (Model Context Protocol) server for screenwriters. It's a retrieval-only RAG pipeline: it parses a reference database of real movie screenplays into scenes, embeds them, and exposes semantic search over that index as MCP tools. The LLM doing the actual writing and judgment is your own Claude, connected locally — this server never calls out to an LLM itself, it just supplies the evidence.
Two engineering ideas this project is built around:
RAG, done properly: real chunking (screenplay scenes, not arbitrary token windows), a purpose-fit embedding model, a persistent vector store, and metadata filtering (mood tags computed once at index time) layered on top of semantic similarity — not just "stuff everything into a prompt."
MCP, done properly: five tools with schemas an LLM can actually reason about (Annotated[..., Field(description=...)] throughout tools/), including a dedicated get_analysis_style tool whose whole job is steering how the calling LLM uses the other four — prompt engineering expressed as a callable tool, not a static system prompt.
Reference data comes from rohitsaxena/MovieSum, a public Hugging Face dataset of ~2,200 movie screenplays, pre-structured into scenes with dialogue and stage directions.
Index time (once, offline, in indexing/build_index.py):
Parse — MovieSum's screenplay XML (or a user's raw pasted script, via a separate plain-text splitter) is split into scenes, not arbitrary chunks — a scene is the natural retrieval unit for screenplay feedback.
Embed — each scene's flattened text is encoded with sentence-transformers/all-MiniLM-L6-v2 into a 384-dim vector.
Classify — each scene is also run once through a local zero-shot classifier (facebook/bart-large-mnli) against a fixed mood taxonomy, so mood becomes a stored metadata field instead of something re-inferred on every query.
Query time (every MCP tool call, in retrieval.py):
Chroma runs approximate nearest-neighbor search over the stored vectors — optionally pre-filtered by metadata (e.g. mood == "paranoid") before ranking by similarity.
Results are formatted into a canonical scene shape and returned as MCP tool output — raw evidence, not a generated answer.
Retrieval and generation are fully decoupled here: this server only ever does the retrieval half, and the MCP tool boundary is exactly where that handoff happens.
From PyPI: not yet published — see the roadmap below (Phase 8).
See docs/claude_desktop.md for the full config example (dev mode today; a simpler uvx slugline-mcp config once published).
The server needs a populated Chroma index to retrieve from. See docs/dataset.md for building one locally from MovieSum, and src/slugline_mcp/indexing/bootstrap.py for how published builds will fetch a prebuilt one automatically.
See docs/testing.md for testing tools interactively with the MCP Inspector.
Once slugline-mcp is connected (see Add it to Claude Desktop above), just talk to Claude normally — paste a scene, describe what you're stuck on, or ask for a comparison. Claude decides which tools to call; you never call them directly.
Paste a scene and ask for feedback. Claude calls get_analysis_style first (it's designed to steer the whole interaction), then search_similar_scenes with your scene's text to pull real comparable scenes from the reference index.
Claude cites specific movies and scenes, not vague genre talk — if it says "this reads like a beat from 8MM," that's because search_similar_scenes actually returned that scene.
Ask to see the full match. "Show me that whole scene" prompts Claude to call get_scene_details with the id from the earlier search result.
Ask for a mood rewrite. "Make this scene feel more paranoid" prompts find_mood_reference_scenes("paranoid") — Claude gets back real scenes that strongly hit that mood, plus whether the match was precise (tag_matched) or a broader semantic guess (semantic_fallback).
Ask what's in the reference set. "What movies do you have indexed?" calls list_indexed_movies.
Every tool degrades gracefully instead of erroring if no reference index is available yet (see retrieval.py) — you'll get empty results rather than a crash. If that happens:
Confirm a Chroma index exists at ~/.slugline-mcp/chroma (or wherever SLUGLINE_MCP_PERSIST_DIR points).
If not, either wait for bootstrap.py to fetch the prebuilt index, or build one yourself (see docs/dataset.md).
See TASKS.md for the full task-by-task build checklist.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
Details for the file slugline_mcp-0.1.0.tar.gz.
Details for the file slugline_mcp-0.1.0-py3-none-any.whl.
