Metadata-Version: 2.4
Name: chatcut-mcp-server
Version: 0.2.1
Summary: Model Context Protocol (MCP) server for local video editing, presentation overlays, transcription, and hardware-accelerated rendering.
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=0.1.0
Requires-Dist: Pillow>=9.1.0
Requires-Dist: pdf2image>=1.17.0
Requires-Dist: pandas>=2.2.1
Requires-Dist: openpyxl>=3.1.2
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: google-generativeai>=0.4.0
Requires-Dist: gTTS>=2.3.0
Requires-Dist: yt-dlp>=2026.3.17
Provides-Extra: ai
Requires-Dist: faster-whisper>=1.0.0; extra == "ai"
Requires-Dist: ultralytics>=8.0.0; extra == "ai"
Requires-Dist: opencv-python>=4.8.0; extra == "ai"

# ChatCut MCP Server 🎬🤖

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python: 3.10+](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
[![Model Context Protocol: 1.0](https://img.shields.io/badge/MCP-1.0-green.svg)](https://modelcontextprotocol.io/)

**ChatCut MCP Server** is a Model Context Protocol (MCP) server that empowers AI coding agents (such as **Claude Code**, **Cursor**, **Codex**, or **Antigravity**) with local video editing, media processing, transcription, and hardware-accelerated rendering capabilities.

With this server, you can give your AI agent natural language instructions like *"trim the silences from this video, overlay slide 2 at second 20, and render it using my GPU"* or *"transcribe this video, find the most engaging segment, and create a vertical 9:16 Short"*, and the agent will know exactly which tools to call to physically process the video on your local machine.

---

## 🛠️ Tools Reference

The server automatically registers the following tools with the MCP client:

| Tool Name | Arguments | Description |
| :--- | :--- | :--- |
| `detect_hardware` | None | Auto-detects the system's active GPU (NVIDIA, Apple Silicon, Intel, AMD) and checks if FFmpeg has hardware encoders enabled. |
| `parse_video_guidelines_excel` | `file_path: str` | Parses an Excel video editing guidelines file and outputs the cut ranges and slide overlay times in seconds. |
| `convert_pptx` | `pptx_path: str`, `output_dir: str` | Converts a PowerPoint presentation to PNG slides and pre-scales them to $1920 \times 1080$ in a cache directory (significantly speeds up FFmpeg rendering). |
| `transcribe_video_file` | `video_path: str`, `gemini_api_key: str` (optional), `force_local: bool` (optional) | Transcribes a video file to JSON with timestamps. Uses the Gemini API (cloud-based, free/fast) or **local Whisper** (`faster-whisper` running on CPU or GPU). |
| `find_short_clips` | `transcript_json: str`, `gemini_api_key: str` (optional) | Analyzes the transcript text and identifies the 3 best 30-60 second clips for vertical Shorts/Reels/TikToks with hook explanations. |
| `generate_vertical_crop_timeline` | `timeline_json_path: str`, `start_time: float`, `end_time: float`, `crop_type: str` (optional) | Creates a vertical (9:16) 1080x1920 timeline configuration, cropping or fitting the main video for the specified time segment. |
| `render_video_project` | `timeline_json_path: str`, `output_mp4_path: str` | Renders the final video from the timeline configuration using FFmpeg with GPU-accelerated encoding (e.g. `-c:v h264_nvenc`). |

---

## 🤖 INSTRUCTIONS FOR AI AGENTS (Claude Code / Codex / Antigravity)

If you are an AI agent reading this repository and the user has asked you to **"Install this MCP server"**, follow these steps based on the user's operating system:

### Step 1: Check System Dependencies
Ensure the user's system has `python` (>= 3.10), `ffmpeg`, and optionally `libreoffice` (required for `.pptx` conversions) installed. If they are missing, inform the user or request permission to install them.

### Step 2: Locate the MCP Client Configuration File
Locate the configuration file corresponding to the application the user is using to converse with you:

* **Claude Desktop (Windows)**: `%APPDATA%\Claude\claude_desktop_config.json`
* **Claude Desktop (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Claude Desktop (Linux)**: `~/.config/Claude/claude_desktop_config.json`
* **Claude Code (Global CLI)**: `~/.claude.json`
* **Cursor (IDE)**: Configurable in the *Settings -> Features -> MCP* section of the graphical interface.

### Step 3: Add the Server to Configuration
Read the configuration JSON file and append a new entry under the `"mcpServers"` key.

#### Option A: Install from PyPI (Recommended for production)
```json
"chatcut": {
  "command": "uvx",
  "args": ["chatcut-mcp-server"],
  "env": {
    "GEMINI_API_KEY": "YOUR_OPTIONAL_API_KEY"
  }
}
```

#### Option B: Install from Local Source (Recommended for development/WSL)
```json
"chatcut-local": {
  "command": "wsl",
  "args": [
    "-d", "Ubuntu",
    "-u", "parrot",
    "bash", "-c",
    "cd /home/parrot/video && venv/bin/chatcut-mcp-server"
  ],
  "env": {
    "GEMINI_API_KEY": "YOUR_OPTIONAL_API_KEY"
  }
}
```

Write the configuration back, preserving all other existing keys.

---

## 👨‍💻 HUMAN INSTALLATION GUIDE

### Option A: Automatic Running (Recommended)
If you have `uv` installed on your system, you can run the server instantly without a permanent installation using `uvx`:

```bash
uvx chatcut-mcp-server
```

### Option B: Local Source Installation
1. Clone the repository:
   ```bash
   git clone git@github.com:madrigal-a/chatcut-mcp-server.git
   cd chatcut-mcp-server
   ```
2. Create a virtual environment and install the package in editable mode:
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows use: venv\Scripts\activate
   pip install -e .
   ```
3. Run the server:
   ```bash
   chatcut-mcp-server
   ```

---

## 📝 Additional System Requirements
* **LibreOffice headless**: Required for automated PPTX to PDF conversions. On Ubuntu, install it using `sudo apt-get install libreoffice`.
* **Poppler-utils**: Required by `pdf2image` to extract pages from PDF files. On Ubuntu, install it using `sudo apt-get install poppler-utils`.
