@dpantani/tdmcp 0.1.0

package/td/modules/mcp/controllers/api_controller.py

@@ -0,0 +1,240 @@
+"""HTTP router for the tdmcp bridge.
+
+Maps the REST endpoints the Node MCP server calls onto the service layer and
+wraps every response in the standard `{ ok, data | error }` envelope.
+
+Node-path URL segments are percent-encoded by the client (a TD path contains
+slashes), so they are `unquote`d here.
+"""
+
+import hmac
+import json
+import os
+from urllib.parse import parse_qs, unquote, urlparse
+
+from mcp import events
+from mcp.services import analysis_service, api_service, batch_service, preview_service
+
+
+def _required_token():
+    """The shared bearer token the bridge enforces, or None when auth is off.
+
+    Off by default (zero-config local flow). Launch TouchDesigner with the
+    `TDMCP_BRIDGE_TOKEN` environment variable set — to the SAME value the Node
+    server uses — to require authentication on every request.
+    """
+    token = os.environ.get("TDMCP_BRIDGE_TOKEN")
+    return token or None
+
+
+def _exec_allowed():
+    """Whether the arbitrary-code endpoints (`/api/exec`, node `method`) are enabled.
+
+    On by default. Set `TDMCP_BRIDGE_ALLOW_EXEC` to 0/false/no/off in TouchDesigner's
+    environment to reject them at the bridge — defense in depth that holds even against
+    a direct network caller, independent of the Node server's own `TDMCP_RAW_PYTHON`
+    gate (which only hides the tools client-side). Structured endpoints stay available.
+    """
+    raw = os.environ.get("TDMCP_BRIDGE_ALLOW_EXEC")
+    if raw is None:
+        return True
+    return raw.strip().lower() not in ("0", "false", "no", "off")
+
+
+def _find_header(request, name):
+    """Case-insensitively find an HTTP header in TouchDesigner's request dict.
+
+    TD builds vary in how they expose headers (top-level keys, or nested under a
+    'headers'/'header'/'fields' dict), so scan defensively for the first match.
+    """
+    target = name.lower()
+
+    def scan(node, depth=0):
+        if not isinstance(node, dict) or depth > 2:
+            return None
+        for key, value in node.items():
+            if isinstance(key, str) and key.lower() == target and isinstance(value, str):
+                return value
+        for nested in ("headers", "header", "fields"):
+            sub = node.get(nested)
+            hit = scan(sub, depth + 1) if isinstance(sub, dict) else None
+            if hit is not None:
+                return hit
+        return None
+
+    return scan(request)
+
+
+def _check_auth(request):
+    token = _required_token()
+    if not token:
+        return  # auth disabled (default)
+    provided = (_find_header(request, "authorization") or "").strip()
+    if not hmac.compare_digest(provided, "Bearer " + token):
+        raise PermissionError("Unauthorized: missing or invalid bearer token.")
+
+
+def _qs(query, key, default=None):
+    values = query.get(key)
+    return values[0] if values else default
+
+
+def _parse_body(request):
+    data = request.get("data")
+    if isinstance(data, (bytes, bytearray)):
+        data = data.decode("utf-8", "ignore")
+    if not data:  # None, "", b"" all become an empty body
+        return {}
+    if isinstance(data, str):
+        data = data.strip()
+        if not data:
+            return {}
+        return json.loads(data)
+    return data
+
+
+def _node_path(segments):
+    # TouchDesigner's WebServer DAT decodes %2F into "/", so a node path arrives
+    # split across URL segments with its leading slash dropped. Re-join (unquote is
+    # a no-op when already decoded) and restore the leading slash.
+    raw = "/".join(unquote(s) for s in segments)
+    return "/" + raw.lstrip("/")
+
+
+def _route(method, path, query, body):
+    parts = [p for p in path.split("/") if p]
+    if not parts or parts[0] != "api":
+        raise ValueError("Not found: %s" % path)
+    rest = parts[1:]
+
+    if rest == ["info"] and method == "GET":
+        return api_service.get_info()
+
+    if rest == ["nodes"] and method == "POST":
+        return api_service.create_node(
+            body["parent_path"], body["type"], body.get("name"), body.get("parameters")
+        )
+    if rest == ["nodes"] and method == "GET":
+        return api_service.get_nodes(_qs(query, "parent"))
+
+    if rest == ["exec"] and method == "POST":
+        if not _exec_allowed():
+            raise PermissionError("Forbidden: arbitrary code execution is disabled (TDMCP_BRIDGE_ALLOW_EXEC=0).")
+        return api_service.exec_script(body["script"], body.get("return_output", True))
+
+    if rest == ["batch"] and method == "POST":
+        return batch_service.run(body.get("operations", []))
+
+    if rest[0] == "nodes" and len(rest) >= 2:
+        if rest[-1] == "method" and method == "POST":
+            if not _exec_allowed():
+                raise PermissionError(
+                    "Forbidden: arbitrary method calls are disabled (TDMCP_BRIDGE_ALLOW_EXEC=0)."
+                )
+            return api_service.call_method(
+                _node_path(rest[1:-1]),
+                body["method"],
+                body.get("args", []),
+                body.get("kwargs", {}),
+            )
+        if rest[-1] == "errors" and method == "GET":
+            return api_service.get_node_errors(_node_path(rest[1:-1]), recursive=False)
+        node_path = _node_path(rest[1:])
+        if method == "GET":
+            return api_service.get_node(node_path)
+        if method == "PATCH":
+            return api_service.update_parameters(node_path, body.get("parameters", {}))
+        if method == "DELETE":
+            return api_service.delete_node(node_path)
+
+    if rest[0] == "preview" and method == "GET" and len(rest) >= 2:
+        return preview_service.capture(
+            _node_path(rest[1:]), int(_qs(query, "width", 640)), int(_qs(query, "height", 360))
+        )
+
+    if rest[0] == "network" and method == "GET" and len(rest) >= 3:
+        kind = rest[-1]
+        node_path = _node_path(rest[1:-1])
+        if kind == "errors":
+            return analysis_service.errors(node_path)
+        if kind == "topology":
+            return analysis_service.topology(node_path, recursive=_qs(query, "recursive") == "true")
+        if kind == "performance":
+            return analysis_service.performance(node_path)
+
+    raise ValueError("Unsupported %s %s" % (method, path))
+
+
+def _send(response, status, payload):
+    response["statusCode"] = status
+    response["statusReason"] = "OK" if status < 400 else "Error"
+    response["content-type"] = "application/json"
+    response["data"] = json.dumps(payload)
+    return response
+
+
+def _merge_query(request, query):
+    # TD may surface query params separately from the uri; merge defensively.
+    for key in ("pars", "params", "queryString", "query", "args"):
+        extra = request.get(key)
+        if isinstance(extra, dict):
+            for k, v in extra.items():
+                query.setdefault(k, v if isinstance(v, list) else [v])
+        elif isinstance(extra, str) and extra:
+            for k, v in parse_qs(extra).items():
+                query.setdefault(k, v)
+    return query
+
+
+def _emit_node_errors(webserver, path):
+    if not path:
+        return
+    try:
+        report = api_service.get_node_errors(path, recursive=False)
+    except Exception:  # noqa: BLE001
+        return
+    for err in report.get("errors", []):
+        events.broadcast(webserver, "node.error", err)
+
+
+def _emit_event(webserver, method, path, data):
+    if webserver is None:
+        return
+    parts = [p for p in path.split("/") if p]
+    rest = parts[1:] if parts[:1] == ["api"] else []
+    try:
+        if method == "POST" and rest == ["nodes"]:
+            events.broadcast(webserver, "node.created", data)
+            _emit_node_errors(webserver, (data or {}).get("path"))
+        elif method == "PATCH" and len(rest) >= 2 and rest[0] == "nodes":
+            _emit_node_errors(webserver, (data or {}).get("path"))
+        elif method == "DELETE" and len(rest) >= 2 and rest[0] == "nodes":
+            events.broadcast(webserver, "node.deleted", data)
+        elif method == "POST" and rest == ["batch"]:
+            for result in (data or {}).get("results", []):
+                if not result.get("ok"):
+                    continue
+                if result.get("action") == "create":
+                    node = result.get("data")
+                    events.broadcast(webserver, "node.created", node)
+                    _emit_node_errors(webserver, (node or {}).get("path"))
+                elif result.get("action") == "delete":
+                    events.broadcast(webserver, "node.deleted", {"path": result.get("path")})
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def handle(request, response, webserver=None):
+    try:
+        _check_auth(request)
+        method = (request.get("method") or "GET").upper()
+        parsed = urlparse(request.get("uri", "/"))
+        query = _merge_query(request, parse_qs(parsed.query))
+        body = _parse_body(request)
+        data = _route(method, parsed.path, query, body)
+        _emit_event(webserver, method, parsed.path, data)
+        return _send(response, 200, {"ok": True, "data": data})
+    except PermissionError as exc:
+        return _send(response, 401, {"ok": False, "error": {"message": str(exc)}})
+    except Exception as exc:  # noqa: BLE001
+        return _send(response, 400, {"ok": False, "error": {"message": str(exc)}})

