@dpantani/tdmcp 0.1.0

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

@@ -0,0 +1,195 @@
+"""Core node CRUD, Python execution, method calls and server info.
+
+All functions assume the TouchDesigner globals (`op`, `app`, `project`) are
+available, which is the case when this package is imported from a running TD.
+"""
+
+import io
+import re
+import sys
+import traceback
+from contextlib import redirect_stdout
+
+import td
+
+# TouchDesigner injects globals (op, app, project, operator classes) only into
+# DAT/Textport scope, not into imported modules — so reach them via `td`.
+op = td.op
+app = td.app
+project = td.project
+
+_TYPE_RE = re.compile(r"[A-Za-z][A-Za-z0-9_]*$")
+
+
+def op_type(node):
+    """Returns the operator type string, e.g. 'noiseTOP'."""
+    return getattr(node, "OPType", None) or getattr(node, "type", "") or ""
+
+
+def _resolve_type(type_name):
+    """Resolves an operator type string to its class via the td module."""
+    if not type_name or not _TYPE_RE.match(type_name):
+        raise ValueError("Invalid operator type: %r" % (type_name,))
+    cls = getattr(td, type_name, None)
+    if cls is None:
+        raise ValueError("Unknown operator type: %s" % type_name)
+    return cls
+
+
+def node_ref(node):
+    return {"path": node.path, "type": op_type(node), "name": node.name}
+
+
+def _jsonable(value):
+    try:
+        import json
+
+        json.dumps(value)
+        return value
+    except Exception:  # noqa: BLE001
+        return str(value)
+
+
+def apply_parameters(node, parameters):
+    applied, failed = [], []
+    for key, value in (parameters or {}).items():
+        try:
+            par = getattr(node.par, key, None)
+            if par is None:
+                failed.append(key)
+                continue
+            par.val = value
+            applied.append(key)
+        except Exception:  # noqa: BLE001
+            failed.append(key)
+    return applied, failed
+
+
+def create_node(parent_path, type_name, name=None, parameters=None):
+    parent = op(parent_path)  # noqa: F821 - TD global
+    if parent is 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)
+    if parameters:
+        apply_parameters(node, parameters)
+    return node_ref(node)
+
+
+def delete_node(path):
+    node = op(path)  # noqa: F821
+    if node is None:
+        raise LookupError("Node not found: %s" % path)
+    node.destroy()
+    return {"deleted": path}
+
+
+def get_nodes(parent_path=None):
+    parent = op(parent_path or "/")  # noqa: F821
+    if parent is None:
+        raise LookupError("Parent not found: %s" % parent_path)
+    children = parent.findChildren(depth=1) if hasattr(parent, "findChildren") else []
+    return {"nodes": [node_ref(c) for c in children]}
+
+
+def node_detail(node):
+    pars = {}
+    try:
+        for par in node.pars():
+            try:
+                pars[par.name] = _jsonable(par.eval())
+            except Exception:  # noqa: BLE001
+                pars[par.name] = None
+    except Exception:  # noqa: BLE001
+        pars = {}
+    inputs = [c.path for c in getattr(node, "inputs", []) if c]
+    outputs = [c.path for c in getattr(node, "outputs", []) if c]
+    detail = node_ref(node)
+    detail.update({"parameters": pars, "inputs": inputs, "outputs": outputs})
+    return detail
+
+
+def get_node(path):
+    node = op(path)  # noqa: F821
+    if node is None:
+        raise LookupError("Node not found: %s" % path)
+    return node_detail(node)
+
+
+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)
+    return node_detail(node)
+
+
+def exec_script(script, return_output=True):
+    buf = io.StringIO()
+    # Seed the exec namespace with the full TD namespace (op, ParMode, operator
+    # classes, …) so scripts behave like they would in a DAT/Textport.
+    namespace = dict(vars(td))
+    namespace["op"] = op
+    try:
+        with redirect_stdout(buf):
+            exec(script, namespace)  # noqa: S102 - intentional, runs inside TD
+    except Exception:  # noqa: BLE001
+        raise RuntimeError(traceback.format_exc())
+    result = {"stdout": buf.getvalue() if return_output else ""}
+    if namespace.get("result") is not None:
+        result["result"] = _jsonable(namespace["result"])
+    return result
+
+
+def call_method(path, method, args=None, kwargs=None):
+    node = op(path)  # noqa: F821
+    if node is None:
+        raise LookupError("Node not found: %s" % path)
+    fn = getattr(node, method, None)
+    if not callable(fn):
+        raise AttributeError("%s has no callable method %s" % (path, method))
+    value = fn(*(args or []), **(kwargs or {}))
+    return {"result": _jsonable(value)}
+
+
+def get_node_errors(path, recursive=False):
+    node = op(path)  # noqa: F821
+    if node is None:
+        return {"errors": []}
+    targets = [node]
+    if recursive and hasattr(node, "findChildren"):
+        targets += node.findChildren()
+    out = []
+    for target in targets:
+        for kind in ("errors", "warnings"):
+            try:
+                fn = getattr(target, kind)
+                text = fn(recurse=False) if callable(fn) else fn
+            except Exception:  # noqa: BLE001
+                text = ""
+            if text:
+                out.append({"path": target.path, "message": text, "type": kind[:-1]})
+    return {"errors": out}
+
+
+def get_info():
+    info = {"python_version": sys.version.split()[0]}
+    try:
+        info["td_version"] = app.version  # noqa: F821
+    except Exception:  # noqa: BLE001
+        pass
+    try:
+        info["build"] = app.build  # noqa: F821
+    except Exception:  # noqa: BLE001
+        pass
+    try:
+        info["project"] = project.name  # noqa: F821
+    except Exception:  # noqa: BLE001
+        pass
+    try:
+        from utils.version import BRIDGE_VERSION
+
+        info["bridge_version"] = BRIDGE_VERSION
+    except Exception:  # noqa: BLE001
+        info["bridge_version"] = "unknown"
+    return info

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

