@dpantani/tdmcp 0.2.0 → 0.3.0

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@dpantani/tdmcp",
-  "version": "0.2.0",
-  "description": "AI-native visual creation for TouchDesigner — a production-grade MCP server.",
+  "mcpName": "io.github.Pantani/tdmcp",
+  "version": "0.3.0",
+  "description": "tdmcp — the TouchDesigner MCP server. Build real TouchDesigner visual systems from plain language with Claude, Cursor, or Codex (Model Context Protocol).",
   "type": "module",
   "license": "MIT",
+  "homepage": "https://pantani.github.io/tdmcp/",
   "engines": {
     "node": ">=20"
   },
@@ -41,6 +43,10 @@
     "validate:recipes": "tsx scripts/validate-recipes.ts",
     "smoke:live": "tsx scripts/smoke-live.ts",
     "build:dxt": "node scripts/build-dxt.mjs",
+    "docs:gen": "tsx scripts/gen-tool-docs.ts",
+    "docs:dev": "npm run docs:gen && vitepress dev docs",
+    "docs:build": "npm run docs:gen && vitepress build docs",
+    "docs:preview": "vitepress preview docs",
     "version": "node scripts/sync-manifest-version.mjs && git add dxt/manifest.json",
     "prepack": "node scripts/clean-pycache.mjs",
     "prepublishOnly": "npm run build && npm test"
@@ -50,14 +56,25 @@
   },
   "keywords": [
     "touchdesigner",
+    "touchdesigner-mcp",
     "mcp",
+    "mcp-server",
     "model-context-protocol",
+    "claude",
+    "cursor",
+    "codex",
+    "ai",
     "visual",
     "creative-coding",
-    "generative-art"
+    "generative-art",
+    "vj",
+    "glsl",
+    "audio-reactive",
+    "derivative"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "gray-matter": "^4.0.3",
     "zod": "^4.4.3"
   },
   "devDependencies": {
@@ -69,6 +86,7 @@
     "tsup": "^8.5.1",
     "tsx": "^4.22.3",
     "typescript": "^6.0.3",
+    "vitepress": "^1.6.4",
     "vitest": "^4.1.7"
   }
 }

package/td/README.md

@@ -102,7 +102,7 @@ Verify from a terminal:
 
 ```bash
 curl http://127.0.0.1:9980/api/info
-# {"ok":true,"data":{"python_version":"3.11.x","td_version":"...","bridge_version":"0.1.0"}}
+# {"ok":true,"data":{"python_version":"3.11.x","td_version":"...","bridge_version":"0.3.0"}}
 ```
 
 Then run the live smoke test from the repo root:

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,7 @@ 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")
@@ -96,7 +114,7 @@ def _check_origin(request):
         return
     host = urlparse(origin).hostname
     if host not in _LOOPBACK_HOSTS:
-        raise PermissionError("Forbidden: cross-origin request rejected (origin %r)." % origin)
+        raise _Forbidden("Forbidden: cross-origin request rejected (origin %r)." % origin)
 
 
 def _qs(query, key, default=None):
@@ -126,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":
@@ -136,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")
         )
@@ -144,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":
@@ -153,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"],
@@ -263,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/preview_service.py

@@ -98,6 +98,11 @@ def capture(path, width=640, height=360):
 
     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:

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,12 @@ 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."""
@@ -230,9 +247,15 @@ class OriginTests(unittest.TestCase):
         with self.assertRaises(PermissionError):
             ac._check_origin({"headers": {"origin": "http://evil.com"}})
 
-    def test_handle_rejects_cross_origin_with_401(self):
+    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"], 401)
+        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"])
 
 
@@ -263,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()