package/td/modules/mcp/dev.py

@@ -0,0 +1,40 @@
+"""Developer helper: hot-reload the bridge's Python in a running TouchDesigner.
+
+Editing files under ``td/`` does NOT reload the modules already imported by a running
+TouchDesigner, so the bridge keeps serving the stale code it loaded at project open.
+After editing the bridge, call :func:`reload_bridge` -- from the Textport
+(``from mcp import dev; dev.reload_bridge()``) or via the ``execute_python_script``
+tool -- to pick up the changes without reopening the project.
+"""
+
+import importlib
+import sys
+
+
+def reload_bridge():
+    """Reimport every loaded ``mcp.*`` / ``utils.*`` module, deepest first.
+
+    Controllers import service modules as module objects (``from mcp.services import x``),
+    so reloading the modules in place propagates the new functions to their callers.
+    Modules are reloaded deepest-first so packages re-bind to freshly reloaded submodules.
+
+    Returns the list of reloaded module names.
+    """
+    targets = [
+        name
+        for name in sys.modules
+        if name in ("mcp", "utils") or name.startswith("mcp.") or name.startswith("utils.")
+    ]
+    targets.sort(key=lambda name: name.count("."), reverse=True)
+    reloaded = []
+    for name in targets:
+        module = sys.modules.get(name)
+        if module is None:
+            continue
+        try:
+            importlib.reload(module)
+            reloaded.append(name)
+        except Exception:
+            # A module that fails to reload (e.g. caught mid-edit) must not abort the rest.
+            pass
+    return reloaded

