@dpantani/tdmcp 0.1.0 → 0.3.0

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

@@ -16,6 +16,18 @@ from mcp import events
 from mcp.services import analysis_service, api_service, batch_service, preview_service
 
 
+class _Unauthorized(PermissionError):
+    """Authentication failed — missing or invalid bearer token (HTTP 401)."""
+
+    status = 401
+
+
+class _Forbidden(PermissionError):
+    """Request refused regardless of credentials — cross-origin or exec disabled (HTTP 403)."""
+
+    status = 403
+
+
 def _required_token():
     """The shared bearer token the bridge enforces, or None when auth is off.
 
@@ -53,8 +65,14 @@ def _find_header(request, name):
         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
+            if isinstance(key, str) and key.lower() == target:
+                # TD builds vary: a header may arrive as a str or as a list of
+                # strings (repeated header). Accept a list's first string element
+                # so the Origin guard never fails *open* on a list-shaped header.
+                if isinstance(value, str):
+                    return value
+                if isinstance(value, (list, tuple)) and value and isinstance(value[0], str):
+                    return value[0]
         for nested in ("headers", "header", "fields"):
             sub = node.get(nested)
             hit = scan(sub, depth + 1) if isinstance(sub, dict) else None
@@ -71,7 +89,32 @@ def _check_auth(request):
         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.")
+        raise _Unauthorized("Unauthorized: missing or invalid bearer token.")
+
+
+_LOOPBACK_HOSTS = ("127.0.0.1", "localhost", "::1")
+
+
+def _check_origin(request):
+    """Reject browser-originated cross-origin requests (CSRF / DNS-rebinding).
+
+    The Node MCP server — the only legitimate caller — never sends an `Origin`
+    header. Browsers always attach one on cross-site requests, so a request
+    bearing a non-loopback `Origin` can only be a web page trying to drive the
+    bridge (e.g. a malicious site POSTing to http://127.0.0.1:9980/api/exec).
+    Under the default zero-auth + exec-on config that would be drive-by remote
+    code execution, so refuse it. Loopback origins stay allowed (a locally
+    served tool page still works) and same-origin / no-Origin callers are
+    unaffected. Holds even against a direct caller and independent of the
+    optional bearer token, mirroring the Node HTTP transport's DNS-rebinding
+    guard on its own port.
+    """
+    origin = _find_header(request, "origin")
+    if not origin:
+        return
+    host = urlparse(origin).hostname
+    if host not in _LOOPBACK_HOSTS:
+        raise _Forbidden("Forbidden: cross-origin request rejected (origin %r)." % origin)
 
 
 def _qs(query, key, default=None):
@@ -101,6 +144,20 @@ def _node_path(segments):
     return "/" + raw.lstrip("/")
 
 
+def _require(body, *keys):
+    """Raise a descriptive error when a required body field is absent.
+
+    Without this, `body["script"]`/`body["type"]` etc. raise a bare KeyError whose
+    message is only the missing key name — opaque to a direct caller. The Node
+    client validates inputs with zod first, so this only fires for raw callers.
+    """
+    if not isinstance(body, dict):
+        raise ValueError("Request body must be a JSON object.")
+    missing = [k for k in keys if k not in body]
+    if missing:
+        raise ValueError("Missing required field(s): %s." % ", ".join(missing))
+
+
 def _route(method, path, query, body):
     parts = [p for p in path.split("/") if p]
     if not parts or parts[0] != "api":
@@ -111,6 +168,7 @@ def _route(method, path, query, body):
         return api_service.get_info()
 
     if rest == ["nodes"] and method == "POST":
+        _require(body, "parent_path", "type")
         return api_service.create_node(
             body["parent_path"], body["type"], body.get("name"), body.get("parameters")
         )
@@ -119,7 +177,8 @@ def _route(method, path, query, body):
 
     if rest == ["exec"] and method == "POST":
         if not _exec_allowed():
-            raise PermissionError("Forbidden: arbitrary code execution is disabled (TDMCP_BRIDGE_ALLOW_EXEC=0).")
+            raise _Forbidden("Forbidden: arbitrary code execution is disabled (TDMCP_BRIDGE_ALLOW_EXEC=0).")
+        _require(body, "script")
         return api_service.exec_script(body["script"], body.get("return_output", True))
 
     if rest == ["batch"] and method == "POST":
@@ -128,9 +187,10 @@ def _route(method, path, query, body):
     if rest[0] == "nodes" and len(rest) >= 2:
         if rest[-1] == "method" and method == "POST":
             if not _exec_allowed():
-                raise PermissionError(
+                raise _Forbidden(
                     "Forbidden: arbitrary method calls are disabled (TDMCP_BRIDGE_ALLOW_EXEC=0)."
                 )
+            _require(body, "method")
             return api_service.call_method(
                 _node_path(rest[1:-1]),
                 body["method"],
@@ -160,7 +220,9 @@ def _route(method, path, query, body):
         if kind == "topology":
             return analysis_service.topology(node_path, recursive=_qs(query, "recursive") == "true")
         if kind == "performance":
-            return analysis_service.performance(node_path)
+            return analysis_service.performance(
+                node_path, recursive=_qs(query, "recursive") == "true"
+            )
 
     raise ValueError("Unsupported %s %s" % (method, path))
 
@@ -226,6 +288,7 @@ def _emit_event(webserver, method, path, data):
 
 def handle(request, response, webserver=None):
     try:
+        _check_origin(request)
         _check_auth(request)
         method = (request.get("method") or "GET").upper()
         parsed = urlparse(request.get("uri", "/"))
@@ -235,6 +298,6 @@ def handle(request, response, webserver=None):
         _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)}})
+        return _send(response, getattr(exc, "status", 403), {"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/services/analysis_service.py

@@ -44,13 +44,18 @@ def topology(path, recursive=False):
     return {"nodes": nodes, "connections": connections}
 
 
-def performance(path):
+def performance(path, recursive=False):
     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 []
+    if not hasattr(root, "findChildren"):
+        children = []
+    elif recursive:
+        children = root.findChildren()  # all descendants (cook time of nested nodes too)
+    else:
+        children = root.findChildren(depth=1)  # direct children only
     for child in children:
         cook_time = float(getattr(child, "cookTime", 0.0) or 0.0)
         total += cook_time

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

@@ -71,9 +71,15 @@ def create_node(parent_path, type_name, name=None, parameters=None):
         raise LookupError("Parent not found: %s" % parent_path)
     cls = _resolve_type(type_name)
     node = parent.create(cls, name) if name else parent.create(cls)
+    ref = node_ref(node)
     if parameters:
-        apply_parameters(node, parameters)
-    return node_ref(node)
+        # The node is created regardless; surface any params that did not apply
+        # (unknown name or bad value) as a non-fatal warning rather than dropping
+        # them silently. The caller (create_td_node) relays these to the user.
+        _applied, failed = apply_parameters(node, parameters)
+        if failed:
+            ref["parameter_warnings"] = sorted(failed)
+    return ref
 
 
 def delete_node(path):
@@ -120,7 +126,23 @@ def update_parameters(path, parameters):
     node = op(path)  # noqa: F821
     if node is None:
         raise LookupError("Node not found: %s" % path)
-    apply_parameters(node, parameters)
+    params = parameters or {}
+    # Reject unknown parameter names up front (atomic: apply nothing) so a typo
+    # like `gain` on a levelTOP fails loudly instead of being silently dropped.
+    unknown = [k for k in params if getattr(node.par, k, None) is None]
+    if unknown:
+        raise ValueError(
+            "Unknown parameter(s) on %s (%s): %s. "
+            "Use get_td_node_parameters to see the valid parameter names."
+            % (path, op_type(node), ", ".join(sorted(unknown)))
+        )
+    applied, failed = apply_parameters(node, params)
+    if failed:
+        raise ValueError(
+            "Could not set parameter(s) on %s (%s): %s "
+            "(wrong value type or out of range?). Applied: %s."
+            % (path, op_type(node), ", ".join(sorted(failed)), ", ".join(sorted(applied)) or "none")
+        )
     return node_detail(node)
 
 

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

@@ -11,8 +11,42 @@ def connect(source_path, target_path, source_output=0, target_input=0):
     src = op(source_path)
     dst = op(target_path)
     if src is None or dst is None:
-        raise LookupError("Source or target not found")
-    dst.inputConnectors[target_input].connect(src.outputConnectors[source_output])
+        raise LookupError("Source or target not found: %s -> %s" % (source_path, target_path))
+    src_parent = src.parent()
+    dst_parent = dst.parent()
+    # TD wires only connect operators sharing a parent. A cross-container connect
+    # silently no-ops (no exception, no wire), so reject it with an actionable msg.
+    if src_parent is None or dst_parent is None or src_parent.path != dst_parent.path:
+        raise ValueError(
+            "Cannot wire across containers: %s (in %s) -> %s (in %s). "
+            "Wires only connect operators sharing a parent; to bring an operator "
+            "across networks use a Select/In OP (e.g. a Select TOP/CHOP whose source "
+            "parameter points at %r)."
+            % (
+                src.path,
+                getattr(src_parent, "path", "<root>"),
+                dst.path,
+                getattr(dst_parent, "path", "<root>"),
+                source_path,
+            )
+        )
+    try:
+        in_conn = dst.inputConnectors[target_input]
+        out_conn = src.outputConnectors[source_output]
+    except IndexError:
+        raise IndexError(
+            "Connector index out of range: target_input=%d (%s has %d input(s)), "
+            "source_output=%d (%s has %d output(s))."
+            % (
+                target_input,
+                dst.path,
+                len(dst.inputConnectors),
+                source_output,
+                src.path,
+                len(src.outputConnectors),
+            )
+        )
+    in_conn.connect(out_conn)
 
 
 def run(operations):

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

@@ -1,4 +1,10 @@
-"""Capture a TOP as a base64-encoded PNG."""
+"""Capture a TOP as a base64-encoded PNG.
+
+The TOP is composited over a checkerboard first, so transparent regions read as a
+checker pattern instead of solid white when a viewer flattens the PNG's alpha over a
+white page. Opaque TOPs are unaffected (the checker stays fully hidden). If the
+composite path errors for any reason, we fall back to saving the TOP directly.
+"""
 
 import base64
 
@@ -6,14 +12,18 @@ import td
 
 op = td.op  # TD globals are not available inside imported modules; reach via td
 
+# Mid-gray checkerboard (16x9 cells). Self-contained fragment shader, no inputs/uniforms.
+_CHECKER_FRAG = """out vec4 fragColor;
+void main(){
+    vec2 cell = floor(vUV.st * vec2(16.0, 9.0));
+    float k = mod(cell.x + cell.y, 2.0);
+    fragColor = vec4(mix(vec3(0.16), vec3(0.30), k), 1.0);
+}
+"""
 
-def capture(path, width=640, height=360):
-    node = op(path)
-    if node is None:
-        raise LookupError("Node not found: %s" % path)
-    if getattr(node, "family", None) != "TOP":
-        raise ValueError("Preview is only supported for TOPs, got %s" % path)
 
+def _save_png(node):
+    """Return the node's PNG bytes, via saveByteArray with a temp-file fallback."""
     data = None
     try:
         data = node.saveByteArray(".png")
@@ -21,7 +31,6 @@ def capture(path, width=640, height=360):
         data = None
 
     if data is None:
-        # Fallback: save to a temp file and read it back.
         import os
         import tempfile
 
@@ -30,11 +39,80 @@ def capture(path, width=640, height=360):
         with open(tmp, "rb") as handle:
             data = handle.read()
 
-    encoded = base64.b64encode(bytes(data)).decode("ascii")
+    return bytes(data)
+
+
+def _checkerboard_png(node, width, height):
+    """Composite `node` over a checkerboard and return the flattened PNG bytes.
+
+    Creates a few temporary nodes in the node's parent and destroys them afterwards
+    (even on error). Returns None if the composite could not be produced, so callers
+    can fall back to a direct save.
+    """
+    parent = node.parent()
+    if parent is None:
+        return None
+
+    temps = []
+    try:
+        frag = parent.create("textDAT", "__tdmcp_pv_frag")
+        temps.append(frag)
+        frag.text = _CHECKER_FRAG
+
+        bg = parent.create("glslTOP", "__tdmcp_pv_bg")
+        temps.append(bg)
+        bg.par.pixeldat = frag.name
+        bg.par.outputresolution = "custom"
+        bg.par.resolutionw = width
+        bg.par.resolutionh = height
+
+        comp = parent.create("compositeTOP", "__tdmcp_pv_comp")
+        temps.append(comp)
+        comp.par.operand = "over"
+        comp.par.outputresolution = "custom"
+        comp.par.resolutionw = width
+        comp.par.resolutionh = height
+        comp.inputConnectors[0].connect(node)  # foreground (over)
+        comp.inputConnectors[1].connect(bg)  # background (under)
+        comp.cook(force=True)
+
+        if comp.errors():
+            return None
+        return _save_png(comp)
+    except Exception:  # noqa: BLE001
+        return None
+    finally:
+        for t in reversed(temps):
+            try:
+                t.destroy()
+            except Exception:  # noqa: BLE001
+                pass
+
+
+def capture(path, width=640, height=360):
+    node = op(path)
+    if node is None:
+        raise LookupError("Node not found: %s" % path)
+    if getattr(node, "family", None) != "TOP":
+        raise ValueError("Preview is only supported for TOPs, got %s" % path)
+
+    w = int(getattr(node, "width", width) or width)
+    h = int(getattr(node, "height", height) or height)
+    # Clamp to a sane preview ceiling so a hostile/huge request (or a TOP with an
+    # extreme resolution) can't allocate a multi-gigapixel GPU texture and exhaust
+    # VRAM / hang TD. A preview is a thumbnail; 4096 on a side is plenty.
+    w = max(1, min(w, 4096))
+    h = max(1, min(h, 4096))
+
+    data = _checkerboard_png(node, w, h)
+    if data is None:
+        data = _save_png(node)
+
+    encoded = base64.b64encode(data).decode("ascii")
     return {
         "path": node.path,
-        "width": int(getattr(node, "width", width) or width),
-        "height": int(getattr(node, "height", height) or height),
+        "width": w,
+        "height": h,
         "format": "png",
         "base64": encoded,
     }

package/td/modules/utils/version.py

@@ -1,3 +1,3 @@
 """Version of the tdmcp TouchDesigner bridge."""
 
-BRIDGE_VERSION = "0.2.0"
+BRIDGE_VERSION = "0.3.0"

package/td/tests/test_api_controller.py

@@ -179,6 +179,17 @@ class RoutingTests(unittest.TestCase):
         with self.assertRaises(ValueError):
             ac._route("GET", "/api/does-not-exist", {}, {})
 
+    def test_create_node_missing_fields_raises_descriptive(self):
+        with self.assertRaises(ValueError) as cm:
+            ac._route("POST", "/api/nodes", {}, {})
+        self.assertIn("parent_path", str(cm.exception))
+        self.assertIn("type", str(cm.exception))
+
+    def test_exec_missing_script_raises_descriptive(self):
+        with self.assertRaises(ValueError) as cm:
+            ac._route("POST", "/api/exec", {}, {})
+        self.assertIn("script", str(cm.exception))
+
 
 class ParsingTests(unittest.TestCase):
     def test_parse_body_variants(self):
@@ -201,6 +212,52 @@ class ParsingTests(unittest.TestCase):
         self.assertEqual(ac._find_header({"X-Token": "abc"}, "x-token"), "abc")
         self.assertIsNone(ac._find_header({"other": "v"}, "x-token"))
 
+    def test_find_header_accepts_list_value(self):
+        # A repeated/multi-value header may arrive as a list; take the first str.
+        self.assertEqual(ac._find_header({"Origin": ["http://x", "http://y"]}, "origin"), "http://x")
+        self.assertIsNone(ac._find_header({"Origin": []}, "origin"))
+        self.assertIsNone(ac._find_header({"Origin": [123]}, "origin"))
+
+
+class OriginTests(unittest.TestCase):
+    """The Origin guard blocks browser-driven CSRF / DNS-rebinding."""
+
+    def test_no_origin_is_allowed(self):
+        ac._check_origin({"method": "GET"})  # the Node client sends no Origin
+
+    def test_loopback_origins_allowed(self):
+        for origin in (
+            "http://127.0.0.1:9980",
+            "http://localhost",
+            "https://localhost:3000",
+            "http://[::1]:9980",
+        ):
+            ac._check_origin({"Origin": origin})  # must not raise
+
+    def test_cross_origin_rejected(self):
+        for origin in ("http://evil.com", "https://attacker.example:8443", "http://192.168.1.5"):
+            with self.assertRaises(PermissionError, msg=origin):
+                ac._check_origin({"Origin": origin})
+
+    def test_opaque_null_origin_rejected(self):
+        with self.assertRaises(PermissionError):
+            ac._check_origin({"Origin": "null"})
+
+    def test_origin_lookup_is_case_insensitive_and_nested(self):
+        with self.assertRaises(PermissionError):
+            ac._check_origin({"headers": {"origin": "http://evil.com"}})
+
+    def test_handle_rejects_cross_origin_with_403(self):
+        resp = ac.handle({"method": "GET", "uri": "/api/info", "Origin": "http://evil.com"}, {})
+        self.assertEqual(resp["statusCode"], 403)
+        self.assertIn("cross-origin", resp["data"])
+
+    def test_handle_rejects_list_valued_cross_origin(self):
+        # Some TD builds surface a header as a list; it must not slip the guard.
+        resp = ac.handle({"method": "GET", "uri": "/api/info", "Origin": ["http://evil.com"]}, {})
+        self.assertEqual(resp["statusCode"], 403)
+        self.assertIn("cross-origin", resp["data"])
+
 
 class HandleTests(unittest.TestCase):
     def tearDown(self):
@@ -229,14 +286,22 @@ class HandleTests(unittest.TestCase):
         self.assertEqual(resp["statusCode"], 400)
         self.assertIn("boom", resp["data"])
 
-    def test_exec_disabled_surfaces_as_401_with_message(self):
+    def test_exec_disabled_surfaces_as_403_with_message(self):
         os.environ["TDMCP_BRIDGE_ALLOW_EXEC"] = "0"
         resp = ac.handle(
             {"method": "POST", "uri": "/api/exec", "data": '{"script": "1"}'}, self._resp()
         )
-        self.assertEqual(resp["statusCode"], 401)
+        self.assertEqual(resp["statusCode"], 403)
         self.assertIn("disabled", resp["data"])
 
+    def test_missing_required_field_surfaces_as_400_with_name(self):
+        # A POST with valid JSON but a missing field gets a descriptive 400,
+        # not a bare KeyError message of just the key name.
+        resp = ac.handle({"method": "POST", "uri": "/api/nodes", "data": "{}"}, self._resp())
+        self.assertEqual(resp["statusCode"], 400)
+        self.assertIn("parent_path", resp["data"])
+        self.assertIn("Missing required field", resp["data"])
+
 
 if __name__ == "__main__":
     unittest.main()