mocapless-mcp 0.1.0__tar.gz

mocapless_mcp-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+storage/
+node_modules/
+.next/
+out/
+*.log
+e2e.mjs
+.venv/
+alembic/versions/__pycache__/
+.env.*
+!.env.example

mocapless_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: mocapless-mcp
+Version: 0.1.0
+Summary: MCP server for Mocapless: generate character animation from text inside Claude, Cursor and any MCP client.
+Project-URL: Homepage, https://mocapless.com
+Project-URL: Documentation, https://mocapless.com/developers
+Author-email: Mocapless <hello@mocapless.com>
+License: MIT
+Keywords: animation,fbx,mcp,mocap,text-to-motion
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<2,>=1.10
+Requires-Dist: pydantic>=2.5
+Description-Content-Type: text/markdown
+
+# mocapless-mcp
+
+Generate character animation from a sentence, inside Claude Desktop, Claude Code, Cursor, Windsurf or any MCP client — on your own rigged character, exported as FBX / GLB / BVH.
+
+```
+"Animate my character: a tired soldier limps forward, stops, looks over his shoulder, then sits down."
+```
+
+The agent plans it, quotes the price, generates it, waits, and saves the files.
+
+## Setup
+
+1. Get an API key: [mocapless.com/account](https://mocapless.com/account) → API keys. New accounts have 60 free credits (about a minute of animation) and a demo character ready to animate.
+2. Add the server to your client.
+
+**Claude Desktop** — `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mocapless": {
+      "command": "uvx",
+      "args": ["mocapless-mcp"],
+      "env": { "MOCAPLESS_API_KEY": "mf_..." }
+    }
+  }
+}
+```
+
+**Claude Code**:
+
+```
+claude mcp add mocapless -e MOCAPLESS_API_KEY=mf_... -- uvx mocapless-mcp
+```
+
+**Cursor / Windsurf** — same JSON under `mcpServers` in the client's MCP settings.
+
+`uvx` comes with [uv](https://docs.astral.sh/uv/). With plain Python: `pip install mocapless-mcp` and use `"command": "mocapless-mcp"`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `account` | Credits left, plan. |
+| `list_characters` | Your characters (the demo mannequin is there on a new account). |
+| `upload_character(path)` | Upload an FBX/GLB/DAE — rigged or not — and wait until it is ready. |
+| `plan_motion(prompt)` | Free: the beats, the engine and the price for a prompt. |
+| `generate_animation(prompt, character_id?, formats?, loop?, quality?, wait?, download_dir?)` | Generate, wait, download. |
+| `get_job(job_id, download_dir?)` | Status and files of a generation. |
+| `recent_animations(limit?)` | Your recent generations. |
+| `share_link(job_id)` | A public link to watch the clip in the browser. |
+
+Files land in `~/mocapless/<job>/` unless `download_dir` or `MOCAPLESS_DOWNLOAD_DIR` says otherwise.
+
+## Prompting
+
+Plain present-tense English about the body, in order. One to four sentences. Say which hand, which direction, what mood; leave out camera and scene. Up to 30 seconds per clip. `loop: true` for idles, walks and dances that should cycle.
+
+## With an engine MCP
+
+Combined with an Unreal or Unity MCP server, one request can export the character, generate the motion here, and import the result into the project.
+
+## Development
+
+```
+cd mcp
+uv sync
+uv run pytest
+uv run mocapless-mcp        # stdio server
+```
+
+Environment: `MOCAPLESS_API_KEY` (required), `MOCAPLESS_API_BASE` (default `https://api.mocapless.com`), `MOCAPLESS_DOWNLOAD_DIR`.

mocapless_mcp-0.1.0/README.md

@@ -0,0 +1,72 @@
+# mocapless-mcp
+
+Generate character animation from a sentence, inside Claude Desktop, Claude Code, Cursor, Windsurf or any MCP client — on your own rigged character, exported as FBX / GLB / BVH.
+
+```
+"Animate my character: a tired soldier limps forward, stops, looks over his shoulder, then sits down."
+```
+
+The agent plans it, quotes the price, generates it, waits, and saves the files.
+
+## Setup
+
+1. Get an API key: [mocapless.com/account](https://mocapless.com/account) → API keys. New accounts have 60 free credits (about a minute of animation) and a demo character ready to animate.
+2. Add the server to your client.
+
+**Claude Desktop** — `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mocapless": {
+      "command": "uvx",
+      "args": ["mocapless-mcp"],
+      "env": { "MOCAPLESS_API_KEY": "mf_..." }
+    }
+  }
+}
+```
+
+**Claude Code**:
+
+```
+claude mcp add mocapless -e MOCAPLESS_API_KEY=mf_... -- uvx mocapless-mcp
+```
+
+**Cursor / Windsurf** — same JSON under `mcpServers` in the client's MCP settings.
+
+`uvx` comes with [uv](https://docs.astral.sh/uv/). With plain Python: `pip install mocapless-mcp` and use `"command": "mocapless-mcp"`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `account` | Credits left, plan. |
+| `list_characters` | Your characters (the demo mannequin is there on a new account). |
+| `upload_character(path)` | Upload an FBX/GLB/DAE — rigged or not — and wait until it is ready. |
+| `plan_motion(prompt)` | Free: the beats, the engine and the price for a prompt. |
+| `generate_animation(prompt, character_id?, formats?, loop?, quality?, wait?, download_dir?)` | Generate, wait, download. |
+| `get_job(job_id, download_dir?)` | Status and files of a generation. |
+| `recent_animations(limit?)` | Your recent generations. |
+| `share_link(job_id)` | A public link to watch the clip in the browser. |
+
+Files land in `~/mocapless/<job>/` unless `download_dir` or `MOCAPLESS_DOWNLOAD_DIR` says otherwise.
+
+## Prompting
+
+Plain present-tense English about the body, in order. One to four sentences. Say which hand, which direction, what mood; leave out camera and scene. Up to 30 seconds per clip. `loop: true` for idles, walks and dances that should cycle.
+
+## With an engine MCP
+
+Combined with an Unreal or Unity MCP server, one request can export the character, generate the motion here, and import the result into the project.
+
+## Development
+
+```
+cd mcp
+uv sync
+uv run pytest
+uv run mocapless-mcp        # stdio server
+```
+
+Environment: `MOCAPLESS_API_KEY` (required), `MOCAPLESS_API_BASE` (default `https://api.mocapless.com`), `MOCAPLESS_DOWNLOAD_DIR`.

mocapless_mcp-0.1.0/mocapless_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Mocapless MCP server: text-to-animation on your own character, from any MCP client."""
+
+__version__ = "0.1.0"

mocapless_mcp-0.1.0/mocapless_mcp/client.py

@@ -0,0 +1,185 @@
+"""A thin client for the Mocapless REST API.
+
+Everything the MCP tools do goes through here, so the tools stay small and
+the API's error language is translated once: a 402 becomes "not enough
+credits, here is where to top up", not a status code an agent has to guess at.
+"""
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from . import __version__
+
+DEFAULT_BASE = "https://api.mocapless.com"
+TERMINAL = {"succeeded", "failed", "cancelled"}
+
+
+class MocaplessError(RuntimeError):
+    """An error worth showing to the person, in their words."""
+
+
+def _detail(response: httpx.Response) -> str:
+    try:
+        body = response.json()
+        detail = body.get("detail") if isinstance(body, dict) else None
+        if isinstance(detail, list):
+            detail = "; ".join(str(d.get("msg", d)) for d in detail)
+        if detail:
+            return str(detail)
+    except Exception:
+        pass
+    return response.text[:300] or f"HTTP {response.status_code}"
+
+
+class MocaplessClient:
+    def __init__(self, api_key: str | None = None, base_url: str | None = None, timeout: float = 120.0):
+        self.api_key = (api_key or os.environ.get("MOCAPLESS_API_KEY") or "").strip()
+        self.base_url = (base_url or os.environ.get("MOCAPLESS_API_BASE") or DEFAULT_BASE).rstrip("/")
+        if not self.api_key:
+            raise MocaplessError(
+                "MOCAPLESS_API_KEY is not set. Create a key at https://mocapless.com/account "
+                "(API keys) and put it in the MCP server's environment."
+            )
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers={"X-API-Key": self.api_key, "User-Agent": f"mocapless-mcp/{__version__}"},
+            timeout=timeout,
+        )
+
+    # ------------------------------------------------------------- transport #
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        try:
+            response = self._http.request(method, path, **kwargs)
+        except httpx.HTTPError as exc:
+            raise MocaplessError(f"Could not reach Mocapless at {self.base_url}: {exc}") from exc
+
+        if response.status_code == 401:
+            raise MocaplessError("Mocapless rejected the API key. Check MOCAPLESS_API_KEY.")
+        if response.status_code == 402:
+            raise MocaplessError(
+                f"Not enough credits: {_detail(response)} Top up at https://mocapless.com/pricing."
+            )
+        if response.status_code == 429:
+            raise MocaplessError("Rate limit reached; wait a moment and try again.")
+        if response.status_code >= 400:
+            raise MocaplessError(_detail(response))
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    # ---------------------------------------------------------------- account #
+    def me(self) -> dict:
+        return self._request("GET", "/v1/auth/me")
+
+    # ------------------------------------------------------------- characters #
+    def list_characters(self) -> list[dict]:
+        return self._request("GET", "/v1/assets")
+
+    def get_character(self, asset_id: str) -> dict:
+        return self._request("GET", f"/v1/assets/{asset_id}")
+
+    def upload_character(self, path: str | Path, *, wait: bool = True, timeout: float = 900.0) -> dict:
+        file = Path(path).expanduser()
+        if not file.is_file():
+            raise MocaplessError(f"No such file: {file}")
+        if file.suffix.lower() not in (".fbx", ".glb", ".gltf", ".dae"):
+            raise MocaplessError("Upload an FBX, GLB, GLTF or DAE file.")
+        with file.open("rb") as handle:
+            asset = self._request(
+                "POST", "/v1/assets", files={"file": (file.name, handle, "application/octet-stream")}
+            )
+        if not wait:
+            return asset
+        return self.wait_character(asset["id"], timeout=timeout)
+
+    def wait_character(self, asset_id: str, *, timeout: float = 900.0, poll: float = 2.0) -> dict:
+        deadline = time.monotonic() + timeout
+        while True:
+            asset = self.get_character(asset_id)
+            if asset.get("status") == "ready":
+                return asset
+            if asset.get("status") == "failed":
+                raise MocaplessError(f"The character could not be used: {asset.get('error') or 'unknown error'}")
+            if time.monotonic() > deadline:
+                raise MocaplessError("Timed out waiting for the character to be processed.")
+            time.sleep(poll)
+
+    # -------------------------------------------------------------- generation #
+    def plan(self, prompt: str, *, engine: str = "auto", fps: int = 30) -> dict:
+        return self._request("POST", "/v1/plan", json={"prompt": prompt, "engine": engine, "fps": fps})
+
+    def generate(
+        self,
+        prompt: str,
+        *,
+        asset_id: str | None = None,
+        formats: list[str] | None = None,
+        loop: bool | None = None,
+        seed: int = 0,
+        engine: str = "auto",
+        samples: int = 1,
+    ) -> dict:
+        body: dict[str, Any] = {
+            "prompt": prompt,
+            "formats": formats or ["fbx", "glb"],
+            "seed": seed,
+            "engine": engine,
+            "samples": samples,
+        }
+        if asset_id:
+            body["asset_id"] = asset_id
+        if loop is not None:
+            body["loop"] = loop
+        return self._request("POST", "/v1/generate", json=body)
+
+    def job(self, job_id: str) -> dict:
+        return self._request("GET", f"/v1/jobs/{job_id}")
+
+    def jobs(self, limit: int = 20) -> list[dict]:
+        return self._request("GET", f"/v1/jobs?limit={int(limit)}")
+
+    def wait_job(self, job_id: str, *, timeout: float = 900.0, poll: float = 2.0) -> dict:
+        """Poll until the job is finished. Backs off to five seconds."""
+        deadline = time.monotonic() + timeout
+        wait = poll
+        while True:
+            job = self.job(job_id)
+            if job.get("status") in TERMINAL:
+                return job
+            if time.monotonic() > deadline:
+                raise MocaplessError(f"Timed out after {timeout:.0f}s; the job {job_id} is still {job.get('stage')}.")
+            time.sleep(wait)
+            wait = min(wait * 1.5, 5.0)
+
+    def share(self, job_id: str) -> dict:
+        return self._request("POST", f"/v1/jobs/{job_id}/share")
+
+    # --------------------------------------------------------------- downloads #
+    def download(self, job: dict, directory: str | Path, kinds: tuple[str, ...] = ("fbx", "glb", "bvh")) -> dict[str, str]:
+        """Save a finished job's deliverables; returns kind -> absolute path."""
+        target = Path(directory).expanduser()
+        target.mkdir(parents=True, exist_ok=True)
+        saved: dict[str, str] = {}
+        for output in job.get("outputs") or []:
+            kind = output.get("kind")
+            if kind not in kinds:
+                continue
+            url = output["url"]
+            path = target / f"{job['id'][:8]}.{kind}"
+            try:
+                # Signed storage URLs need no key; the API's own file route
+                # accepts ours. Sending it either way is harmless.
+                with self._http.stream("GET", url, headers={"X-API-Key": self.api_key}, timeout=600.0) as response:
+                    response.raise_for_status()
+                    with path.open("wb") as handle:
+                        for chunk in response.iter_bytes():
+                            handle.write(chunk)
+            except httpx.HTTPError as exc:
+                raise MocaplessError(f"Could not download the {kind}: {exc}") from exc
+            saved[kind] = str(path.resolve())
+        return saved

mocapless_mcp-0.1.0/mocapless_mcp/server.py

@@ -0,0 +1,200 @@
+"""The MCP server: Mocapless as a set of tools for an agent.
+
+Runs over stdio, which is what Claude Desktop, Claude Code, Cursor and
+Windsurf speak. One environment variable, MOCAPLESS_API_KEY, is the whole
+configuration. The tools are deliberately few and high-level - "generate an
+animation and give me the files" is one call, because that is the sentence
+a person says.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Annotated, Any
+
+from mcp.server.fastmcp import FastMCP
+from pydantic import Field
+
+from .client import MocaplessClient, MocaplessError
+
+mcp = FastMCP(
+    "Mocapless",
+    instructions=(
+        "Mocapless turns a sentence into a character animation on the user's own "
+        "rigged character. Use plan_motion to preview the beats and the price for "
+        "free; generate_animation to make the clip (it waits and downloads the "
+        "files by default). Prompts work best in plain present-tense English that "
+        "says what the body does, in order: 'A person limps forward, stops, looks "
+        "over his shoulder, then sits down.' Up to 30 seconds per clip."
+    ),
+)
+
+_client: MocaplessClient | None = None
+
+
+def client() -> MocaplessClient:
+    global _client
+    if _client is None:
+        _client = MocaplessClient()
+    return _client
+
+
+def reset_client() -> None:
+    global _client
+    _client = None
+
+
+def _default_dir(job_id: str) -> Path:
+    base = os.environ.get("MOCAPLESS_DOWNLOAD_DIR") or str(Path.home() / "mocapless")
+    return Path(base).expanduser() / job_id[:8]
+
+
+def _job_summary(job: dict) -> dict[str, Any]:
+    return {
+        "job_id": job.get("id"),
+        "status": job.get("status"),
+        "stage": job.get("stage"),
+        "prompt": job.get("prompt"),
+        "engine": job.get("engine"),
+        "fallback_from": job.get("fallbackFrom"),
+        "frames": job.get("frames"),
+        "duration_seconds": job.get("durationSeconds"),
+        "credits_cost": job.get("creditsCost"),
+        "credits_refunded": job.get("creditsRefunded"),
+        "error": job.get("error"),
+        "outputs": {o["kind"]: o["url"] for o in (job.get("outputs") or [])},
+    }
+
+
+def _character_summary(asset: dict) -> dict[str, Any]:
+    return {
+        "character_id": asset.get("id"),
+        "name": asset.get("filename"),
+        "status": asset.get("status"),
+        "bones": asset.get("boneCount"),
+        "skeleton_mapped": asset.get("coverage"),
+        "auto_rigged": asset.get("autoRigged", False),
+        "error": asset.get("error"),
+    }
+
+
+# --------------------------------------------------------------------------- #
+# tools
+# --------------------------------------------------------------------------- #
+def account() -> dict[str, Any]:
+    """Who is signed in and how many credits are left. One credit is roughly one second of animation."""
+    me = client().me()
+    return {"email": me.get("email"), "credits": me.get("credits"), "plan": me.get("plan")}
+
+
+def list_characters() -> list[dict[str, Any]]:
+    """The characters in the account, newest first. New accounts have a demo mannequin ready to animate."""
+    return [_character_summary(a) for a in client().list_characters()]
+
+
+def upload_character(
+    path: Annotated[str, Field(description="Local path to an FBX, GLB, GLTF or DAE. Rigged or not - an un-rigged character gets a skeleton built for it.")],
+) -> dict[str, Any]:
+    """Upload a character and wait until its skeleton has been read (seconds for a normal file, a minute or two for a very heavy one). Returns the character id to animate."""
+    return _character_summary(client().upload_character(path))
+
+
+def plan_motion(
+    prompt: Annotated[str, Field(description="What the character should do, in plain English. Sequences are fine: 'walks forward, then waves'.")],
+) -> dict[str, Any]:
+    """Free preview of what generate_animation would do for this prompt: the beats, the engine, the price in credits and the current balance. Nothing is generated or charged."""
+    plan = client().plan(prompt)
+    script = plan.get("script") or {}
+    return {
+        "engine": plan.get("engine"),
+        "cost_credits": plan.get("cost"),
+        "balance_credits": plan.get("balance"),
+        "affordable": plan.get("affordable"),
+        "duration_seconds": script.get("duration"),
+        "beats": script.get("beats") or [],
+        "segments": [
+            {"primitive": s.get("primitive"), "seconds": s.get("seconds"), "style": s.get("style")}
+            for s in script.get("segments") or []
+        ],
+        "notes": script.get("notes") or [],
+    }
+
+
+def generate_animation(
+    prompt: Annotated[str, Field(description="What the character should do, in plain English, in order. Best as one to four short present-tense sentences about the body: 'A person sneaks forward on tiptoe, then leaps sideways and rolls.'")],
+    character_id: Annotated[str | None, Field(description="A character id from list_characters or upload_character. Omit to use the most recent ready character.")] = None,
+    formats: Annotated[list[str], Field(description="Any of fbx, glb, bvh.")] = ["fbx", "glb"],
+    loop: Annotated[bool, Field(description="Make the clip loop seamlessly (for idles, walks, dances).")] = False,
+    quality: Annotated[str, Field(description="'standard' (one take) or 'best' (two takes, keeps the steadier one; same credits, a little slower).")] = "standard",
+    wait: Annotated[bool, Field(description="Wait for the result (usually 30-90 seconds). If false, returns the job id to check with get_job.")] = True,
+    download_dir: Annotated[str | None, Field(description="Where to save the files. Default: ~/mocapless/<job>/ (or MOCAPLESS_DOWNLOAD_DIR).")] = None,
+) -> dict[str, Any]:
+    """Generate an animation from a sentence on the user's character, wait for it, and download the files. Charges credits (see plan_motion first if the price matters); a failed job is refunded automatically."""
+    if quality not in ("standard", "best"):
+        raise MocaplessError("quality must be 'standard' or 'best'")
+    c = client()
+    job = c.generate(
+        prompt,
+        asset_id=character_id,
+        formats=[f.lower() for f in formats],
+        loop=loop,
+        samples=2 if quality == "best" else 1,
+    )
+    if not wait:
+        return _job_summary(job)
+    job = c.wait_job(job["id"])
+    summary = _job_summary(job)
+    if job.get("status") == "succeeded":
+        summary["files"] = c.download(job, download_dir or _default_dir(job["id"]))
+    elif job.get("status") == "failed":
+        summary["hint"] = "The credits for this job were refunded." if job.get("creditsRefunded") else None
+    return summary
+
+
+def get_job(
+    job_id: Annotated[str, Field(description="A job id from generate_animation.")],
+    download_dir: Annotated[str | None, Field(description="If set and the job succeeded, download the files here.")] = None,
+) -> dict[str, Any]:
+    """Status of a generation, and its files once it has finished."""
+    job = client().job(job_id)
+    summary = _job_summary(job)
+    if download_dir and job.get("status") == "succeeded":
+        summary["files"] = client().download(job, download_dir)
+    return summary
+
+
+def recent_animations(
+    limit: Annotated[int, Field(description="How many, newest first.", ge=1, le=50)] = 10,
+) -> list[dict[str, Any]]:
+    """The account's recent generations."""
+    return [_job_summary(j) for j in client().jobs(limit)]
+
+
+def share_link(
+    job_id: Annotated[str, Field(description="A finished job id.")],
+) -> dict[str, Any]:
+    """A public link to watch the animation in the browser - the clip only, not the files."""
+    return client().share(job_id)
+
+
+for tool in (account, list_characters, upload_character, plan_motion, generate_animation, get_job, recent_animations, share_link):
+    mcp.add_tool(tool)
+
+
+@mcp.prompt()
+def animate(what: str) -> str:
+    """Generate an animation for the current character from a description."""
+    return (
+        f"Use Mocapless to animate the user's character: {what}\n"
+        "First call plan_motion to check the beats and the price. If it is affordable, call "
+        "generate_animation with the same prompt, then tell the user where the files were saved "
+        "and how long the clip is."
+    )
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

mocapless_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "mocapless-mcp"
+version = "0.1.0"
+description = "MCP server for Mocapless: generate character animation from text inside Claude, Cursor and any MCP client."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Mocapless", email = "hello@mocapless.com" }]
+keywords = ["mcp", "animation", "text-to-motion", "fbx", "mocap"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Topic :: Multimedia :: Graphics :: 3D Modeling",
+]
+dependencies = [
+  "mcp>=1.10,<2",
+  "httpx>=0.27",
+  "pydantic>=2.5",
+]
+
+[project.urls]
+Homepage = "https://mocapless.com"
+Documentation = "https://mocapless.com/developers"
+
+[project.scripts]
+mocapless-mcp = "mocapless_mcp.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["mocapless_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]