Metadata-Version: 2.4
Name: mcp-video-pipeline_2
Version: 0.1.1
Summary: MCP server for generating algorithm explanation videos
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.3.0
Requires-Dist: google-generativeai>=0.8.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: python-dotenv>=1.0.1

# AI Video Pipeline — MCP Server

> **This pipeline helps you make algorithm-explanation videos with minimal manual work.**
> Claude Desktop calls these tools automatically — you just describe your video idea and follow the steps.

---

## 🗺️ How the Pipeline Works

```
Your Idea (topic + gist)
       │
       ▼
  [Tool 1] Script Generator       ← Claude writes your full narration script
       │
       ▼
  You record the voiceover
  Premiere Pro → export timestamped transcript
       │
       ▼
  [Tool 2] Scene Planner          ← splits transcript into visual scenes
       │
       ├── for image scenes →
       │   [Tool 3] Image Prompt Generator  ← paste into Whisk / Midjourney
       │
       └── for animation scenes →
           [Tool 4] Animation Generator     ← generates Manim Python code
```

---

## 📋 Prerequisites

Before starting, you need:

| Requirement | How to get it |
|---|---|
| **Python 3.10+** | [python.org/downloads](https://www.python.org/downloads/) |
| **Claude Desktop** | [claude.ai/download](https://claude.ai/download) |
| **Free Gemini API key** | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) — no credit card |
| **Premiere Pro** (for transcripts) | Any version with SRT caption export |
| **(Optional) Manim** | Only if you want equation animations — install separately |

---

## 🚀 Setup (Step by Step)

### Step 1 — Clone / Download the Project

Put the `mcp_video_pipeline` folder somewhere easy to find.  
Example location: `C:\Proj\DD\mcp_video_pipeline\`

---

### Step 2 — Install Python Dependencies

Open **Command Prompt** or **PowerShell**, then run:

```powershell
cd C:\Proj\DD\mcp_video_pipeline
pip install -r requirements.txt
```

You should see packages being downloaded. This takes 1-2 minutes.

---

### Step 3 — Get Your Free Gemini API Key

1. Go to: **https://aistudio.google.com/apikey**
2. Sign in with your Google account.
3. Click **"Create API Key"**.
4. Copy the key (it looks like: `AIzaSy...`).

**Free limits:** 15 requests/minute, 1 million tokens/day. More than enough for video production.

---

### Step 4 — Set Up Your API Key

In the `mcp_video_pipeline` folder:

1. Find the file called `.env.example`
2. Make a copy of it and name the copy exactly: **`.env`** (just dot-env, no .example)
3. Open `.env` in Notepad and replace `your_free_gemini_api_key_here` with your actual key

```
GEMINI_API_KEY=AIzaSyYOUR_ACTUAL_KEY_HERE
```

Save the file.

---

### Step 5 — Configure Claude Desktop

1. Open the file `claude_desktop_config.json` (in this project folder) — it shows you what to copy.

2. Find Claude Desktop's config file:
   - **Windows:** Press `Win+R`, type `%APPDATA%\Claude\`, press Enter
   - Open `claude_desktop_config.json` in Notepad (create it if missing)

3. Your config file should look like this — add the `mcpServers` block:

```json
{
  "mcpServers": {
    "ai-video-pipeline": {
      "command": "python",
      "args": ["C:\\Proj\\DD\\mcp_video_pipeline\\server.py"]
    }
  }
}
```

> ⚠️ **Important:** Update the path if your project is in a different location.  
> Use double backslashes `\\` in the path (this is a Windows JSON requirement).

4. Save the file.

5. **Fully quit and restart Claude Desktop** (right-click the tray icon → Quit, then reopen).

---

### Step 6 — Verify It's Working

In Claude Desktop, look for a **🔧 tools icon** (hammer icon) in the chat bar.  
Clicking it should show 4 tools:
- `generate_script`
- `plan_scenes`
- `generate_image_prompt`
- `generate_animation_code`

If you don't see them: see the Troubleshooting section below.

---

## 🎬 Using the Pipeline

### Stage 1: Generate Your Script

Tell Claude something like:

> *"I want to make a video about Dijkstra's shortest path algorithm. The tagline is 'How GPS knows the fastest route.' The gist is: Dijkstra's finds the cheapest path in a weighted graph. It's used in GPS and internet routing. Make it 10 minutes."*

Claude will call the `generate_script` tool and return:
- Full narration script
- Key equations used
- Metaphors used

**Review the script. Make edits if needed.**

---

### Stage 2: Record & Transcribe (You Do This)

1. Record yourself reading the script naturally.
2. In Premiere Pro:
   - Go to **Window → Text → Transcript**
   - Click **"Transcribe Sequence"**
   - Once done, export as SRT or copy the text with timestamps
3. Format: `[HH:MM:SS] spoken words...` per line

---

### Stage 3: Plan Your Scenes

Paste the transcript and tell Claude:

> *"Here is my transcript: [paste transcript here]. Plan the scenes for me."*

Claude calls `plan_scenes` and returns a table of scenes with timestamps, descriptions, and types (image or animation).

---

### Stage 4: Generate Visuals

For each `image` scene, Claude automatically calls `generate_image_prompt`.  
You get a ready-to-paste prompt for Whisk, Midjourney, Firefly, or any image AI.

For each `animation` scene, Claude calls `generate_animation_code`.  
You get a Python file. To render:

```powershell
pip install manim
manim -pql animation_scene.py YourSceneName
```

---

## 🔧 Troubleshooting

| Problem | Fix |
|---|---|
| Tools not showing in Claude Desktop | Check the path in `claude_desktop_config.json` is correct. Fully restart Claude (not just close window). |
| `GEMINI_API_KEY is not set` error | Make sure your `.env` file exists (not `.env.example`) and the key is correct. |
| `pip: command not found` | Install Python from python.org and check "Add to PATH" during install. |
| 429 Rate Limit error | You've sent 15 requests in under a minute. Wait 60 seconds and retry. |
| Manim LaTeX error | Install MiKTeX from miktex.org (Windows). Required for equation rendering. |
| JSON parse error in tools | Retry — occasionally Gemini may return slightly malformed JSON. Rare. |

---

## 📁 Project File Map

```
mcp_video_pipeline/
├── server.py                    ← MCP server entry-point (start here to understand the project)
├── requirements.txt             ← Python packages
├── .env.example                 ← Copy → .env and add your Gemini key
├── claude_desktop_config.json   ← Snippet for Claude Desktop setup
├── README.md                    ← This file
├── tools/
│   ├── script_generator.py      ← Tool 1: Video script generation
│   ├── scene_planner.py         ← Tool 2: Transcript → scene list
│   ├── image_prompt_generator.py ← Tool 3: Scene → AI image prompt
│   └── animation_generator.py   ← Tool 4: Scene → Manim Python code
└── utils/
    ├── model_client.py          ← Gemini API calls (shared by all tools)
    └── schemas.py               ← Data validation models
```

---

## 🤖 Free Model Details

| Detail | Value |
|---|---|
| Model | `gemini-2.0-flash` |
| Provider | Google AI Studio |
| Cost | **Free** |
| Rate limit | 15 requests/minute |
| Daily limit | 1,000,000 tokens/day |
| Context window | 1,000,000 tokens |
| API key required | Yes (free, no credit card) |

To switch models, edit the `GEMINI_MODEL` line in your `.env` file.

---

## ✅ Testing Without Claude Desktop (Developer Mode)

```powershell
cd C:\Proj\DD\mcp_video_pipeline
mcp dev server.py
```

Open `http://localhost:5173` in your browser. You'll see the MCP Inspector — a UI to test each tool individually with sample inputs.