package/td/modules/mcp/events.py

@@ -0,0 +1,25 @@
+"""Broadcast TD-side events to all connected WebSocket clients.
+
+Events use the shape { "event": "<name>", "data": <payload> }, matching what the
+Node server's event stream expects.
+"""
+
+import json
+
+
+def broadcast(webserver, event, data=None):
+    if webserver is None:
+        return
+    try:
+        message = json.dumps({"event": event, "data": data})
+    except Exception:  # noqa: BLE001
+        return
+    try:
+        connections = webserver.webSocketConnections or []
+    except Exception:  # noqa: BLE001
+        return
+    for client in connections:
+        try:
+            webserver.webSocketSendText(client, message)
+        except Exception:  # noqa: BLE001
+            pass

package/td/modules/mcp/install.py

@@ -0,0 +1,155 @@
+"""One-call installer for the tdmcp bridge.
+
+Once `td/modules` is on TouchDesigner's Python module path (Preferences ->
+"Python 64-bit Module Path"), an artist can bring the whole bridge up with a
+single line in the Textport:
+
+    from mcp import install; install.run()
+
+It creates a tidy `tdmcp_bridge` base COMP containing a Web Server DAT (port
+9980) and its callbacks, then activates it. Idempotent: re-running reconfigures
+the existing ops. Pass `export_tox="/path/mcp_webserver_base.tox"` to also save a
+reusable component you can drag into any project.
+"""
+
+
+def _callbacks_source(modules_dir=None):
+    header = ""
+    if modules_dir:
+        header = (
+            "import sys\n"
+            "if %r not in sys.path:\n"
+            "    sys.path.insert(0, %r)\n\n" % (modules_dir, modules_dir)
+        )
+    return header + (
+        "def onHTTPRequest(webServerDAT, request, response):\n"
+        "    from mcp.controllers import api_controller  # per-request: hot-reloads after cache clear\n"
+        "    return api_controller.handle(request, response, webServerDAT)\n\n"
+        "def onWebSocketOpen(webServerDAT, client, uri): return\n"
+        "def onWebSocketReceiveText(webServerDAT, client, data): return\n"
+        "def onWebSocketReceiveBinary(webServerDAT, client, data): return\n"
+        "def onWebSocketReceivePing(webServerDAT, client, data):\n"
+        "    webServerDAT.webSocketSendPong(client, data=data)\n"
+        "def onWebSocketReceivePong(webServerDAT, client, data): return\n"
+        "def onServerStart(webServerDAT): return\n"
+        "def onServerStop(webServerDAT): return\n"
+    )
+
+
+def _event_hooks_source(modules_dir=None):
+    header = ""
+    if modules_dir:
+        header = (
+            "import sys\n"
+            "if %r not in sys.path:\n"
+            "    sys.path.insert(0, %r)\n\n" % (modules_dir, modules_dir)
+        )
+    return header + (
+        "def _broadcast(event, data):\n"
+        "    try:\n"
+        "        from mcp import events\n"
+        "        events.broadcast(me.parent().op('webserver'), event, data)\n"
+        "    except Exception:\n"
+        "        pass\n\n"
+        "def onFrameEnd(frame):\n"
+        "    try:\n"
+        "        f = int(frame)\n"
+        "        if f % 30 == 0:\n"
+        "            _broadcast('timeline.frame', {'frame': f, 'seconds': float(absTime.seconds)})\n"
+        "        if f % 120 == 0:\n"
+        "            scope = me.parent().parent()\n"
+        "            if scope is not None:\n"
+        "                emitted = 0\n"
+        "                for child in scope.findChildren(depth=3):\n"
+        "                    try:\n"
+        "                        ct = float(getattr(child, 'cookTime', 0.0) or 0.0)\n"
+        "                    except Exception:\n"
+        "                        ct = 0.0\n"
+        "                    if ct > 5.0:\n"
+        "                        _broadcast('node.cook', {'path': child.path, 'cook_time_ms': ct})\n"
+        "                        emitted += 1\n"
+        "                        if emitted >= 10:\n"
+        "                            break\n"
+        "    except Exception:\n"
+        "        pass\n\n"
+        "def onProjectPostSave():\n"
+        "    try:\n"
+        "        _broadcast('project.saved', {'filename': project.name})\n"
+        "    except Exception:\n"
+        "        pass\n\n"
+        "def onStart(): return\n"
+        "def onCreate(): return\n"
+    )
+
+
+def run(port=9980, parent_path="/project1", container="tdmcp_bridge", modules_dir=None, export_tox=None):
+    import td  # TouchDesigner globals are only available via the td module here
+
+    if modules_dir:
+        import sys
+
+        if modules_dir not in sys.path:
+            sys.path.insert(0, modules_dir)
+
+    root = td.op(parent_path) or td.op("/")
+    comp = root.op(container) or root.create(td.baseCOMP, container)
+
+    callbacks = comp.op("callbacks") or comp.create(td.textDAT, "callbacks")
+    callbacks.text = _callbacks_source(modules_dir)
+
+    server = comp.op("webserver") or comp.create(td.webserverDAT, "webserver")
+    server.par.port = port
+    server.par.callbacks = callbacks
+    server.par.active = True
+
+    # Execute DAT that emits project.saved / timeline.frame events over WebSocket.
+    hooks = comp.op("events_hook") or comp.create(td.executeDAT, "events_hook")
+    hooks.text = _event_hooks_source(modules_dir)
+    hooks.par.active = True
+    hooks.par.frameend = True
+    hooks.par.projectpostsave = True
+
+    if export_tox:
+        comp.save(export_tox)
+
+    print("[tdmcp] bridge running on port %d (%s)" % (port, comp.path))
+    print(
+        "[tdmcp] SECURITY: the Web Server DAT listens on ALL network interfaces and, by "
+        "default, executes arbitrary Python (the /api/exec and node-method endpoints) with "
+        "no authentication. On a shared/untrusted network, harden it: (1) set the "
+        "TDMCP_BRIDGE_TOKEN env var (same value on the Node server) to require a bearer "
+        "token; (2) set TDMCP_BRIDGE_ALLOW_EXEC=0 to refuse the arbitrary-code endpoints; "
+        "and/or firewall port %d to localhost." % port
+    )
+    return comp
+
+
+def export(path, modules_dir=None, port=9980, parent_path="/project1", container="tdmcp_bridge"):
+    """Build the bridge and save it as a reusable .tox you can drag into any project.
+
+    Run this once in your own TouchDesigner, commit the resulting .tox, and from
+    then on the bridge install is just drag-and-drop. Pass `modules_dir` (the
+    absolute path to `td/modules`) to bake the import path into the .tox so it
+    keeps working in projects that don't have that folder on the Preferences
+    "Python 64-bit Module Path"; otherwise the target machine still needs it set.
+
+        from mcp import install
+        install.export("/path/to/mcp_webserver_base.tox")
+    """
+    return run(
+        port=port,
+        parent_path=parent_path,
+        container=container,
+        modules_dir=modules_dir,
+        export_tox=path,
+    )
+
+
+def uninstall(parent_path="/project1", container="tdmcp_bridge"):
+    import td
+
+    root = td.op(parent_path) or td.op("/")
+    comp = root.op(container)
+    if comp is not None:
+        comp.destroy()
+        print("[tdmcp] bridge removed")

