creativai-mcp 0.1.0__tar.gz

creativai_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,55 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"    # trigger on v0.1.0, v1.2.3, etc.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write   # required for PyPI trusted publishing (OIDC)
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install hatchling build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # environment: pypi    # uncomment once OIDC trusted publisher is configured on pypi.org
+
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          skip-existing: true

creativai_mcp-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+.env
+
+# Environment / secrets — NEVER commit API keys
+.env
+.env.*
+!.env.example
+
+# pytest
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+
+# mypy
+.mypy_cache/
+.dmypy.json
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*~
+
+# macOS
+.DS_Store
+
+# Distribution / packaging
+MANIFEST
+pip-wheel-metadata/

creativai_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: creativai-mcp
+Version: 0.1.0
+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>=1.0
+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, and manage collections 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
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "creativai": {
+        "type": "stdio",
+        "command": "creativai-mcp",
+        "args": ["--api-key", "YOUR_API_KEY"]
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_collections` | List all video collections |
+| `get_collection` | Get collection details |
+| `list_media` | List media in a collection |
+| `search_videos` | Semantic search across your library |
+| `start_indexing` | Index a video for AI search |
+| `get_indexing_status` | Check indexing progress |
+| `cancel_indexing` | Cancel an in-progress indexing job |
+| `extract_knowledge` | Extract structured knowledge from video |
+| `list_data_plates` | List all data plates |
+| `get_data_plate_segments` | Get segments from a data plate |
+| `list_organizations` | List organizations |
+| `list_projects` | List projects in an organization |
+
+## Transports
+
+**stdio** (default — for desktop AI clients):
+```bash
+creativai-mcp --transport stdio --api-key YOUR_API_KEY
+```
+
+**HTTP/SSE** (for remote/web clients):
+```bash
+creativai-mcp --transport http --host 0.0.0.0 --port 8080 --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

creativai_mcp-0.1.0/README.md

@@ -0,0 +1,93 @@
+# 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, and manage collections 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
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "creativai": {
+        "type": "stdio",
+        "command": "creativai-mcp",
+        "args": ["--api-key", "YOUR_API_KEY"]
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_collections` | List all video collections |
+| `get_collection` | Get collection details |
+| `list_media` | List media in a collection |
+| `search_videos` | Semantic search across your library |
+| `start_indexing` | Index a video for AI search |
+| `get_indexing_status` | Check indexing progress |
+| `cancel_indexing` | Cancel an in-progress indexing job |
+| `extract_knowledge` | Extract structured knowledge from video |
+| `list_data_plates` | List all data plates |
+| `get_data_plate_segments` | Get segments from a data plate |
+| `list_organizations` | List organizations |
+| `list_projects` | List projects in an organization |
+
+## Transports
+
+**stdio** (default — for desktop AI clients):
+```bash
+creativai-mcp --transport stdio --api-key YOUR_API_KEY
+```
+
+**HTTP/SSE** (for remote/web clients):
+```bash
+creativai-mcp --transport http --host 0.0.0.0 --port 8080 --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

creativai_mcp-0.1.0/creativai_mcp/__init__.py

@@ -0,0 +1,8 @@
+"""
+CreativAI MCP — package root.
+"""
+
+from .server import build_server, main
+
+__all__ = ["build_server", "main"]
+__version__ = "0.1.0"

creativai_mcp-0.1.0/creativai_mcp/auth.py

@@ -0,0 +1,35 @@
+"""
+CreativAI MCP — auth helper.
+
+Resolves the API key from (in order):
+1. Explicit argument
+2. CREATIVAI_API_KEY environment variable
+3. ~/.creativai/config file (key=value format)
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def resolve_api_key(api_key: str | None = None) -> str:
+    """Return an API key or raise RuntimeError if none is found."""
+    if api_key:
+        return api_key
+
+    env_key = os.environ.get("CREATIVAI_API_KEY", "").strip()
+    if env_key:
+        return env_key
+
+    config_path = Path.home() / ".creativai" / "config"
+    if config_path.exists():
+        for line in config_path.read_text().splitlines():
+            line = line.strip()
+            if line.startswith("api_key") and "=" in line:
+                return line.split("=", 1)[1].strip()
+
+    raise RuntimeError(
+        "No CreativAI API key found. "
+        "Set the CREATIVAI_API_KEY environment variable or pass api_key= explicitly."
+    )

creativai_mcp-0.1.0/creativai_mcp/prompts/__init__.py

@@ -0,0 +1,77 @@
+"""
+CreativAI MCP — Prompt templates.
+
+Pre-defined prompts that help users get the most out of CreativAI tools.
+"""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+
+def register(mcp: FastMCP) -> None:
+
+    @mcp.prompt()
+    def video_analysis_workflow(collection_name: str, topic: str) -> str:
+        """Generate a step-by-step workflow to analyze videos on a topic.
+
+        Args:
+            collection_name: Name of the collection to create.
+            topic: Topic or domain of the videos (e.g. 'factory safety').
+        """
+        return f"""You are a video intelligence analyst using CreativAI tools.
+
+Follow this workflow to analyze {topic} videos in the '{collection_name}' collection:
+
+1. **Check existing collections** — Call list_collections to see if '{collection_name}' already exists.
+2. **Create collection** — If not found, call create_collection('{collection_name}').
+3. **Add media** — Call get_upload_url to get presigned URLs for your video files, then upload them.
+4. **Index** — Call start_indexing with the collection_id, then poll get_indexing_status until status='completed'.
+5. **Search** — Call search_collection to find relevant clips about {topic}.
+6. **Deep analysis** — Call ask_collection to get an AI-synthesized analysis of {topic} patterns.
+7. **Structured extraction** — Call create_data_plate_from_collection, then add_extraction_columns to extract specific facts about {topic}.
+
+Start by calling list_collections to check what already exists."""
+
+    @mcp.prompt()
+    def safety_audit_workflow(collection_id: str) -> str:
+        """Generate a safety audit workflow for a video collection.
+
+        Args:
+            collection_id: The collection to audit.
+        """
+        return f"""You are a safety compliance auditor using CreativAI video intelligence.
+
+Perform a comprehensive safety audit of collection '{collection_id}':
+
+1. **Search for violations** — Call search_collection('{collection_id}', 'safety violation PPE missing hard hat')
+2. **Search for hazards** — Call search_collection('{collection_id}', 'unsafe behavior near machinery equipment')  
+3. **Ask for summary** — Call ask_collection('{collection_id}', 'Summarize all safety incidents, PPE compliance rate, and top risk areas observed in the footage')
+4. **Extract structured data** — Call create_data_plate_from_collection('{collection_id}'), then add_extraction_columns with:
+   - {{'name': 'ppe_worn', 'question': 'Is the worker wearing required PPE (hard hat, vest, gloves)?'}}
+   - {{'name': 'safety_violation', 'question': 'Is there a safety violation visible? Describe it.'}}
+   - {{'name': 'risk_level', 'question': 'Rate the safety risk level: low, medium, or high'}}
+5. **Query the data** — Call query_knowledge_plate to ask 'What percentage of segments show PPE violations?'
+
+Begin with step 1."""
+
+    @mcp.prompt()
+    def search_and_report(collection_id: str, search_query: str) -> str:
+        """Search a collection and produce a structured report.
+
+        Args:
+            collection_id: Collection to search.
+            search_query: What to look for.
+        """
+        return f"""Search the collection '{collection_id}' for '{search_query}' and produce a structured report.
+
+Steps:
+1. Call search_collection('{collection_id}', '{search_query}', limit=20)
+2. Call ask_collection('{collection_id}', 'Provide a detailed report on {search_query}: frequency, patterns, timestamps, and key observations')
+3. Format the findings as a report with:
+   - Executive Summary
+   - Key Findings (with timestamps)
+   - Frequency / Statistics  
+   - Recommendations
+
+Start with the search."""

creativai_mcp-0.1.0/creativai_mcp/resources/__init__.py

@@ -0,0 +1,92 @@
+"""
+CreativAI MCP — MCP Resources.
+
+Exposes collections and search results as readable MCP resources
+at creativai:// URIs.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from mcp.server.fastmcp import FastMCP
+
+
+def register(mcp: FastMCP, get_client: Any) -> None:
+
+    @mcp.resource("creativai://collections")
+    def resource_list_collections() -> str:
+        """All video collections in your CreativAI account.
+
+        Returns JSON list of collections with IDs, names, model, video count.
+        """
+        client = get_client()
+        result = client.collections.list()
+        collections = result if isinstance(result, list) else result.get("collections", result.get("data", []))
+        return json.dumps(collections, indent=2)
+
+    @mcp.resource("creativai://collections/{collection_id}")
+    def resource_get_collection(collection_id: str) -> str:
+        """Details and media list for a specific collection.
+
+        Args:
+            collection_id: Collection ID (e.g. 'col_abc123').
+        """
+        client = get_client()
+        result = client.collections.get(collection_id)
+        return json.dumps(result, indent=2)
+
+    @mcp.resource("creativai://collections/{collection_id}/plates")
+    def resource_list_plates(collection_id: str) -> str:
+        """All data plates in a collection.
+
+        Args:
+            collection_id: Collection ID.
+        """
+        client = get_client()
+        result = client.data_plates.list(collection_id)
+        plates = result if isinstance(result, list) else result.get("plates", result.get("data", []))
+        return json.dumps(plates, indent=2)
+
+    @mcp.resource("creativai://account")
+    def resource_account_info() -> str:
+        """Your CreativAI account info: credits, plan, usage stats."""
+        client = get_client()
+        result = client.users.get_users_info()
+        return json.dumps(result, indent=2)
+
+    @mcp.resource("creativai://collections/{collection_id}/videos")
+    def resource_collection_videos(collection_id: str) -> str:
+        """All media files in a collection with their preprocessing and indexing status.
+
+        Args:
+            collection_id: Collection ID (e.g. 'col_abc123').
+        """
+        client = get_client()
+        result = client.media.list(collection_id)
+        media = result if isinstance(result, list) else result.get("media", result.get("data", []))
+        return json.dumps(media, indent=2)
+
+    @mcp.resource("creativai://data-plates/{plate_id}")
+    def resource_data_plate(plate_id: str) -> str:
+        """A data plate's first page of segments (up to 100 rows).
+
+        Note: plate_id should be formatted as '{collection_id}:{plate_id}'.
+        Args:
+            plate_id: Composite ID in the format 'collection_id:plate_id'.
+        """
+        client = get_client()
+        if ":" in plate_id:
+            collection_id, pid = plate_id.split(":", 1)
+        else:
+            return json.dumps({"error": "plate_id must be 'collection_id:plate_id'"})
+        result = client.data_plates.get(collection_id, pid, page=1, page_size=100)
+        return json.dumps(result, indent=2)
+
+    @mcp.resource("creativai://organizations")
+    def resource_organizations() -> str:
+        """All organizations you are a member of."""
+        client = get_client()
+        result = client.organizations.list()
+        orgs = result if isinstance(result, list) else result.get("organizations", result.get("data", []))
+        return json.dumps(orgs, indent=2)

creativai_mcp-0.1.0/creativai_mcp/server.py

@@ -0,0 +1,129 @@
+"""
+CreativAI MCP Server — entry point.
+
+Supports two transports:
+  stdio  (default) — for Claude Desktop, Cursor, Copilot config files
+  sse    — for HTTP-based MCP clients (set --transport sse)
+
+Usage:
+  # stdio (Claude Desktop / Cursor)
+  creativai-mcp
+
+  # HTTP/SSE on a custom port
+  creativai-mcp --transport sse --host 0.0.0.0 --port 8090
+
+  # Explicit API key
+  creativai-mcp --api-key sk_live_xxx
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+
+from .auth import resolve_api_key
+from .tools import register_all
+from .resources import register as register_resources
+from .prompts import register as register_prompts
+
+load_dotenv()
+
+_SERVER_NAME = "CreativAI"
+_SERVER_VERSION = "0.1.0"
+_SERVER_DESCRIPTION = (
+    "Video intelligence tools: upload, index, search, chat, extract knowledge, "
+    "live stream, and more — powered by CreativAI."
+)
+
+
+def build_server(api_key: str | None = None) -> FastMCP:
+    """Build and return a configured FastMCP server instance.
+
+    This is also importable for use inside the FastAPI backend (SSE transport).
+    """
+    resolved_key = resolve_api_key(api_key)
+
+    # Lazy client factory — one client per server instance, created on first use.
+    _client_cache: list = []
+
+    def get_client():
+        if not _client_cache:
+            import creativai
+            kwargs: dict = {"api_key": resolved_key}
+            base_url = os.environ.get("CREATIVAI_BASE_URL", "").strip()
+            if base_url:
+                kwargs["base_url"] = base_url
+            _client_cache.append(creativai.CreativAI(**kwargs))
+        return _client_cache[0]
+
+    mcp = FastMCP(
+        name=_SERVER_NAME,
+        version=_SERVER_VERSION,
+        description=_SERVER_DESCRIPTION,
+    )
+
+    # Register all tools, resources, and prompts
+    register_all(mcp, get_client)
+    register_resources(mcp, get_client)
+    register_prompts(mcp)
+
+    return mcp
+
+
+def main() -> None:
+    """CLI entry point — parses args and runs the server."""
+    parser = argparse.ArgumentParser(
+        prog="creativai-mcp",
+        description="CreativAI MCP server — expose video intelligence to any MCP-compatible AI.",
+    )
+    parser.add_argument(
+        "--api-key",
+        default=None,
+        help="CreativAI API key (falls back to CREATIVAI_API_KEY env var).",
+    )
+    parser.add_argument(
+        "--base-url",
+        default=None,
+        help="Override the API base URL (e.g. http://localhost:5000 for local backend).",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "sse"],
+        default="stdio",
+        help="Transport protocol (default: stdio).",
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Host for SSE transport (default: 127.0.0.1).",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8090,
+        help="Port for SSE transport (default: 8090).",
+    )
+    args = parser.parse_args()
+
+    # --base-url CLI flag sets the env var so build_server picks it up
+    if args.base_url:
+        os.environ["CREATIVAI_BASE_URL"] = args.base_url
+
+    try:
+        mcp = build_server(api_key=args.api_key)
+    except RuntimeError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.transport == "sse":
+        mcp.run(transport="sse", host=args.host, port=args.port)
+    else:
+        mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

creativai_mcp-0.1.0/creativai_mcp/tools/__init__.py

@@ -0,0 +1,45 @@
+"""
+CreativAI MCP — tools package.
+Exports a single register_all() that wires every tool domain into an mcp instance.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from mcp.server.fastmcp import FastMCP
+
+from . import (
+    collections,
+    media,
+    indexing,
+    search,
+    agentic_chat,
+    knowledge,
+    data_plates,
+    tasks,
+    live_stream,
+    online_search,
+    youtube,
+    users,
+    organizations,
+)
+
+
+def register_all(mcp: FastMCP, get_client: Any) -> None:
+    """Register all CreativAI tools into the given FastMCP instance."""
+    collections.register(mcp, get_client)
+    media.register(mcp, get_client)
+    indexing.register(mcp, get_client)
+    search.register(mcp, get_client)
+    agentic_chat.register(mcp, get_client)
+    knowledge.register(mcp, get_client)
+    data_plates.register(mcp, get_client)
+    tasks.register(mcp, get_client)
+    live_stream.register(mcp, get_client)
+    online_search.register(mcp, get_client)
+    youtube.register(mcp, get_client)
+    users.register(mcp, get_client)
+    organizations.register(mcp, get_client)
+
+
+__all__ = ["register_all"]