yuuno-mcp 0.1.0__tar.gz

yuuno_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: yuuno-mcp
+Version: 0.1.0
+Summary: MCP server for yuuno.tech adflow — build and run AI media canvases from Claude/Cursor.
+Author: yuuno.tech
+License: Proprietary
+Project-URL: Homepage, https://app.yuuno.tech
+Project-URL: Documentation, https://app.yuuno.tech/settings/organization/api
+Keywords: mcp,model-context-protocol,yuuno,adflow,ai-video,llm-tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp~=3.4
+Requires-Dist: httpx
+Provides-Extra: http
+Requires-Dist: uvicorn[standard]; extra == "http"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: respx; extra == "dev"
+Requires-Dist: uvicorn[standard]; extra == "dev"
+
+# yuuno-mcp
+
+MCP server for [yuuno.tech](https://app.yuuno.tech) **adflow** — drive the
+node-based AI media canvas from an MCP client (Claude Code, Claude Desktop,
+Cursor, …). You become an agent on the board: create sessions, wire up
+image/video/audio/text generation nodes, run flows, and read results — the
+same canvas the in-app chat edits, so your changes appear live in the browser.
+
+## Get an API key
+
+Mint a workspace key at
+**app.yuuno.tech → Settings → Organization → API**
+(`https://app.yuuno.tech/settings/organization/api`). It's a 40-character hex
+string scoped to your workspace. Rotating it (Reset) invalidates the previous
+key for every connected client in that workspace.
+
+## Connect
+
+### Claude Code
+
+Local (stdio, recommended — works everywhere):
+
+```bash
+claude mcp add yuuno -e YUUNO_API_KEY=<your-40-hex-key> -- uvx yuuno-mcp
+```
+
+Hosted (Streamable HTTP — no local install):
+
+```bash
+claude mcp add --transport http yuuno https://mcp.yuuno.tech/mcp \
+  --header "Authorization: Bearer <your-40-hex-key>"
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (stdio; Desktop connectors don't pass
+custom headers, so use stdio):
+
+```json
+{
+  "mcpServers": {
+    "yuuno": {
+      "command": "uvx",
+      "args": ["yuuno-mcp"],
+      "env": { "YUUNO_API_KEY": "<your-40-hex-key>" }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (or a project `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "yuuno": {
+      "url": "https://mcp.yuuno.tech/mcp",
+      "headers": { "Authorization": "Bearer ${env:YUUNO_API_KEY}" }
+    }
+  }
+}
+```
+
+Cursor also supports stdio (`"command": "uvx", "args": ["yuuno-mcp"]`).
+
+> **Client support note:** remote (hosted HTTP + `Authorization` header) works
+> today in Claude Code and Cursor. Claude Desktop and claude.ai custom
+> connectors don't pass static headers — use stdio (`uvx`) for Desktop; OAuth
+> for claude.ai is a later release.
+
+## First moves for the agent
+
+Call **`get_cheatsheet`** once at the start of a session — it explains the 18
+node types, the DAG op rules, the run lifecycle, and model selection. Then a
+typical build is: `list_models` → `create_session` → `apply_ops_batch` (build
+the graph) → `auto_layout` → `estimate_credits` → `run_flow` → `wait_for_run`.
+`list_examples` returns ready-to-apply op recipes.
+
+## Tools (37)
+
+- **Sessions** — `whoami`, `create_session`, `list_sessions`, `get_dag`,
+  `copy_session`, `delete_session`
+- **DAG ops** — `add_node`, `add_node_with_inputs`, `update_node`,
+  `remove_node`, `add_edge`, `update_edge`, `remove_edge`, `apply_ops_batch`,
+  `set_uploaded_assets`
+- **Structure** — `add_group`, `move_to_group`, `ungroup`, `replace_edge`,
+  `insert_node_on_edge`, `bypass_node`, `list_node_io`, `auto_layout`
+- **Runs** — `run_flow`, `get_run_status`, `list_runs`, `wait_for_run`,
+  `estimate_credits`
+- **Generate / catalog** — `execute_utility_node`, `wait_for_task`,
+  `generate_text`, `generate_asset`, `list_models`, `get_model_schema`,
+  `upload_asset`
+- **Docs** — `get_cheatsheet`, `list_examples` (also exposed as MCP resources
+  `yuuno://cheatsheet` and `yuuno://examples/<name>`)
+
+## Configuration
+
+| var | default | purpose |
+|---|---|---|
+| `YUUNO_API_KEY` | — | workspace API key (40 hex), stdio mode |
+| `YUUNO_BACKEND_URL` | `https://api.yuuno.tech` | Django backend base URL |
+| `YUUNO_APP_URL` | `https://app.yuuno.tech` | SPA base URL (canvas links) |
+| `YUUNO_WORKSPACE_ID` | — | optional workspace uuid (`X-API-ID`), stdio only |
+| `YUUNO_JWT` | — | dev fallback: SimpleJWT access token |
+| `MCP_HTTP_HOST` / `MCP_HTTP_PORT` | `127.0.0.1` / `8765` | `--transport http` bind |
+
+In hosted HTTP mode the key is never held server-side — each request carries
+its own `Authorization: Bearer <key>`, verified against the backend, and the
+server proxies that exact key to Django (no cross-tenant state).
+
+## Development
+
+```bash
+cd mcp
+python3.12 -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/python -m pytest tests -q
+```
+
+The contract-parity test (`tests/test_parity.py`) imports
+`adflow.dag_protocol.constants` from the monorepo root and asserts the mirrored
+constants match; it auto-skips outside the monorepo. Deploy artifacts (systemd
+units, nginx config, operator runbook) are under [`deploy/`](deploy/).

yuuno_mcp-0.1.0/README.md

@@ -0,0 +1,125 @@
+# yuuno-mcp
+
+MCP server for [yuuno.tech](https://app.yuuno.tech) **adflow** — drive the
+node-based AI media canvas from an MCP client (Claude Code, Claude Desktop,
+Cursor, …). You become an agent on the board: create sessions, wire up
+image/video/audio/text generation nodes, run flows, and read results — the
+same canvas the in-app chat edits, so your changes appear live in the browser.
+
+## Get an API key
+
+Mint a workspace key at
+**app.yuuno.tech → Settings → Organization → API**
+(`https://app.yuuno.tech/settings/organization/api`). It's a 40-character hex
+string scoped to your workspace. Rotating it (Reset) invalidates the previous
+key for every connected client in that workspace.
+
+## Connect
+
+### Claude Code
+
+Local (stdio, recommended — works everywhere):
+
+```bash
+claude mcp add yuuno -e YUUNO_API_KEY=<your-40-hex-key> -- uvx yuuno-mcp
+```
+
+Hosted (Streamable HTTP — no local install):
+
+```bash
+claude mcp add --transport http yuuno https://mcp.yuuno.tech/mcp \
+  --header "Authorization: Bearer <your-40-hex-key>"
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (stdio; Desktop connectors don't pass
+custom headers, so use stdio):
+
+```json
+{
+  "mcpServers": {
+    "yuuno": {
+      "command": "uvx",
+      "args": ["yuuno-mcp"],
+      "env": { "YUUNO_API_KEY": "<your-40-hex-key>" }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (or a project `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "yuuno": {
+      "url": "https://mcp.yuuno.tech/mcp",
+      "headers": { "Authorization": "Bearer ${env:YUUNO_API_KEY}" }
+    }
+  }
+}
+```
+
+Cursor also supports stdio (`"command": "uvx", "args": ["yuuno-mcp"]`).
+
+> **Client support note:** remote (hosted HTTP + `Authorization` header) works
+> today in Claude Code and Cursor. Claude Desktop and claude.ai custom
+> connectors don't pass static headers — use stdio (`uvx`) for Desktop; OAuth
+> for claude.ai is a later release.
+
+## First moves for the agent
+
+Call **`get_cheatsheet`** once at the start of a session — it explains the 18
+node types, the DAG op rules, the run lifecycle, and model selection. Then a
+typical build is: `list_models` → `create_session` → `apply_ops_batch` (build
+the graph) → `auto_layout` → `estimate_credits` → `run_flow` → `wait_for_run`.
+`list_examples` returns ready-to-apply op recipes.
+
+## Tools (37)
+
+- **Sessions** — `whoami`, `create_session`, `list_sessions`, `get_dag`,
+  `copy_session`, `delete_session`
+- **DAG ops** — `add_node`, `add_node_with_inputs`, `update_node`,
+  `remove_node`, `add_edge`, `update_edge`, `remove_edge`, `apply_ops_batch`,
+  `set_uploaded_assets`
+- **Structure** — `add_group`, `move_to_group`, `ungroup`, `replace_edge`,
+  `insert_node_on_edge`, `bypass_node`, `list_node_io`, `auto_layout`
+- **Runs** — `run_flow`, `get_run_status`, `list_runs`, `wait_for_run`,
+  `estimate_credits`
+- **Generate / catalog** — `execute_utility_node`, `wait_for_task`,
+  `generate_text`, `generate_asset`, `list_models`, `get_model_schema`,
+  `upload_asset`
+- **Docs** — `get_cheatsheet`, `list_examples` (also exposed as MCP resources
+  `yuuno://cheatsheet` and `yuuno://examples/<name>`)
+
+## Configuration
+
+| var | default | purpose |
+|---|---|---|
+| `YUUNO_API_KEY` | — | workspace API key (40 hex), stdio mode |
+| `YUUNO_BACKEND_URL` | `https://api.yuuno.tech` | Django backend base URL |
+| `YUUNO_APP_URL` | `https://app.yuuno.tech` | SPA base URL (canvas links) |
+| `YUUNO_WORKSPACE_ID` | — | optional workspace uuid (`X-API-ID`), stdio only |
+| `YUUNO_JWT` | — | dev fallback: SimpleJWT access token |
+| `MCP_HTTP_HOST` / `MCP_HTTP_PORT` | `127.0.0.1` / `8765` | `--transport http` bind |
+
+In hosted HTTP mode the key is never held server-side — each request carries
+its own `Authorization: Bearer <key>`, verified against the backend, and the
+server proxies that exact key to Django (no cross-tenant state).
+
+## Development
+
+```bash
+cd mcp
+python3.12 -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/python -m pytest tests -q
+```
+
+The contract-parity test (`tests/test_parity.py`) imports
+`adflow.dag_protocol.constants` from the monorepo root and asserts the mirrored
+constants match; it auto-skips outside the monorepo. Deploy artifacts (systemd
+units, nginx config, operator runbook) are under [`deploy/`](deploy/).

yuuno_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "yuuno-mcp"
+version = "0.1.0"
+description = "MCP server for yuuno.tech adflow — build and run AI media canvases from Claude/Cursor."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "Proprietary" }
+authors = [{ name = "yuuno.tech" }]
+keywords = ["mcp", "model-context-protocol", "yuuno", "adflow", "ai-video", "llm-tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "fastmcp~=3.4",
+    "httpx",
+]
+
+[project.optional-dependencies]
+# Hosted Streamable-HTTP transport (uvicorn yuuno_mcp.server:app). Not needed
+# for the stdio transport (uvx yuuno-mcp), which is the default.
+http = [
+    "uvicorn[standard]",
+]
+dev = [
+    "pytest",
+    "pytest-asyncio",
+    "respx",
+    "uvicorn[standard]",
+]
+
+[project.urls]
+Homepage = "https://app.yuuno.tech"
+Documentation = "https://app.yuuno.tech/settings/organization/api"
+
+[project.scripts]
+yuuno-mcp = "yuuno_mcp.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

yuuno_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

yuuno_mcp-0.1.0/src/yuuno_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""yuuno-mcp — MCP server for yuuno.tech adflow canvases."""
+
+__version__ = "0.1.0"

yuuno_mcp-0.1.0/src/yuuno_mcp/auth.py

@@ -0,0 +1,151 @@
+"""Hosted-HTTP token verification (Bearer API key → backend probe).
+
+Transports:
+
+- stdio (single-tenant): no verifier involved; the user's API key comes
+  from ``YUUNO_API_KEY`` in the environment (see server.default_client_factory).
+- hosted Streamable HTTP (multi-tenant): each request carries the caller's
+  key as ``Authorization: Bearer <40-hex>``; FastMCP's auth layer verifies
+  it via :class:`YuunoTokenVerifier` and tools recover it per-request via
+  ``get_access_token()``.
+
+The verifier is a thin gate: it checks the strict 40-hex format, then probes
+the Django backend (default ``GET /api/v1/me/`` with ``X-API-KEY``). Probe
+outcomes are tri-state:
+
+- VALID (2xx)        → cached positive for 60s.
+- INVALID (401/403)  → cached negative for 60s.
+- TRANSIENT (other statuses / transport error) → NEVER cached; a
+  previously-verified key keeps working for up to 10 minutes (stale-grace),
+  otherwise the single request is rejected without poisoning the cache.
+
+Real authorization is enforced by Django on every proxied call — tools
+always forward the caller's own key.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from typing import Literal
+
+import httpx
+from fastmcp.server.auth import AccessToken, TokenVerifier
+
+from yuuno_mcp.config import Settings
+
+# Strict: 40 lowercase/uppercase hex chars, no prefix (secrets.token_hex(20)).
+API_KEY_RE = re.compile(r"^[0-9a-fA-F]{40}$")
+
+VERIFY_CACHE_TTL_SECONDS = 60.0
+STALE_GRACE_SECONDS = 600.0
+MAX_CACHE_ENTRIES = 1024
+
+ProbeOutcome = Literal["valid", "invalid", "transient"]
+
+
+def is_valid_key_format(token: str) -> bool:
+    """True iff *token* is a well-formed 40-hex yuuno API key."""
+    return bool(API_KEY_RE.fullmatch(token or ""))
+
+
+class YuunoTokenVerifier(TokenVerifier):
+    """Verify a Bearer API key against the yuuno backend.
+
+    Rejects anything that is not exactly 40 hex chars, then probes
+    ``GET {backend}{probe_path}`` (default /api/v1/me/) with
+    ``X-API-KEY: <key>``. See module
+    docstring for the tri-state caching policy.
+    """
+
+    def __init__(
+        self,
+        settings: Settings,
+        *,
+        http_client: httpx.AsyncClient | None = None,
+        cache_ttl: float = VERIFY_CACHE_TTL_SECONDS,
+        stale_grace: float = STALE_GRACE_SECONDS,
+        max_entries: int = MAX_CACHE_ENTRIES,
+    ) -> None:
+        super().__init__()
+        self._settings = settings
+        self._probe_url = settings.backend_url + settings.auth_probe_path
+        self._cache_ttl = cache_ttl
+        self._stale_grace = stale_grace
+        self._max_entries = max_entries
+        # key -> (inserted_monotonic, verified: bool)
+        self._cache: dict[str, tuple[float, bool]] = {}
+        self._http = http_client
+
+    async def _probe(self, token: str) -> ProbeOutcome:
+        """Tri-state backend probe.
+
+        2xx → valid; 401/403 → invalid (the backend affirmatively rejected
+        the key); anything else (5xx, 429, unexpected 4xx like a
+        misconfigured probe path, transport errors) → transient — the
+        backend did NOT judge the key, so the outcome must not be cached.
+        """
+        client = self._http
+        owns_client = client is None
+        if owns_client:
+            client = httpx.AsyncClient(timeout=10.0)
+        try:
+            response = await client.get(self._probe_url, headers={"X-API-KEY": token})
+        except httpx.HTTPError:
+            return "transient"
+        finally:
+            if owns_client:
+                await client.aclose()
+        if response.is_success:
+            return "valid"
+        if response.status_code in (401, 403):
+            return "invalid"
+        return "transient"
+
+    def _cache_put(self, token: str, verified: bool, now: float) -> None:
+        self._cache[token] = (now, verified)
+        if len(self._cache) <= self._max_entries:
+            return
+        # Sweep entries past their maximum useful lifetime (stale-grace
+        # covers the positive case; negatives expire earlier anyway).
+        cutoff = now - self._stale_grace
+        for key in [k for k, (t, _) in self._cache.items() if t < cutoff]:
+            del self._cache[key]
+        # Still over? Drop oldest-inserted first.
+        while len(self._cache) > self._max_entries:
+            oldest = min(self._cache.items(), key=lambda kv: kv[1][0])[0]
+            del self._cache[oldest]
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        if not is_valid_key_format(token):
+            return None
+
+        now = time.monotonic()
+        entry = self._cache.get(token)
+        if entry is not None and now - entry[0] < self._cache_ttl:
+            verified = entry[1]
+        else:
+            outcome = await self._probe(token)
+            if outcome == "valid":
+                self._cache_put(token, True, now)
+                verified = True
+            elif outcome == "invalid":
+                self._cache_put(token, False, now)
+                verified = False
+            else:  # transient — never cached
+                # Stale-grace: keep serving a previously-verified key for up
+                # to 10 min so one backend 503 can't lock a valid tenant out.
+                verified = (
+                    entry is not None
+                    and entry[1]
+                    and now - entry[0] < self._stale_grace
+                )
+
+        if not verified:
+            return None
+        return AccessToken(
+            token=token,
+            client_id="yuuno-api-key",
+            scopes=[],
+            expires_at=None,
+        )

yuuno_mcp-0.1.0/src/yuuno_mcp/cli.py

@@ -0,0 +1,61 @@
+"""Command-line entry point: ``yuuno-mcp [--transport stdio|http]``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from yuuno_mcp import __version__
+from yuuno_mcp.config import Settings
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="yuuno-mcp",
+        description=(
+            "MCP server for yuuno.tech adflow. stdio mode (default) expects "
+            "YUUNO_API_KEY in the environment; http mode serves Streamable "
+            "HTTP with per-request Bearer keys."
+        ),
+    )
+    parser.add_argument(
+        "--transport",
+        choices=("stdio", "http"),
+        default="stdio",
+        help="Transport to serve (default: stdio)",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"yuuno-mcp {__version__}"
+    )
+    args = parser.parse_args(argv)
+
+    settings = Settings.from_env()
+
+    if args.transport == "http":
+        import uvicorn
+
+        # Reuse the module-level ASGI app (the same object systemd runs via
+        # ``uvicorn yuuno_mcp.server:app``) so both entry points are identical.
+        from yuuno_mcp.server import app
+
+        uvicorn.run(app, host=settings.http_host, port=settings.http_port)
+        return
+
+    # stdio: single-tenant; a missing key fails fast with guidance instead of
+    # failing on the first tool call.
+    if not settings.api_key and not settings.jwt:
+        print(
+            "yuuno-mcp: YUUNO_API_KEY is not set. Generate an API key at "
+            f"{settings.app_url}/settings/organization/api and add it to "
+            "your MCP server env config.",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+
+    from yuuno_mcp.server import create_server
+
+    create_server(settings).run()
+
+
+if __name__ == "__main__":
+    main()