@@ -0,0 +1,49 @@
+"""Atomic-ish batch operations: create / update / delete / connect."""
+
+import td
+
+from mcp.services import api_service
+
+op = td.op  # TD globals are not available inside imported modules; reach via td
+
+
+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])
+
+
+def run(operations):
+    results = []
+    for operation in operations or []:
+        action = operation.get("action")
+        try:
+            if action == "create":
+                ref = api_service.create_node(
+                    operation["parent_path"],
+                    operation["type"],
+                    operation.get("name"),
+                    operation.get("parameters"),
+                )
+                results.append({"action": action, "ok": True, "data": ref})
+            elif action == "update":
+                api_service.update_parameters(operation["path"], operation.get("parameters", {}))
+                results.append({"action": action, "ok": True, "path": operation["path"]})
+            elif action == "delete":
+                api_service.delete_node(operation["path"])
+                results.append({"action": action, "ok": True, "path": operation["path"]})
+            elif action == "connect":
+                connect(
+                    operation["source_path"],
+                    operation["target_path"],
+                    operation.get("source_output", 0),
+                    operation.get("target_input", 0),
+                )
+                results.append({"action": action, "ok": True})
+            else:
+                results.append({"action": action, "ok": False, "error": "unknown action"})
+        except Exception as exc:  # noqa: BLE001
+            results.append({"action": action, "ok": False, "error": str(exc)})
+    return {"results": results}

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

@@ -0,0 +1,40 @@
+"""Capture a TOP as a base64-encoded PNG."""
+
+import base64
+
+import td
+
+op = td.op  # TD globals are not available inside imported modules; reach via td
+
+
+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)
+
+    data = None
+    try:
+        data = node.saveByteArray(".png")
+    except Exception:  # noqa: BLE001
+        data = None
+
+    if data is None:
+        # Fallback: save to a temp file and read it back.
+        import os
+        import tempfile
+
+        tmp = os.path.join(tempfile.gettempdir(), "tdmcp_preview.png")
+        node.save(tmp)
+        with open(tmp, "rb") as handle:
+            data = handle.read()
+
+    encoded = base64.b64encode(bytes(data)).decode("ascii")
+    return {
+        "path": node.path,
+        "width": int(getattr(node, "width", width) or width),
+        "height": int(getattr(node, "height", height) or height),
+        "format": "png",
+        "base64": encoded,
+    }

