Metadata-Version: 2.4
Name: creativai-mcp
Version: 0.1.6
Summary: MCP server for the CreativAI Video Intelligence Platform
Author-email: CreativAI <support@creativai.io>
License: Proprietary
Keywords: ai,creativai,mcp,model-context-protocol,video
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: creativai>=0.1
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2.0,>=1.27
Requires-Dist: python-dotenv>=1.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# creativai-mcp

MCP (Model Context Protocol) server for the [CreativAI](https://creativ-ai.com) Video Intelligence Platform.

Connect any MCP-compatible AI assistant (Claude, Cursor, VS Code Copilot, etc.) directly to your CreativAI video library — search, index, extract knowledge, manage collections, run live streams, import from YouTube, and more — all through natural language.

## Installation

```bash
pip install creativai-mcp
```

## Quick Start

```bash
creativai-mcp --api-key YOUR_API_KEY
```

Or set the environment variable:

```bash
export CREATIVAI_API_KEY=YOUR_API_KEY
creativai-mcp
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "creativai": {
      "command": "creativai-mcp",
      "args": ["--api-key", "YOUR_API_KEY"]
    }
  }
}
```

### VS Code / GitHub Copilot

Add to your VS Code `settings.json`:

```json
{
  "mcp": {
    "servers": {
      "creativai": {
        "type": "stdio",
        "command": "creativai-mcp",
        "args": ["--api-key", "YOUR_API_KEY"]
      }
    }
  }
}
```

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "creativai": {
      "command": "creativai-mcp",
      "args": ["--api-key", "YOUR_API_KEY"]
    }
  }
}
```

## Available Tools

### Collections

| Tool | Description |
|------|-------------|
| `list_collections` | List all video collections in your account |
| `create_collection` | Create a new video collection (`video_only` or `multimodal`) |
| `get_collection` | Get full details for a single collection |
| `update_collection` | Rename a collection |
| `delete_collection` | ⚠️ Permanently delete a collection and all its data |

### Media

| Tool | Description |
|------|-------------|
| `list_media` | List all media files in a collection with preprocessing status |
| `get_upload_url` | Get a presigned S3 upload URL for a single file |
| `get_upload_urls` | Get presigned S3 upload URLs for multiple files at once |
| `upload_from_url` | Import a video from an external URL or S3 URI (async) |
| `get_transfer_status` | Poll the status of a URL-to-collection transfer job |
| `delete_media` | ⚠️ Permanently remove specific media files from a collection |

### Search

| Tool | Description |
|------|-------------|
| `search_collection` | Semantic search over an indexed collection — vision, audio, or hybrid |

### Indexing

| Tool | Description |
|------|-------------|
| `start_indexing` | Start an async indexing job to make a collection searchable |
| `get_indexing_status` | Poll the status of a running indexing job |
| `estimate_indexing_cost` | Estimate credit cost before starting indexing |
| `cancel_indexing` | Cancel a running indexing job |
| `index_and_wait` | Start indexing and block until completion (convenience tool) |

### Agentic Chat

| Tool | Description |
|------|-------------|
| `ask_collection` | Ask a natural-language question about a collection — one-shot |
| `create_chat_session` | Create a multi-turn chat session for a collection |
| `send_chat_message` | Send a follow-up message to an existing chat session |
| `get_chat_history` | Get the full message history of a chat session |
| `list_chat_sessions` | List chat sessions, optionally filtered by collection |
| `delete_chat_session` | Delete a chat session |

### Data Plates

| Tool | Description |
|------|-------------|
| `list_data_plates` | List all data plates in a collection |
| `get_data_plate` | Get a data plate with its paginated segments |
| `create_data_plate_from_collection` | Create a data plate from all indexed segments (async) |
| `get_data_plate_job` | Poll the status of a data plate creation job |
| `delete_data_plate` | ⚠️ Permanently delete a data plate and its extracted data |

### Knowledge Extraction

| Tool | Description |
|------|-------------|
| `query_knowledge_plate` | Ask a natural-language question against a knowledge plate |
| `add_extraction_columns` | Add AI extraction questions as columns to a knowledge plate |
| `list_extraction_columns` | List all extracted columns in a knowledge plate |
| `get_knowledge_extraction_job` | Poll the status of a knowledge extraction job |
| `get_plate_charts` | Get auto-generated charts and visualizations for a plate |

### Live Stream

| Tool | Description |
|------|-------------|
| `create_live_stream_session` | Create a live stream session for real-time video analysis |
| `list_live_stream_sessions` | List live stream sessions, optionally filtered by collection |
| `get_live_stream_session` | Get full details for a live stream session |
| `stop_live_stream_session` | Stop an active live stream session |
| `add_live_stream_questions` | Add real-time analysis questions to a running session |
| `get_live_stream_status` | Check if a live stream session is ready (workers + MediaMTX) |

### Online Search (Web Video Import)

| Tool | Description |
|------|-------------|
| `start_online_search` | Start a web search job to find publicly available videos |
| `get_online_search_status` | Poll the status of an online search job |
| `list_online_search_candidates` | List candidate videos found by an online search |
| `confirm_online_search` | Confirm all candidates and start importing + indexing |
| `search_and_import` | Blocking convenience tool: search web and return candidates |

### YouTube

| Tool | Description |
|------|-------------|
| `start_youtube_search` | Start a YouTube search — refines query into optimized search terms |
| `get_youtube_search_status` | Poll the status of a YouTube search job |
| `list_youtube_candidates` | List candidate YouTube videos found for a search job |
| `confirm_youtube_search` | Confirm all YouTube candidates and trigger import + indexing |
| `confirm_selected_youtube_videos` | Confirm only specific YouTube videos for import |

### Organizations & Projects

| Tool | Description |
|------|-------------|
| `list_organizations` | List all organizations you are a member of |
| `get_organization` | Get details for a specific organization |
| `list_projects` | List all projects in an organization |
| `get_project` | Get a project and its collections |

### Tasks

| Tool | Description |
|------|-------------|
| `list_tasks` | List annotation/review tasks in a collection |
| `get_task` | Get detailed information about a specific task |
| `my_tasks` | List all tasks assigned to you across all collections |
| `update_task_status` | Update the status of a task |
| `add_task_comment` | Add a comment to a task |

### Account & Users

| Tool | Description |
|------|-------------|
| `get_account_info` | Get your account info (credits, plan, uploaded hours) |
| `get_credits` | Get your current credit balance and usage stats |
| `get_current_user` | Get the current authenticated user's ID and email |

## Transports

**stdio** (default — for desktop AI clients):
```bash
creativai-mcp --transport stdio --api-key YOUR_API_KEY
```

**SSE** (for remote/web clients):
```bash
creativai-mcp --transport sse --host 0.0.0.0 --port 8090 --api-key YOUR_API_KEY
```

## Requirements

- Python 3.10+
- A CreativAI API key — get one at [creativ-ai.com](https://creativ-ai.com)

## License

Proprietary — © CreativAI
