Metadata-Version: 2.4
Name: narrateai-mcp
Version: 0.4.3
Summary: MCP server for NarrateAI - get timed transcript from silent video
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.15.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: uvicorn>=0.30.0

# NarrateAI MCP Server

MCP server that exposes NarrateAI's video-to-transcript flow as a tool. Upload a silent video (via URL), run frame analysis + workflow understanding + transcription, and get back a timed transcript with segments.

**No changes to the main app.** This is a standalone MCP server that calls your existing NarrateAI API.

## Prerequisites

1. **NarrateAI app running** — Backend (FastAPI) must be running, e.g. `uv run python main.py` or your production URL.
2. **API key** — Create one in the NarrateAI web app (Settings → API Keys).
3. **Video URL** — A public URL to an MP4 (e.g. S3 signed URL, GitHub raw, etc.).

## Install

From the project root:

```bash
cd mcp-server
uv sync
```

## Run locally (stdio)

```bash
cd mcp-server
NARRATEAI_API_KEY=your_key_here NARRATEAI_API_BASE_URL=http://localhost:8000 uv run python -m narrateai_mcp
```

Stdin/stdout are used for MCP protocol, so you won't see interactive output. Use this via Cursor or another MCP client.

## Cursor setup

1. Add your API key to `.cursor/mcp.json` (replace the empty `NARRATEAI_API_KEY`; avoid committing real keys):

   ```json
   {
     "mcpServers": {
       "narrateai": {
         "command": "uv",
         "args": ["run", "-C", "mcp-server", "python", "-m", "narrateai_mcp"],
         "env": {
           "NARRATEAI_API_BASE_URL": "http://localhost:8000",
           "NARRATEAI_API_KEY": "demo_sk_live_xxxx"
         }
       }
     }
   }
   ```

2. If your app runs elsewhere, set `NARRATEAI_API_BASE_URL` to that URL (e.g. `https://api.narrateai.app`).

3. Restart Cursor completely (quit and reopen).

4. In Cursor, the tools will appear. You can ask, e.g.:
   - "Use the narrate_video_transcript tool with this video URL: https://example.com/demo.mp4"
   - "Transcribe this video (it's in Spanish): https://example.com/podcast.mp4"

## Tool: transcribe_video

Transcription only: video with existing voice → speech-to-text → timed transcript. No translation.

| Argument       | Type   | Description                                                                 |
|----------------|--------|-----------------------------------------------------------------------------|
| video_source   | string | Public URL or local file path of the video.                                 |
| source_language| string | **REQUIRED.** Language of the speech (en, es, fr, zh, etc.). Ask user if not specified. |
| api_key        | string | (Optional) API key. Defaults to `NARRATEAI_API_KEY` env var.                |

**Returns:** JSON with `job_id`. Poll `get_job_result(job_id)` until `status` is `transcript_ready`.

## Tool: translate_video

Translation (new upload): video with voice → transcribe → translate → translated transcript.

| Argument        | Type   | Description                                                                 |
|-----------------|--------|-----------------------------------------------------------------------------|
| video_source    | string | Public URL or local file path.                                              |
| source_language | string | **REQUIRED.** Language of the speech.                                       |
| target_language | string | **REQUIRED.** Language to translate to.                                     |
| api_key         | string | (Optional) API key.                                                         |

**Returns:** JSON with `job_id`. Poll `get_job_result(job_id)` until `transcript_ready`.

## Tool: translate_existing_video

Translation (existing video): Translate transcript of a video already in the user's library. Sync – returns immediately.

| Argument        | Type   | Description                                                                 |
|-----------------|--------|-----------------------------------------------------------------------------|
| job_id          | string | Job ID of the completed video (from user's library).                       |
| source_language | string | **REQUIRED.** Language of the current transcript.                           |
| target_language | string | **REQUIRED.** Language to translate to.                                     |
| api_key         | string | (Optional) API key.                                                         |

**Returns:** JSON with `transcript`, `total_duration`, `total_words`.

## Tool: dub_video_full

Full auto-dubbing: transcribe → translate → extract speaker voice → TTS with cloned voice → dubbed video. No refinement screen.

| Argument                 | Type    | Description                                                                 |
|--------------------------|---------|-----------------------------------------------------------------------------|
| video_source             | string  | Public URL or local file path.                                             |
| source_language          | string  | **REQUIRED.** Language of the speech.                                       |
| target_language          | string  | **REQUIRED.** Language to dub into.                                        |
| preserve_background_music| boolean | **REQUIRED.** Ask user: keep background music (true) or not (false).        |
| api_key                  | string  | (Optional) API key.                                                         |

**Returns:** JSON with `job_id`. Poll `get_job_result(job_id)` until `status` is `completed`, then `video_url` has the dubbed video.

## Tool: narrate_video_transcript

| Argument          | Type   | Description                                                                 |
|-------------------|--------|-----------------------------------------------------------------------------|
| video_url         | string | Public URL of the video (MP4).                                              |
| api_key           | string | (Optional) API key. Defaults to `NARRATEAI_API_KEY` env var.                 |
| language          | string | Language code (en, es, fr, de, etc.). Default: en.                         |
| max_wait_seconds  | float  | Max time to wait for transcript. Default: 600.                             |

**Returns:** JSON with `transcript` (timed segments), `workflow_understanding`, `visual_timeline`, `total_duration`, `total_words`.

## Output format (transcript segments)

Each segment has:

- `start_time`, `end_time` (seconds)
- `text` — narration for that segment
- `duration`, `pause_duration`, `chunk_type`, `segment_id`

## Troubleshooting

- **"API key required"** — Set `NARRATEAI_API_KEY` in env or pass `api_key` to the tool.
- **"Temporary redirect service not available"** — Backend must have `USE_TEMP_REDIRECTS` and GCS configured.
- **"Transcript not ready" / timeout** — Video may be long or processing slow. Try a shorter clip or raise `max_wait_seconds`.
- **429 / rate limit** — Check your subscription tier and daily API limits in NarrateAI.
