hoox-mcp 0.1.0__tar.gz

hoox_mcp-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+
+# Virtual environment
+.venv/
+
+# Build / packaging
+dist/
+build/
+*.egg-info/
+
+# Test caches
+.pytest_cache/
+
+# Secrets (keep .env.example)
+.env

hoox_mcp-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Hoox
+
+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.
+

hoox_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: hoox-mcp
+Version: 0.1.0
+Summary: MCP server for Hoox — AI video generation platform
+Project-URL: Homepage, https://hoox.video
+Project-URL: Documentation, https://docs.hoox.video
+Author-email: Hoox <alerts@hoox.video>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,generation,hoox,mcp,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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Description-Content-Type: text/markdown
+
+# Hoox MCP Server
+
+Official [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for [Hoox](https://hoox.video) — the AI video generation platform. This server lets any MCP-compatible client (Claude Desktop, Cursor, Windsurf, etc.) generate videos, manage avatars and voices, and export MP4 files using natural language.
+
+## Quickstart with Claude Desktop
+
+1. Get your API key from [app.hoox.video → Settings → API Keys](https://app.hoox.video). An **Enterprise** plan is required to access the API.
+2. Install `uv` (Python package manager): `curl -LsSf https://astral.sh/uv/install.sh | sh`
+3. Add the following configuration to your `claude_desktop_config.json` (Claude → Preferences → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "hoox": {
+      "command": "uvx",
+      "args": ["hoox-mcp"],
+      "env": {
+        "HOOX_API_KEY": "hx_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Other MCP clients
+
+For Cursor, Windsurf, or any other compatible client:
+
+```bash
+pip install hoox-mcp
+```
+
+Then add the configuration to your client's MCP configuration file:
+
+```json
+{
+  "mcpServers": {
+    "hoox": {
+      "command": "hoox-mcp",
+      "env": {
+        "HOOX_API_KEY": "hx_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Your MCP client can now interact with Hoox through the tools listed below.
+
+## Example prompts
+
+> ⚠️ Hoox credits are required to use these tools.
+
+Try for example:
+
+- *"Use the Hoox API to generate a 60-second vertical product demo video for our new DTC skincare serum."*
+- *"List the male avatars available with a professional style"*
+- *"Create an avatar from this description: man in a conference room in a suit"*
+- *"Duplicate the video vid_xxx by changing the voice to a male English voice"*
+- *"Generate a 45 second script about our new DTC skincare serum, then start the video generation and export the result as MP4"*
+
+## Available tools
+
+### Voices
+
+| Tool                  | Description                                                       |
+|-----------------------|-------------------------------------------------------------------|
+| `list_voices`         | List available voices with optional filters (language, gender, tags) |
+| `get_voice`           | Get details for a voice by ID                                    |
+| `list_resource_voices`| Simplified voice list optimized for generation                   |
+
+### Avatars
+
+| Tool                    | Description                                                   |
+|-------------------------|---------------------------------------------------------------|
+| `list_avatars`          | List available avatars with optional filters (gender, tags)   |
+| `get_avatar`            | Get full details for an avatar and its looks                  |
+| `get_avatar_look`       | Get details for a specific look                               |
+| `create_avatar`         | Create a new avatar from a prompt or reference images         |
+| `edit_avatar`           | Edit an existing look to create a new variation               |
+| `get_avatar_status`     | Check the creation status of an avatar                        |
+| `list_resource_avatars` | Simplified avatar list optimized for generation               |
+
+### Script
+
+| Tool              | Description                                      |
+|-------------------|--------------------------------------------------|
+| `generate_script` | Generate a video narration script from a prompt  |
+
+### Video generation
+
+| Tool                 | Description                                         |
+|----------------------|-----------------------------------------------------|
+| `start_generation`   | Start an AI video generation job                    |
+| `get_generation_status` | Check the status and progress of a generation job |
+
+### Export
+
+| Tool             | Description                                   |
+|------------------|-----------------------------------------------|
+| `start_export`   | Start exporting a generated video to MP4      |
+| `get_export_status` | Check the status of an export job          |
+
+### Video management
+
+| Tool             | Description                                                         |
+|------------------|---------------------------------------------------------------------|
+| `duplicate_video`| Duplicate a completed video, optionally changing the voice or avatar|
+
+## Typical workflow
+
+```text
+1. list_resource_voices / list_resource_avatars  →  pick a voice & avatar
+2. generate_script (optional)                    →  get narration text
+3. start_generation                              →  get job_id
+4. get_generation_status (polling)               →  get video_id
+5. start_export                                  →  get export job_id
+6. get_export_status (polling)                   →  get MP4 download URL
+```
+
+## Configuration
+
+| Environment variable | Required | Default                                  | Description                         |
+|----------------------|---------|------------------------------------------|-------------------------------------|
+| `HOOX_API_KEY`       | Yes     | —                                        | Your Hoox API key (`hx_live_...`)   |
+| `HOOX_BASE_URL`      | No      | `https://app.hoox.video/api/public/v1`   | Override the API base URL           |
+
+## Troubleshooting
+
+### "HOOX_API_KEY is required"
+
+Make sure the `HOOX_API_KEY` environment variable is set in your MCP client configuration. The key must start with `hx_live_` or `hx_`.
+
+### Error `plan_required` (403)
+
+Your Hoox account must have an **Enterprise** plan to use the API. Upgrade at [app.hoox.video](https://app.hoox.video).
+
+### Error `insufficient_credits` (402)
+
+Your workspace has run out of credits. Top up from the Hoox dashboard under Settings → Billing.
+
+### Error `rate_limit_exceeded` (429)
+
+The API allows 100 requests per minute on the Enterprise plan. Wait a bit before trying again.
+
+### Tool not showing up in Claude Desktop / Cursor
+
+1. Check that `hoox-mcp` is installed: `pip install hoox-mcp` or `uvx hoox-mcp --help`
+2. Restart your MCP client after updating the configuration
+3. Check your client's logs for connection errors
+
+Claude Desktop logs are located at:
+
+- macOS: `~/Library/Logs/Claude/mcp-server-hoox.log`
+- Windows: `%APPDATA%\\Claude\\logs\\mcp-server-hoox.log`
+
+### Generation stuck in "processing"
+
+Video generation can take between 1 and 5 minutes depending on duration and options. Use `get_generation_status` to monitor progress. If the job is stuck for more than 10 minutes, it may have failed — check the `error` field in the status response.
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE` for details.

hoox_mcp-0.1.0/README.md

@@ -0,0 +1,163 @@
+# Hoox MCP Server
+
+Official [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for [Hoox](https://hoox.video) — the AI video generation platform. This server lets any MCP-compatible client (Claude Desktop, Cursor, Windsurf, etc.) generate videos, manage avatars and voices, and export MP4 files using natural language.
+
+## Quickstart with Claude Desktop
+
+1. Get your API key from [app.hoox.video → Settings → API Keys](https://app.hoox.video). An **Enterprise** plan is required to access the API.
+2. Install `uv` (Python package manager): `curl -LsSf https://astral.sh/uv/install.sh | sh`
+3. Add the following configuration to your `claude_desktop_config.json` (Claude → Preferences → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "hoox": {
+      "command": "uvx",
+      "args": ["hoox-mcp"],
+      "env": {
+        "HOOX_API_KEY": "hx_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Other MCP clients
+
+For Cursor, Windsurf, or any other compatible client:
+
+```bash
+pip install hoox-mcp
+```
+
+Then add the configuration to your client's MCP configuration file:
+
+```json
+{
+  "mcpServers": {
+    "hoox": {
+      "command": "hoox-mcp",
+      "env": {
+        "HOOX_API_KEY": "hx_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Your MCP client can now interact with Hoox through the tools listed below.
+
+## Example prompts
+
+> ⚠️ Hoox credits are required to use these tools.
+
+Try for example:
+
+- *"Use the Hoox API to generate a 60-second vertical product demo video for our new DTC skincare serum."*
+- *"List the male avatars available with a professional style"*
+- *"Create an avatar from this description: man in a conference room in a suit"*
+- *"Duplicate the video vid_xxx by changing the voice to a male English voice"*
+- *"Generate a 45 second script about our new DTC skincare serum, then start the video generation and export the result as MP4"*
+
+## Available tools
+
+### Voices
+
+| Tool                  | Description                                                       |
+|-----------------------|-------------------------------------------------------------------|
+| `list_voices`         | List available voices with optional filters (language, gender, tags) |
+| `get_voice`           | Get details for a voice by ID                                    |
+| `list_resource_voices`| Simplified voice list optimized for generation                   |
+
+### Avatars
+
+| Tool                    | Description                                                   |
+|-------------------------|---------------------------------------------------------------|
+| `list_avatars`          | List available avatars with optional filters (gender, tags)   |
+| `get_avatar`            | Get full details for an avatar and its looks                  |
+| `get_avatar_look`       | Get details for a specific look                               |
+| `create_avatar`         | Create a new avatar from a prompt or reference images         |
+| `edit_avatar`           | Edit an existing look to create a new variation               |
+| `get_avatar_status`     | Check the creation status of an avatar                        |
+| `list_resource_avatars` | Simplified avatar list optimized for generation               |
+
+### Script
+
+| Tool              | Description                                      |
+|-------------------|--------------------------------------------------|
+| `generate_script` | Generate a video narration script from a prompt  |
+
+### Video generation
+
+| Tool                 | Description                                         |
+|----------------------|-----------------------------------------------------|
+| `start_generation`   | Start an AI video generation job                    |
+| `get_generation_status` | Check the status and progress of a generation job |
+
+### Export
+
+| Tool             | Description                                   |
+|------------------|-----------------------------------------------|
+| `start_export`   | Start exporting a generated video to MP4      |
+| `get_export_status` | Check the status of an export job          |
+
+### Video management
+
+| Tool             | Description                                                         |
+|------------------|---------------------------------------------------------------------|
+| `duplicate_video`| Duplicate a completed video, optionally changing the voice or avatar|
+
+## Typical workflow
+
+```text
+1. list_resource_voices / list_resource_avatars  →  pick a voice & avatar
+2. generate_script (optional)                    →  get narration text
+3. start_generation                              →  get job_id
+4. get_generation_status (polling)               →  get video_id
+5. start_export                                  →  get export job_id
+6. get_export_status (polling)                   →  get MP4 download URL
+```
+
+## Configuration
+
+| Environment variable | Required | Default                                  | Description                         |
+|----------------------|---------|------------------------------------------|-------------------------------------|
+| `HOOX_API_KEY`       | Yes     | —                                        | Your Hoox API key (`hx_live_...`)   |
+| `HOOX_BASE_URL`      | No      | `https://app.hoox.video/api/public/v1`   | Override the API base URL           |
+
+## Troubleshooting
+
+### "HOOX_API_KEY is required"
+
+Make sure the `HOOX_API_KEY` environment variable is set in your MCP client configuration. The key must start with `hx_live_` or `hx_`.
+
+### Error `plan_required` (403)
+
+Your Hoox account must have an **Enterprise** plan to use the API. Upgrade at [app.hoox.video](https://app.hoox.video).
+
+### Error `insufficient_credits` (402)
+
+Your workspace has run out of credits. Top up from the Hoox dashboard under Settings → Billing.
+
+### Error `rate_limit_exceeded` (429)
+
+The API allows 100 requests per minute on the Enterprise plan. Wait a bit before trying again.
+
+### Tool not showing up in Claude Desktop / Cursor
+
+1. Check that `hoox-mcp` is installed: `pip install hoox-mcp` or `uvx hoox-mcp --help`
+2. Restart your MCP client after updating the configuration
+3. Check your client's logs for connection errors
+
+Claude Desktop logs are located at:
+
+- macOS: `~/Library/Logs/Claude/mcp-server-hoox.log`
+- Windows: `%APPDATA%\\Claude\\logs\\mcp-server-hoox.log`
+
+### Generation stuck in "processing"
+
+Video generation can take between 1 and 5 minutes depending on duration and options. Use `get_generation_status` to monitor progress. If the job is stuck for more than 10 minutes, it may have failed — check the `error` field in the status response.
+
+## License
+
+This project is licensed under the MIT License. See `LICENSE` for details.

hoox_mcp-0.1.0/hoox_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Hoox MCP Server — AI video generation through the Model Context Protocol."""
+
+from hoox_mcp.server import main
+
+__all__ = ["main"]

hoox_mcp-0.1.0/hoox_mcp/client.py

@@ -0,0 +1,164 @@
+"""Thin async HTTP client wrapping the Hoox public REST API."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+DEFAULT_BASE_URL = "https://app.hoox.video/api/public/v1"
+REQUEST_TIMEOUT = 120.0
+
+
+class HooxClientError(Exception):
+    """Raised when the Hoox API returns a non-2xx response."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"HTTP {status_code}: {detail}")
+
+
+class HooxClient:
+    """Lightweight async wrapper around the Hoox public API v1."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("HOOX_API_KEY", "")
+        # HOOX_BASE_URL is intentionally not read from the environment to avoid
+        # accidentally sending API requests (and the API key) to an unexpected host.
+        # If a different endpoint is needed (e.g. for staging), it must be passed
+        # explicitly via the base_url argument.
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        if not self.api_key:
+            raise ValueError(
+                "HOOX_API_KEY is required. Set it as an environment variable or pass it directly."
+            )
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=REQUEST_TIMEOUT,
+        )
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: dict[str, Any] | None = None,
+    ) -> Any:
+        resp = await self._client.request(method, path, params=params, json=json_body)
+        if resp.status_code >= 400:
+            try:
+                detail = resp.json()
+            except Exception:
+                detail = resp.text
+            raise HooxClientError(resp.status_code, str(detail))
+        return resp.json()
+
+    # ------------------------------------------------------------------
+    # Voices
+    # ------------------------------------------------------------------
+
+    async def list_voices(
+        self,
+        language: str | None = None,
+        gender: str | None = None,
+        tags: str | None = None,
+        only_public: bool | None = None,
+    ) -> Any:
+        params: dict[str, Any] = {}
+        if language:
+            params["language"] = language
+        if gender:
+            params["gender"] = gender
+        if tags:
+            params["tags"] = tags
+        if only_public is not None:
+            params["onlyPublic"] = str(only_public).lower()
+        return await self._request("GET", "/voice/list", params=params)
+
+    async def get_voice(self, voice_id: str) -> Any:
+        return await self._request("GET", f"/voice/{voice_id}")
+
+    # ------------------------------------------------------------------
+    # Avatars
+    # ------------------------------------------------------------------
+
+    async def list_avatars(
+        self,
+        gender: str | None = None,
+        tags: str | None = None,
+        only_public: bool | None = None,
+    ) -> Any:
+        params: dict[str, Any] = {}
+        if gender:
+            params["gender"] = gender
+        if tags:
+            params["tags"] = tags
+        if only_public is not None:
+            params["onlyPublic"] = str(only_public).lower()
+        return await self._request("GET", "/avatar/list", params=params)
+
+    async def get_avatar(self, avatar_id: str) -> Any:
+        return await self._request("GET", f"/avatar/{avatar_id}")
+
+    async def get_avatar_look(self, avatar_id: str, look_id: str) -> Any:
+        return await self._request("GET", f"/avatar/{avatar_id}/look/{look_id}")
+
+    async def get_avatar_status(self, avatar_id: str, look_id: str) -> Any:
+        return await self._request(
+            "GET", "/avatar/status", params={"avatar_id": avatar_id, "look_id": look_id}
+        )
+
+    async def create_avatar(self, **kwargs: Any) -> Any:
+        return await self._request("POST", "/avatar/create", json_body=kwargs)
+
+    async def edit_avatar(self, **kwargs: Any) -> Any:
+        return await self._request("POST", "/avatar/edit", json_body=kwargs)
+
+    # ------------------------------------------------------------------
+    # Script
+    # ------------------------------------------------------------------
+
+    async def generate_script(self, **kwargs: Any) -> Any:
+        return await self._request("POST", "/script/generate", json_body=kwargs)
+
+    # ------------------------------------------------------------------
+    # Generation
+    # ------------------------------------------------------------------
+
+    async def start_generation(self, **kwargs: Any) -> Any:
+        return await self._request("POST", "/generation/start", json_body=kwargs)
+
+    async def get_generation_status(self, job_id: str) -> Any:
+        return await self._request("GET", f"/generation/status/{job_id}")
+
+    # ------------------------------------------------------------------
+    # Export
+    # ------------------------------------------------------------------
+
+    async def start_export(self, **kwargs: Any) -> Any:
+        return await self._request("POST", "/export/start", json_body=kwargs)
+
+    async def get_export_status(self, job_id: str) -> Any:
+        return await self._request("GET", f"/export/status/{job_id}")
+
+    # ------------------------------------------------------------------
+    # Video
+    # ------------------------------------------------------------------
+
+    async def duplicate_video(self, **kwargs: Any) -> Any:
+        return await self._request("POST", "/video/duplicate", json_body=kwargs)
+