m2ai-mcp-videogen-advisor 1.0.0__tar.gz

m2ai_mcp_videogen_advisor-1.0.0/.env.example

@@ -0,0 +1,10 @@
+# videogen-mcp Environment Variables
+# Copy this file to .env and fill in your API keys
+
+# HeyGen API key from Space Settings > API
+# Required for avatar-based video generation
+HEYGEN_API_KEY=your_heygen_api_key_here
+
+# Google AI Studio API key with Veo access
+# Required for creative/cinematic video generation
+GEMINI_API_KEY=your_gemini_api_key_here

m2ai_mcp_videogen_advisor-1.0.0/.gitignore

@@ -0,0 +1,49 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db

m2ai_mcp_videogen_advisor-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Me, Myself Plus AI LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

m2ai_mcp_videogen_advisor-1.0.0/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: m2ai-mcp-videogen-advisor
+Version: 1.0.0
+Summary: Unified MCP server for video generation with intelligent HeyGen/Veo routing
+Project-URL: Homepage, https://github.com/m2ai-mcp-servers/videogen-mcp
+Project-URL: Documentation, https://github.com/m2ai-mcp-servers/videogen-mcp#readme
+Project-URL: Repository, https://github.com/m2ai-mcp-servers/videogen-mcp
+Author: Me, Myself Plus AI LLC
+License: MIT
+License-File: LICENSE
+Keywords: ai,claude,gemini,heygen,mcp,model-context-protocol,veo,video
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# VideoGen Advisor
+
+A unified MCP server for video generation that intelligently routes requests to either HeyGen (for avatar/presenter videos) or Google Veo (for creative/cinematic content).
+
+## Features
+
+- **Intelligent Routing**: Automatically selects the best service based on prompt content
+- **HeyGen Integration**: Avatar-based videos, custom voices, templates
+- **Google Veo Integration**: Cinematic content, image-to-video, creative visuals
+- **Unified Interface**: Single `generate_video` tool with automatic service selection
+- **Full Control**: Direct access to service-specific tools when needed
+
+## Installation
+
+```bash
+pip install m2ai-mcp-videogen-advisor
+```
+
+## Configuration
+
+Set your API keys as environment variables:
+
+```bash
+export HEYGEN_API_KEY=your_heygen_api_key_here
+export GEMINI_API_KEY=your_gemini_api_key_here
+```
+
+## Claude Desktop Configuration
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "videogen": {
+      "command": "videogen-advisor",
+      "env": {
+        "HEYGEN_API_KEY": "your_heygen_key",
+        "GEMINI_API_KEY": "your_gemini_key"
+      }
+    }
+  }
+}
+```
+
+Or run directly with Python:
+
+```json
+{
+  "mcpServers": {
+    "videogen": {
+      "command": "python",
+      "args": ["-m", "videogen_mcp.server"],
+      "env": {
+        "HEYGEN_API_KEY": "your_heygen_key",
+        "GEMINI_API_KEY": "your_gemini_key"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Unified Interface (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `generate_video` | Generate video with intelligent routing to HeyGen or Veo |
+| `get_video_status` | Check job status (works for both services) |
+| `download_video` | Get download URL for completed video |
+
+### HeyGen-Specific (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `list_avatars` | List available avatars (stock + custom) |
+| `list_voices` | List available voices for avatar videos |
+| `create_avatar_video` | Create video with specific avatar/voice |
+| `list_templates` | List available video templates |
+| `get_template_details` | Get template variables and details |
+| `generate_from_template` | Generate video from template |
+
+### Veo-Specific (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `generate_creative_video` | Generate cinematic video with full Veo controls |
+| `generate_video_from_image` | Animate a static image into video |
+
+## Usage Examples
+
+### Automatic Routing
+
+```
+"Create a video where someone presents our Q4 results"
+→ Routes to HeyGen (presenter/speaking content)
+
+"Cinematic aerial shot of mountains at sunset"
+→ Routes to Veo (creative/visual content)
+```
+
+### Explicit Service Selection
+
+```python
+# Force HeyGen
+generate_video(
+    prompt="Create any video",
+    service_hint="heygen"
+)
+
+# Force Veo
+generate_video(
+    prompt="A tutorial video",
+    service_hint="veo"
+)
+```
+
+### HeyGen Avatar Video
+
+```python
+# 1. List avatars and voices
+avatars = list_avatars(filter_gender="female")
+voices = list_voices(filter_language="en")
+
+# 2. Create video
+job = create_avatar_video(
+    script="Hello! Welcome to our company.",
+    avatar_id="Angela-inblackskirt-20220820",
+    voice_id="1bd001e7e50f421d891986aad5158bc8",
+    background={"type": "color", "value": "#0066CC"},
+    aspect_ratio="16:9"
+)
+
+# 3. Poll for completion
+status = get_video_status(job_id=job["job_id"], service="heygen")
+
+# 4. Download when complete
+result = download_video(job_id=job["job_id"], service="heygen")
+```
+
+### Veo Creative Video
+
+```python
+# Generate cinematic content
+job = generate_creative_video(
+    prompt="A slow dolly shot through a neon-lit Tokyo alley at night, rain reflections, cinematic color grading",
+    negative_prompt="blurry, low quality, text overlays",
+    aspect_ratio="16:9",
+    duration=8,
+    model="veo-3.1-generate-preview"
+)
+
+# Poll and download
+status = get_video_status(job_id=job["job_id"], service="veo")
+result = download_video(job_id=job["job_id"], service="veo")
+```
+
+### Image to Video
+
+```python
+# Animate a still image
+job = generate_video_from_image(
+    image_url="https://example.com/product-photo.jpg",
+    prompt="Slow zoom in with subtle product rotation",
+    duration=6
+)
+```
+
+## Routing Logic
+
+The `generate_video` tool uses keyword detection to route requests:
+
+**HeyGen triggers** (avatar/presenter content):
+- speak, present, explain, tutorial, avatar, host, narrator
+- talking, announce, introduce, walk through, demo, spokesperson
+
+**Veo triggers** (creative/cinematic content):
+- cinematic, scene, visual, b-roll, animation, shot, footage
+- landscape, abstract, artistic, dramatic, aerial, timelapse
+
+Ambiguous prompts default to Veo unless avatar/presenter language is detected.
+
+## Video Wait Times
+
+- **HeyGen**: 1-5 minutes (varies by content length)
+- **Veo**: 2-10 minutes (varies by complexity)
+
+Poll `get_video_status` until status is `completed` or `failed`.
+
+## Error Handling
+
+All tools return structured error objects:
+
+```json
+{
+  "error": true,
+  "code": "QUOTA_EXCEEDED",
+  "message": "API credits exhausted. Check your account."
+}
+```
+
+Common error codes:
+- `AUTH_FAILED` - Invalid API key
+- `QUOTA_EXCEEDED` - API credits exhausted
+- `INVALID_AVATAR` / `INVALID_VOICE` - ID not found
+- `CONTENT_BLOCKED` - Safety filter triggered
+- `VIDEO_NOT_READY` - Generation still in progress
+- `JOB_NOT_FOUND` - Invalid job ID
+
+## Development
+
+```bash
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=videogen_mcp
+
+# Type checking
+mypy src/
+
+# Linting
+ruff check src/ tests/
+```
+
+## License
+
+MIT License
+
+## Credits
+
+- [HeyGen API](https://docs.heygen.com/reference)
+- [Google Veo API](https://ai.google.dev/gemini-api/docs/video)
+- Generated by GRIMLOCK MCP Factory

m2ai_mcp_videogen_advisor-1.0.0/README.md

@@ -0,0 +1,235 @@
+# VideoGen Advisor
+
+A unified MCP server for video generation that intelligently routes requests to either HeyGen (for avatar/presenter videos) or Google Veo (for creative/cinematic content).
+
+## Features
+
+- **Intelligent Routing**: Automatically selects the best service based on prompt content
+- **HeyGen Integration**: Avatar-based videos, custom voices, templates
+- **Google Veo Integration**: Cinematic content, image-to-video, creative visuals
+- **Unified Interface**: Single `generate_video` tool with automatic service selection
+- **Full Control**: Direct access to service-specific tools when needed
+
+## Installation
+
+```bash
+pip install m2ai-mcp-videogen-advisor
+```
+
+## Configuration
+
+Set your API keys as environment variables:
+
+```bash
+export HEYGEN_API_KEY=your_heygen_api_key_here
+export GEMINI_API_KEY=your_gemini_api_key_here
+```
+
+## Claude Desktop Configuration
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "videogen": {
+      "command": "videogen-advisor",
+      "env": {
+        "HEYGEN_API_KEY": "your_heygen_key",
+        "GEMINI_API_KEY": "your_gemini_key"
+      }
+    }
+  }
+}
+```
+
+Or run directly with Python:
+
+```json
+{
+  "mcpServers": {
+    "videogen": {
+      "command": "python",
+      "args": ["-m", "videogen_mcp.server"],
+      "env": {
+        "HEYGEN_API_KEY": "your_heygen_key",
+        "GEMINI_API_KEY": "your_gemini_key"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Unified Interface (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `generate_video` | Generate video with intelligent routing to HeyGen or Veo |
+| `get_video_status` | Check job status (works for both services) |
+| `download_video` | Get download URL for completed video |
+
+### HeyGen-Specific (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `list_avatars` | List available avatars (stock + custom) |
+| `list_voices` | List available voices for avatar videos |
+| `create_avatar_video` | Create video with specific avatar/voice |
+| `list_templates` | List available video templates |
+| `get_template_details` | Get template variables and details |
+| `generate_from_template` | Generate video from template |
+
+### Veo-Specific (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `generate_creative_video` | Generate cinematic video with full Veo controls |
+| `generate_video_from_image` | Animate a static image into video |
+
+## Usage Examples
+
+### Automatic Routing
+
+```
+"Create a video where someone presents our Q4 results"
+→ Routes to HeyGen (presenter/speaking content)
+
+"Cinematic aerial shot of mountains at sunset"
+→ Routes to Veo (creative/visual content)
+```
+
+### Explicit Service Selection
+
+```python
+# Force HeyGen
+generate_video(
+    prompt="Create any video",
+    service_hint="heygen"
+)
+
+# Force Veo
+generate_video(
+    prompt="A tutorial video",
+    service_hint="veo"
+)
+```
+
+### HeyGen Avatar Video
+
+```python
+# 1. List avatars and voices
+avatars = list_avatars(filter_gender="female")
+voices = list_voices(filter_language="en")
+
+# 2. Create video
+job = create_avatar_video(
+    script="Hello! Welcome to our company.",
+    avatar_id="Angela-inblackskirt-20220820",
+    voice_id="1bd001e7e50f421d891986aad5158bc8",
+    background={"type": "color", "value": "#0066CC"},
+    aspect_ratio="16:9"
+)
+
+# 3. Poll for completion
+status = get_video_status(job_id=job["job_id"], service="heygen")
+
+# 4. Download when complete
+result = download_video(job_id=job["job_id"], service="heygen")
+```
+
+### Veo Creative Video
+
+```python
+# Generate cinematic content
+job = generate_creative_video(
+    prompt="A slow dolly shot through a neon-lit Tokyo alley at night, rain reflections, cinematic color grading",
+    negative_prompt="blurry, low quality, text overlays",
+    aspect_ratio="16:9",
+    duration=8,
+    model="veo-3.1-generate-preview"
+)
+
+# Poll and download
+status = get_video_status(job_id=job["job_id"], service="veo")
+result = download_video(job_id=job["job_id"], service="veo")
+```
+
+### Image to Video
+
+```python
+# Animate a still image
+job = generate_video_from_image(
+    image_url="https://example.com/product-photo.jpg",
+    prompt="Slow zoom in with subtle product rotation",
+    duration=6
+)
+```
+
+## Routing Logic
+
+The `generate_video` tool uses keyword detection to route requests:
+
+**HeyGen triggers** (avatar/presenter content):
+- speak, present, explain, tutorial, avatar, host, narrator
+- talking, announce, introduce, walk through, demo, spokesperson
+
+**Veo triggers** (creative/cinematic content):
+- cinematic, scene, visual, b-roll, animation, shot, footage
+- landscape, abstract, artistic, dramatic, aerial, timelapse
+
+Ambiguous prompts default to Veo unless avatar/presenter language is detected.
+
+## Video Wait Times
+
+- **HeyGen**: 1-5 minutes (varies by content length)
+- **Veo**: 2-10 minutes (varies by complexity)
+
+Poll `get_video_status` until status is `completed` or `failed`.
+
+## Error Handling
+
+All tools return structured error objects:
+
+```json
+{
+  "error": true,
+  "code": "QUOTA_EXCEEDED",
+  "message": "API credits exhausted. Check your account."
+}
+```
+
+Common error codes:
+- `AUTH_FAILED` - Invalid API key
+- `QUOTA_EXCEEDED` - API credits exhausted
+- `INVALID_AVATAR` / `INVALID_VOICE` - ID not found
+- `CONTENT_BLOCKED` - Safety filter triggered
+- `VIDEO_NOT_READY` - Generation still in progress
+- `JOB_NOT_FOUND` - Invalid job ID
+
+## Development
+
+```bash
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=videogen_mcp
+
+# Type checking
+mypy src/
+
+# Linting
+ruff check src/ tests/
+```
+
+## License
+
+MIT License
+
+## Credits
+
+- [HeyGen API](https://docs.heygen.com/reference)
+- [Google Veo API](https://ai.google.dev/gemini-api/docs/video)
+- Generated by GRIMLOCK MCP Factory

m2ai_mcp_videogen_advisor-1.0.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "m2ai-mcp-videogen-advisor"
+version = "1.0.0"
+description = "Unified MCP server for video generation with intelligent HeyGen/Veo routing"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+    {name = "Me, Myself Plus AI LLC"}
+]
+keywords = ["mcp", "model-context-protocol", "ai", "claude", "video", "heygen", "veo", "gemini"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=4.0.0",
+    "respx>=0.21.0",
+    "ruff>=0.1.0",
+    "mypy>=1.8.0",
+]
+
+[project.scripts]
+videogen-advisor = "videogen_mcp.server:main"
+
+[project.urls]
+Homepage = "https://github.com/m2ai-mcp-servers/videogen-mcp"
+Documentation = "https://github.com/m2ai-mcp-servers/videogen-mcp#readme"
+Repository = "https://github.com/m2ai-mcp-servers/videogen-mcp"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/videogen_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true