package/td/modules/mcp/services/__init__.py

@@ -0,0 +1 @@
+"""Business-logic services for the tdmcp bridge."""

package/td/modules/mcp/services/analysis_service.py

@@ -0,0 +1,64 @@
+"""Recursive network analysis: errors, topology and performance."""
+
+import td
+
+from mcp.services import api_service
+
+op = td.op  # TD globals are not available inside imported modules; reach via td
+
+
+def errors(path):
+    return api_service.get_node_errors(path, recursive=True)
+
+
+def topology(path, recursive=False):
+    root = op(path)
+    if root is None:
+        return {"nodes": [], "connections": []}
+    nodes, connections = [], []
+    if not hasattr(root, "findChildren"):
+        children = []
+    elif recursive:
+        children = root.findChildren()  # all descendants
+    else:
+        children = root.findChildren(depth=1)  # direct children only
+    for child in children:
+        nodes.append(
+            {"path": child.path, "type": api_service.op_type(child), "name": child.name}
+        )
+        for index, connector in enumerate(getattr(child, "inputConnectors", [])):
+            # `connector.connections` yields the source-side output Connectors; each
+            # carries its own `.index` (the source output index) and `.owner` (the op).
+            for source in getattr(connector, "connections", []):
+                owner = getattr(source, "owner", None)
+                if owner is None:
+                    continue
+                connections.append(
+                    {
+                        "source_path": owner.path,
+                        "source_output": int(getattr(source, "index", 0) or 0),
+                        "target_path": child.path,
+                        "target_input": index,
+                    }
+                )
+    return {"nodes": nodes, "connections": connections}
+
+
+def performance(path):
+    root = op(path)  # noqa: F821
+    if root is None:
+        return {"nodes": [], "total_cook_time_ms": 0.0}
+    nodes = []
+    total = 0.0
+    children = root.findChildren(depth=1) if hasattr(root, "findChildren") else []
+    for child in children:
+        cook_time = float(getattr(child, "cookTime", 0.0) or 0.0)
+        total += cook_time
+        nodes.append(
+            {
+                "path": child.path,
+                "cook_time_ms": cook_time,
+                "cook_count": int(getattr(child, "cookCount", 0) or 0),
+            }
+        )
+    return {"nodes": nodes, "total_cook_time_ms": total}