package/td/modules/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility helpers for the tdmcp bridge."""

package/td/modules/utils/version.py

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

package/td/startup.py

@@ -0,0 +1,34 @@
+# tdmcp bridge auto-start (Execute DAT).
+#
+# Easiest path (no DAT at all): once td/modules is on the Preferences module
+# path, just paste this into the Textport once:
+#
+#     from mcp import install; install.run()
+#
+# This file is the "run automatically on every project open" version: paste it
+# into an Execute DAT and turn ON its "Start" and "Create" toggles. Put that
+# Execute DAT in your Default Project template to make it global for new projects.
+#
+# If you did NOT add td/modules to the Preferences module path, set MODULES_DIR
+# to its absolute path below.
+
+MODULES_DIR = ""
+
+
+def _install():
+    if MODULES_DIR:
+        import sys
+
+        if MODULES_DIR not in sys.path:
+            sys.path.insert(0, MODULES_DIR)
+    from mcp import install
+
+    install.run(modules_dir=MODULES_DIR or None)
+
+
+def onStart():
+    _install()
+
+
+def onCreate():
+    _install()

package/td/templates/webserver_callbacks.py

@@ -0,0 +1,50 @@
+# WebServer DAT callbacks for the tdmcp bridge.
+#
+# Setup:
+#   1. Copy the `td/modules` folder into your TD project, e.g. <project>/tdmcp/modules.
+#   2. Add a Web Server DAT, set its port to 9980 (matches TDMCP_TD_PORT).
+#   3. Point the Web Server DAT's callbacks at this file (or paste its contents).
+#
+# The path below assumes <project>/tdmcp/modules — adjust _MODULES if you put it
+# somewhere else.
+
+import os
+import sys
+
+_MODULES = os.path.join(project.folder, "tdmcp", "modules")  # noqa: F821 - TD global
+if _MODULES not in sys.path:
+    sys.path.insert(0, _MODULES)
+
+from mcp.controllers import api_controller  # noqa: E402
+
+
+def onHTTPRequest(webServerDAT, request, response):
+    return api_controller.handle(request, response, webServerDAT)
+
+
+def onWebSocketOpen(webServerDAT, client, uri):
+    return
+
+
+def onWebSocketReceiveText(webServerDAT, client, data):
+    return
+
+
+def onWebSocketReceiveBinary(webServerDAT, client, data):
+    return
+
+
+def onWebSocketReceivePing(webServerDAT, client, data):
+    webServerDAT.webSocketSendPong(client, data=data)
+
+
+def onWebSocketReceivePong(webServerDAT, client, data):
+    return
+
+
+def onServerStart(webServerDAT):
+    return
+
+
+def onServerStop(webServerDAT):
+    return

package/td/tests/test_api_controller.py

@@ -0,0 +1,242 @@
+"""Unit tests for the tdmcp bridge HTTP router.
+
+The bridge normally runs inside TouchDesigner, where `td`, `op`, `app` and the
+operator classes are injected globals. To exercise the router's pure logic —
+auth, the arbitrary-code gate, request parsing, path decoding and route
+dispatch — off-TD, we install a stub `td` module before importing the package
+and replace the service layer with recorders for dispatch assertions.
+
+Run from the repo root: `python3 -m unittest discover -s td/tests`
+(or `npm run test:bridge`). No third-party dependencies — stdlib only.
+"""
+
+import os
+import sys
+import types
+import unittest
+from unittest import mock
+
+# --- Make the bridge importable without TouchDesigner --------------------------
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_MODULES = os.path.abspath(os.path.join(_HERE, "..", "modules"))
+if _MODULES not in sys.path:
+    sys.path.insert(0, _MODULES)
+
+# `mcp.services.*` bind `op/app/project` from `td` at import time; a stub suffices.
+_td_stub = types.ModuleType("td")
+_td_stub.op = mock.MagicMock(name="op")
+_td_stub.app = mock.MagicMock(name="app")
+_td_stub.project = mock.MagicMock(name="project")
+sys.modules.setdefault("td", _td_stub)
+
+from mcp.controllers import api_controller as ac  # noqa: E402
+
+
+def _clear_exec_env():
+    os.environ.pop("TDMCP_BRIDGE_ALLOW_EXEC", None)
+
+
+def _clear_token_env():
+    os.environ.pop("TDMCP_BRIDGE_TOKEN", None)
+
+
+class AuthTests(unittest.TestCase):
+    def tearDown(self):
+        _clear_token_env()
+
+    def test_no_token_means_auth_off(self):
+        _clear_token_env()
+        # Should not raise even with no Authorization header.
+        ac._check_auth({"method": "GET"})
+
+    def test_valid_bearer_token_passes(self):
+        os.environ["TDMCP_BRIDGE_TOKEN"] = "s3cret"
+        ac._check_auth({"Authorization": "Bearer s3cret"})
+
+    def test_invalid_token_raises(self):
+        os.environ["TDMCP_BRIDGE_TOKEN"] = "s3cret"
+        with self.assertRaises(PermissionError):
+            ac._check_auth({"Authorization": "Bearer wrong"})
+
+    def test_missing_header_raises_when_token_required(self):
+        os.environ["TDMCP_BRIDGE_TOKEN"] = "s3cret"
+        with self.assertRaises(PermissionError):
+            ac._check_auth({"method": "GET"})
+
+    def test_header_lookup_is_case_insensitive_and_nested(self):
+        os.environ["TDMCP_BRIDGE_TOKEN"] = "s3cret"
+        # Header nested under a 'headers' dict with odd casing — must still match.
+        ac._check_auth({"headers": {"authorization": "Bearer s3cret"}})
+
+
+class ExecGateTests(unittest.TestCase):
+    def tearDown(self):
+        _clear_exec_env()
+        _clear_token_env()
+
+    def test_allowed_by_default(self):
+        _clear_exec_env()
+        self.assertTrue(ac._exec_allowed())
+
+    def test_disabled_values(self):
+        for value in ("0", "false", "FALSE", "no", "off", " Off "):
+            os.environ["TDMCP_BRIDGE_ALLOW_EXEC"] = value
+            self.assertFalse(ac._exec_allowed(), value)
+
+    def test_enabled_values(self):
+        for value in ("1", "true", "yes", "on", "", "anything"):
+            os.environ["TDMCP_BRIDGE_ALLOW_EXEC"] = value
+            self.assertTrue(ac._exec_allowed(), value)
+
+    def test_route_blocks_exec_when_disabled(self):
+        os.environ["TDMCP_BRIDGE_ALLOW_EXEC"] = "0"
+        with self.assertRaises(PermissionError):
+            ac._route("POST", "/api/exec", {}, {"script": "print(1)"})
+
+    def test_route_blocks_node_method_when_disabled(self):
+        os.environ["TDMCP_BRIDGE_ALLOW_EXEC"] = "0"
+        with self.assertRaises(PermissionError):
+            ac._route("POST", "/api/nodes/project1/geo1/method", {}, {"method": "cook"})
+
+
+class RoutingTests(unittest.TestCase):
+    """Dispatch logic, with the service layer swapped for recorders."""
+
+    def setUp(self):
+        _clear_exec_env()
+        self._saved = {
+            "api": ac.api_service,
+            "batch": ac.batch_service,
+            "analysis": ac.analysis_service,
+            "preview": ac.preview_service,
+        }
+        ac.api_service = mock.MagicMock(name="api_service")
+        ac.batch_service = mock.MagicMock(name="batch_service")
+        ac.analysis_service = mock.MagicMock(name="analysis_service")
+        ac.preview_service = mock.MagicMock(name="preview_service")
+
+    def tearDown(self):
+        ac.api_service = self._saved["api"]
+        ac.batch_service = self._saved["batch"]
+        ac.analysis_service = self._saved["analysis"]
+        ac.preview_service = self._saved["preview"]
+
+    def test_get_info(self):
+        ac._route("GET", "/api/info", {}, {})
+        ac.api_service.get_info.assert_called_once_with()
+
+    def test_create_node(self):
+        ac._route("POST", "/api/nodes", {}, {"parent_path": "/project1", "type": "noiseTOP"})
+        ac.api_service.create_node.assert_called_once()
+        self.assertEqual(ac.api_service.create_node.call_args.args[0], "/project1")
+        self.assertEqual(ac.api_service.create_node.call_args.args[1], "noiseTOP")
+
+    def test_list_nodes_uses_parent_query(self):
+        ac._route("GET", "/api/nodes", {"parent": ["/project1"]}, {})
+        ac.api_service.get_nodes.assert_called_once_with("/project1")
+
+    def test_exec_dispatch_when_allowed(self):
+        ac._route("POST", "/api/exec", {}, {"script": "x=1", "return_output": False})
+        ac.api_service.exec_script.assert_called_once_with("x=1", False)
+
+    def test_batch_dispatch(self):
+        ops = [{"action": "create", "parent_path": "/p", "type": "noiseTOP"}]
+        ac._route("POST", "/api/batch", {}, {"operations": ops})
+        ac.batch_service.run.assert_called_once_with(ops)
+
+    def test_node_get_patch_delete(self):
+        ac._route("GET", "/api/nodes/project1/noise1", {}, {})
+        ac.api_service.get_node.assert_called_once_with("/project1/noise1")
+
+        ac._route("PATCH", "/api/nodes/project1/noise1", {}, {"parameters": {"period": 4}})
+        ac.api_service.update_parameters.assert_called_once_with("/project1/noise1", {"period": 4})
+
+        ac._route("DELETE", "/api/nodes/project1/noise1", {}, {})
+        ac.api_service.delete_node.assert_called_once_with("/project1/noise1")
+
+    def test_node_method_dispatch(self):
+        ac._route(
+            "POST",
+            "/api/nodes/project1/geo1/method",
+            {},
+            {"method": "cook", "args": [1], "kwargs": {"force": True}},
+        )
+        ac.api_service.call_method.assert_called_once_with("/project1/geo1", "cook", [1], {"force": True})
+
+    def test_node_errors_dispatch(self):
+        ac._route("GET", "/api/nodes/project1/geo1/errors", {}, {})
+        ac.api_service.get_node_errors.assert_called_once_with("/project1/geo1", recursive=False)
+
+    def test_preview_dispatch_with_dimensions(self):
+        ac._route("GET", "/api/preview/project1/out1", {"width": ["800"], "height": ["600"]}, {})
+        ac.preview_service.capture.assert_called_once_with("/project1/out1", 800, 600)
+
+    def test_network_topology_dispatch(self):
+        ac._route("GET", "/api/network/project1/topology", {"recursive": ["true"]}, {})
+        ac.analysis_service.topology.assert_called_once_with("/project1", recursive=True)
+
+    def test_unknown_route_raises(self):
+        with self.assertRaises(ValueError):
+            ac._route("GET", "/api/does-not-exist", {}, {})
+
+
+class ParsingTests(unittest.TestCase):
+    def test_parse_body_variants(self):
+        self.assertEqual(ac._parse_body({"data": ""}), {})
+        self.assertEqual(ac._parse_body({"data": None}), {})
+        self.assertEqual(ac._parse_body({"data": '{"a": 1}'}), {"a": 1})
+        self.assertEqual(ac._parse_body({"data": b'{"b": 2}'}), {"b": 2})
+        self.assertEqual(ac._parse_body({"data": {"c": 3}}), {"c": 3})
+
+    def test_node_path_rejoins_and_restores_leading_slash(self):
+        self.assertEqual(ac._node_path(["project1", "noise1"]), "/project1/noise1")
+        # Percent-encoded segment decodes back to a slash-bearing path.
+        self.assertEqual(ac._node_path(["project1%2Fgeo1"]), "/project1/geo1")
+
+    def test_qs_returns_first_or_default(self):
+        self.assertEqual(ac._qs({"k": ["v1", "v2"]}, "k"), "v1")
+        self.assertEqual(ac._qs({}, "missing", "fallback"), "fallback")
+
+    def test_find_header_top_level_and_default(self):
+        self.assertEqual(ac._find_header({"X-Token": "abc"}, "x-token"), "abc")
+        self.assertIsNone(ac._find_header({"other": "v"}, "x-token"))
+
+
+class HandleTests(unittest.TestCase):
+    def tearDown(self):
+        _clear_exec_env()
+        _clear_token_env()
+
+    def _resp(self):
+        return {}
+
+    def test_ok_envelope(self):
+        with mock.patch.object(ac, "_route", return_value={"hello": "world"}):
+            resp = ac.handle({"method": "GET", "uri": "/api/info"}, self._resp())
+        self.assertEqual(resp["statusCode"], 200)
+        self.assertIn('"ok": true', resp["data"])
+        self.assertIn("world", resp["data"])
+
+    def test_auth_failure_is_401(self):
+        os.environ["TDMCP_BRIDGE_TOKEN"] = "s3cret"
+        resp = ac.handle({"method": "GET", "uri": "/api/info"}, self._resp())
+        self.assertEqual(resp["statusCode"], 401)
+        self.assertIn('"ok": false', resp["data"])
+
+    def test_error_is_400(self):
+        with mock.patch.object(ac, "_route", side_effect=ValueError("boom")):
+            resp = ac.handle({"method": "GET", "uri": "/api/info"}, self._resp())
+        self.assertEqual(resp["statusCode"], 400)
+        self.assertIn("boom", resp["data"])
+
+    def test_exec_disabled_surfaces_as_401_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.assertIn("disabled", resp["data"])
+
+
+if __name__ == "__main__":
+    unittest.main()