@dpantani/tdmcp 0.1.0

package/recipes/noise_landscape.json

@@ -0,0 +1,76 @@
+{
+  "id": "noise_landscape",
+  "name": "Noise Landscape",
+  "description": "A 3D terrain displaced by noise, shaded with a Phong material and rendered with an orbiting camera.",
+  "tags": ["generative", "3d", "geometry", "noise", "landscape"],
+  "difficulty": "intermediate",
+  "td_version_min": "2022",
+  "nodes": [
+    {
+      "name": "geo1",
+      "type": "geometryCOMP",
+      "comment": "Renders the displaced terrain SOP nested inside it (not its default torus)"
+    },
+    {
+      "name": "grid1",
+      "type": "gridSOP",
+      "parent": "geo1",
+      "parameters": { "rows": 120, "cols": 120, "sizex": 4, "sizey": 4, "orient": "zx" },
+      "comment": "Base mesh (horizontal plane), nested inside geo1"
+    },
+    {
+      "name": "noise1",
+      "type": "noiseSOP",
+      "parent": "geo1",
+      "render": true,
+      "parameters": { "amp": 0.8, "period": 2 },
+      "comment": "Displaces the grid into hills/valleys; this is the rendered geometry"
+    },
+    { "name": "phong1", "type": "phongMAT", "comment": "Surface shading" },
+    { "name": "cam1", "type": "cameraCOMP", "parameters": { "tz": 7, "ty": 5, "rx": -33 } },
+    { "name": "light1", "type": "lightCOMP", "parameters": { "tx": 4, "ty": 6, "tz": 4 } },
+    { "name": "render1", "type": "renderTOP", "comment": "Final rendered image" },
+    { "name": "out1", "type": "nullTOP" }
+  ],
+  "connections": [{ "from": "grid1", "to": "noise1" }, { "from": "render1", "to": "out1" }],
+  "parameters": [
+    {
+      "name": "geometry",
+      "node": "render1",
+      "param": "geometry",
+      "value": "geo1",
+      "description": "Geometry COMP to render."
+    },
+    {
+      "name": "camera",
+      "node": "render1",
+      "param": "camera",
+      "value": "cam1",
+      "description": "Camera COMP."
+    },
+    {
+      "name": "lights",
+      "node": "render1",
+      "param": "lights",
+      "value": "light1",
+      "description": "Light COMP(s)."
+    },
+    {
+      "name": "material",
+      "node": "geo1",
+      "param": "material",
+      "value": "phong1",
+      "description": "Material applied to the geometry."
+    },
+    {
+      "name": "terrain_height",
+      "node": "noise1",
+      "param": "amp",
+      "value": 0.8,
+      "min": 0,
+      "max": 2,
+      "label": "Terrain Height"
+    }
+  ],
+  "preview_description": "A softly lit rolling 3D terrain of noise-driven hills viewed from a slightly elevated angle."
+}

package/recipes/particle_galaxy.json

@@ -0,0 +1,52 @@
+{
+  "id": "particle_galaxy",
+  "name": "Particle Galaxy",
+  "description": "A swirling galaxy of particles emitted from a sphere, pushed by turbulence and gravity, rendered as glowing sprites.",
+  "tags": ["particle", "3d", "galaxy", "generative"],
+  "difficulty": "advanced",
+  "td_version_min": "2022",
+  "nodes": [
+    {
+      "name": "geo",
+      "type": "geometryCOMP",
+      "comment": "Renders the particle SOP nested inside it (not its default torus)"
+    },
+    {
+      "name": "sphere",
+      "type": "sphereSOP",
+      "parent": "geo",
+      "parameters": { "radx": 1, "rady": 1, "radz": 1 },
+      "comment": "Emitter surface, nested inside geo"
+    },
+    {
+      "name": "particle",
+      "type": "particleSOP",
+      "parent": "geo",
+      "render": true,
+      "parameters": { "life": 4 },
+      "comment": "Particle simulation fed by the sphere; this is the rendered geometry"
+    },
+    { "name": "mat", "type": "pointspriteMAT", "comment": "Glowing sprite material" },
+    { "name": "cam", "type": "cameraCOMP", "parameters": { "tz": 6 } },
+    { "name": "light", "type": "lightCOMP", "parameters": { "tx": 3, "ty": 4, "tz": 4 } },
+    { "name": "render", "type": "renderTOP", "comment": "Rendered galaxy" },
+    { "name": "out1", "type": "nullTOP" }
+  ],
+  "connections": [{ "from": "sphere", "to": "particle" }, { "from": "render", "to": "out1" }],
+  "parameters": [
+    { "name": "geometry", "node": "render", "param": "geometry", "value": "geo" },
+    { "name": "camera", "node": "render", "param": "camera", "value": "cam" },
+    { "name": "lights", "node": "render", "param": "lights", "value": "light" },
+    { "name": "material", "node": "geo", "param": "material", "value": "mat" },
+    {
+      "name": "lifetime",
+      "node": "particle",
+      "param": "life",
+      "value": 4,
+      "min": 1,
+      "max": 20,
+      "label": "Particle Lifetime"
+    }
+  ],
+  "preview_description": "A slowly rotating spiral of bright point-sprites drifting outward from a glowing core."
+}

package/recipes/projection_mapping.json

@@ -0,0 +1,25 @@
+{
+  "id": "projection_mapping",
+  "name": "Projection Mapping",
+  "description": "Takes a source visual through corner-pin keystone correction and edge feathering, ready to send to a projector window.",
+  "tags": ["projection", "mapping", "output", "installation"],
+  "difficulty": "advanced",
+  "td_version_min": "2022",
+  "nodes": [
+    { "name": "source", "type": "nullTOP", "comment": "Wire your visual into this node" },
+    { "name": "cornerpin", "type": "cornerpinTOP", "comment": "Keystone / corner-pin warp" },
+    {
+      "name": "feather",
+      "type": "levelTOP",
+      "comment": "Edge-blend brightness ramp (placeholder for edge blending)"
+    },
+    { "name": "out1", "type": "nullTOP", "comment": "Send to a Window COMP for the projector" }
+  ],
+  "connections": [
+    { "from": "source", "to": "cornerpin" },
+    { "from": "cornerpin", "to": "feather" },
+    { "from": "feather", "to": "out1" }
+  ],
+  "parameters": [],
+  "preview_description": "A warped, edge-feathered version of the source ready to align onto a physical surface."
+}

package/recipes/reaction_diffusion.json

@@ -0,0 +1,90 @@
+{
+  "id": "reaction_diffusion",
+  "name": "Reaction Diffusion",
+  "description": "A Gray-Scott reaction-diffusion simulation running entirely on the GPU in a GLSL TOP, with the previous state fed back each frame.",
+  "tags": ["generative", "glsl", "simulation", "reaction-diffusion", "organic"],
+  "difficulty": "advanced",
+  "td_version_min": "2022",
+  "nodes": [
+    {
+      "name": "seed1",
+      "type": "glslTOP",
+      "comment": "Generates the Gray-Scott initial state: A=1 everywhere with sparse organic blobs of B"
+    },
+    {
+      "name": "feedback1",
+      "type": "feedbackTOP",
+      "comment": "Holds the previous simulation state"
+    },
+    {
+      "name": "glsl1",
+      "type": "glslTOP",
+      "comment": "Gray-Scott update step (reads feedback as input 0)"
+    },
+    { "name": "out1", "type": "nullTOP", "comment": "Output of the simulation" }
+  ],
+  "connections": [
+    { "from": "seed1", "to": "feedback1", "to_input": 0 },
+    { "from": "feedback1", "to": "glsl1", "to_input": 0 },
+    { "from": "glsl1", "to": "out1" }
+  ],
+  "parameters": [
+    {
+      "name": "feedback_target",
+      "node": "feedback1",
+      "param": "top",
+      "value": "glsl1",
+      "description": "feedbackTOP samples glsl1 (the simulation output)."
+    },
+    {
+      "name": "seed_resmode",
+      "node": "seed1",
+      "param": "outputresolution",
+      "value": "custom",
+      "description": "The seed GLSL TOP has no input, so it needs an explicit resolution; it propagates through the feedback loop to size the whole simulation."
+    },
+    { "name": "seed_resmult", "node": "seed1", "param": "resmult", "value": 0 },
+    {
+      "name": "seed_resw",
+      "node": "seed1",
+      "param": "resolutionw",
+      "value": 256,
+      "label": "Resolution",
+      "description": "Simulation grid width."
+    },
+    {
+      "name": "seed_resh",
+      "node": "seed1",
+      "param": "resolutionh",
+      "value": 256,
+      "description": "Simulation grid height."
+    }
+  ],
+  "glsl_uniforms": [
+    {
+      "node": "glsl1",
+      "name": "uFeed",
+      "kind": "float",
+      "value": 0.055,
+      "label": "Feed Rate",
+      "min": 0.0,
+      "max": 0.1,
+      "description": "Gray-Scott feed rate — how fast chemical A is replenished. Lower values give sparser patterns."
+    },
+    {
+      "node": "glsl1",
+      "name": "uKill",
+      "kind": "float",
+      "value": 0.062,
+      "label": "Kill Rate",
+      "min": 0.0,
+      "max": 0.1,
+      "description": "Gray-Scott kill rate — how fast chemical B is removed. Tune alongside Feed Rate to shift between spots, stripes and mazes."
+    }
+  ],
+  "glsl_code": {
+    "seed1": "out vec4 fragColor;\nfloat hash(vec2 p){ return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453); }\nfloat vnoise(vec2 p){\n    vec2 i = floor(p); vec2 f = fract(p);\n    f = f*f*(3.0-2.0*f);\n    float a = hash(i);\n    float b = hash(i+vec2(1.0,0.0));\n    float c = hash(i+vec2(0.0,1.0));\n    float d = hash(i+vec2(1.0,1.0));\n    return mix(mix(a,b,f.x), mix(c,d,f.x), f.y);\n}\nvoid main(){\n    vec2 uv = vUV.st;\n    float n = vnoise(uv * 14.0);\n    float b = smoothstep(0.62, 0.70, n);\n    fragColor = TDOutputSwizzle(vec4(1.0, b, 0.0, 1.0));\n}\n",
+    "glsl1": "out vec4 fragColor;\n\nuniform float uFeed;\nuniform float uKill;\n\nvec2 sampleAB(vec2 uv) { return texture(sTD2DInputs[0], uv).rg; }\n\nvoid main()\n{\n    vec2 uv = vUV.st;\n    vec2 texel = uTD2DInfos[0].res.xy;\n    vec2 c = sampleAB(uv);\n    float a = c.r;\n    float b = c.g;\n\n    vec2 lap = vec2(0.0);\n    lap += sampleAB(uv + texel * vec2(-1.0, 0.0)) * 0.2;\n    lap += sampleAB(uv + texel * vec2( 1.0, 0.0)) * 0.2;\n    lap += sampleAB(uv + texel * vec2( 0.0,-1.0)) * 0.2;\n    lap += sampleAB(uv + texel * vec2( 0.0, 1.0)) * 0.2;\n    lap += sampleAB(uv + texel * vec2(-1.0,-1.0)) * 0.05;\n    lap += sampleAB(uv + texel * vec2( 1.0,-1.0)) * 0.05;\n    lap += sampleAB(uv + texel * vec2(-1.0, 1.0)) * 0.05;\n    lap += sampleAB(uv + texel * vec2( 1.0, 1.0)) * 0.05;\n    lap -= c;\n\n    float reaction = a * b * b;\n    float da = 1.0 * lap.r - reaction + uFeed * (1.0 - a);\n    float db = 0.5 * lap.g + reaction - (uKill + uFeed) * b;\n\n    float a2 = clamp(a + da, 0.0, 1.0);\n    float b2 = clamp(b + db, 0.0, 1.0);\n    fragColor = TDOutputSwizzle(vec4(a2, b2, 0.0, 1.0));\n}\n"
+  },
+  "preview_description": "Evolving coral / fingerprint-like organic patterns growing and dividing across the frame."
+}

package/recipes/webcam_glitch.json

@@ -0,0 +1,40 @@
+{
+  "id": "webcam_glitch",
+  "name": "Webcam Glitch",
+  "description": "Live webcam pushed through edge detection, RGB split, a feedback loop and a glitch shader for a corrupted-signal look.",
+  "tags": ["webcam", "glitch", "feedback", "realtime"],
+  "difficulty": "intermediate",
+  "td_version_min": "2022",
+  "nodes": [
+    { "name": "cam", "type": "videodeviceinTOP", "comment": "Webcam input" },
+    { "name": "edge", "type": "edgeTOP" },
+    { "name": "rgbsplit", "type": "glslTOP", "comment": "Chromatic RGB offset" },
+    { "name": "feedback1", "type": "feedbackTOP" },
+    { "name": "comp1", "type": "compositeTOP" },
+    { "name": "glitch", "type": "glslTOP", "comment": "Per-band horizontal displacement" },
+    { "name": "out1", "type": "nullTOP" }
+  ],
+  "connections": [
+    { "from": "cam", "to": "edge" },
+    { "from": "edge", "to": "rgbsplit" },
+    { "from": "rgbsplit", "to": "feedback1" },
+    { "from": "rgbsplit", "to": "comp1", "to_input": 0 },
+    { "from": "feedback1", "to": "comp1", "to_input": 1 },
+    { "from": "comp1", "to": "glitch" },
+    { "from": "glitch", "to": "out1" }
+  ],
+  "parameters": [
+    {
+      "name": "feedback_target",
+      "node": "feedback1",
+      "param": "top",
+      "value": "glitch",
+      "description": "Feedback samples the glitch output."
+    }
+  ],
+  "glsl_code": {
+    "rgbsplit": "out vec4 fragColor;\nvoid main(){ vec2 uv=vUV.st; vec2 o=vec2(0.006,0.0);\n  float r=texture(sTD2DInputs[0],uv+o).r; float g=texture(sTD2DInputs[0],uv).g; float b=texture(sTD2DInputs[0],uv-o).b;\n  fragColor=TDOutputSwizzle(vec4(r,g,b,1.0)); }\n",
+    "glitch": "out vec4 fragColor;\nfloat hash(float x){return fract(sin(x*127.1)*43758.5453);}\nvoid main(){ vec2 uv=vUV.st; float band=floor(uv.y*24.0);\n  float off=(hash(band)-0.5)*0.08*step(0.7,hash(band*1.7));\n  fragColor=TDOutputSwizzle(texture(sTD2DInputs[0],uv+vec2(off,0.0))); }\n"
+  },
+  "preview_description": "A ghosted, color-fringed webcam image that periodically tears into horizontal glitch bands."
+}

package/td/README.md

@@ -0,0 +1,160 @@
+# tdmcp TouchDesigner bridge
+
+This folder contains the TouchDesigner-side bridge: a small Python package that
+exposes a REST API (via a **Web Server DAT**) which the `tdmcp` MCP server
+talks to.
+
+> A binary `.tox` cannot be generated from source by an AI agent, so the bridge
+> ships as Python modules plus a callbacks template. Assembling the `.tox` is a
+> one-time, copy-paste install (below). You can then export your own
+> `mcp_webserver_base.tox` from TD for reuse.
+
+## Easiest install
+
+You only need the bridge running inside TouchDesigner once. Pick whichever fits —
+all three create one tidy `tdmcp_bridge` COMP (Web Server DAT + callbacks), are
+idempotent, and can be undone with `from mcp import install; install.uninstall()`.
+
+**A. One paste — no clone, no Preferences.** In the Textport
+(`Dialogs → Textport and DATs`):
+
+```python
+import urllib.request; exec(urllib.request.urlopen("https://raw.githubusercontent.com/Pantani/tdmcp/main/td/bootstrap.py").read().decode())
+```
+
+It downloads the bridge to `~/tdmcp-bridge/modules` and starts it on port 9980.
+(Needs the repo reachable; if it is private, use B or C.)
+
+**B. One line — after adding the module path.** Add the absolute path of
+`td/modules` to **Preferences → "Python 64-bit Module Path"**, then in the
+Textport:
+
+```python
+from mcp import install; install.run()
+```
+
+**C. From the terminal.** `npx @dpantani/tdmcp install-bridge` (or
+`node dist/index.js install-bridge` from a clone) copies the bridge to
+`~/tdmcp-bridge` and prints exactly what to paste in the Textport.
+
+### Make a reusable .tox (drag-and-drop)
+
+Run this once in your own TouchDesigner to bake a component you can drag into any
+project:
+
+```python
+from mcp import install
+install.export("/path/to/mcp_webserver_base.tox", modules_dir="/abs/path/to/td/modules")
+```
+
+Commit that `.tox`; from then on the bridge install is just dragging it in. Pass
+`modules_dir` so the import path travels inside the `.tox`; otherwise the target
+machine still needs `td/modules` on its Preferences module path.
+
+## Layout
+
+```
+td/
+├── modules/
+│   ├── mcp/
+│   │   ├── controllers/api_controller.py   # HTTP router + JSON envelope
+│   │   ├── dev.py                          # reload_bridge(): hot-reload modules in a running TD
+│   │   └── services/
+│   │       ├── api_service.py               # node CRUD, exec, method, info
+│   │       ├── preview_service.py           # TOP → base64 PNG
+│   │       ├── batch_service.py             # create/update/delete/connect
+│   │       └── analysis_service.py          # errors/topology/performance
+│   └── utils/version.py
+└── templates/webserver_callbacks.py        # Web Server DAT callbacks
+```
+
+## Developing the bridge
+
+TouchDesigner imports the bridge modules once at project open, so editing files under
+`td/` does **not** update a running bridge — it keeps serving the code it loaded. After
+editing, reload without reopening the project:
+
+```python
+from mcp import dev
+dev.reload_bridge()   # reimports every mcp.* / utils.* module; returns the names reloaded
+```
+
+Bump `BRIDGE_VERSION` in `modules/utils/version.py` on every bridge change. `get_td_info`
+reports the *running* bridge's version, so when it lags the repo you know the running
+bridge is stale and should be reloaded (or the project reopened).
+
+## Manual install (Web Server DAT, ≈2 minutes)
+
+Prefer to wire it by hand, or can't run the options above? Do it manually:
+
+1. Copy the `td/modules` folder into your project folder, e.g.
+   `<yourproject>/tdmcp/modules` (so you have `<yourproject>/tdmcp/modules/mcp/...`).
+2. In TouchDesigner, add a **Web Server DAT**.
+   - Set **Port** to `9980` (must match `TDMCP_TD_PORT`).
+   - Set **Active** to On.
+3. Point the Web Server DAT's **Callbacks DAT** at a Text DAT containing the
+   contents of `td/templates/webserver_callbacks.py`. If you copied the modules
+   somewhere other than `<project>/tdmcp/modules`, edit the `_MODULES` path at
+   the top of that file.
+4. Save the project. The bridge is now listening.
+
+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"}}
+```
+
+Then run the live smoke test from the repo root:
+
+```bash
+npm run smoke:live
+```
+
+## Global auto-install (recommended)
+
+Instead of wiring a Web Server DAT per project, use the self-installing
+`td/startup.py` so the bridge comes up automatically in any project:
+
+1. Add the absolute path of `td/modules` to **Preferences → "Python 64-bit
+   Module Path"** so `import mcp...` works everywhere. Then leave
+   `MODULES_DIR = ""` in `startup.py`; otherwise set it to that absolute path.
+2. Add an **Execute DAT** and paste the contents of `td/startup.py` into it.
+3. Turn ON the Execute DAT's **Start** and **Create** toggles. It creates and
+   configures `tdmcp_webserver` (port 9980) plus its callbacks on project open.
+4. To apply it to every *new* project, save this project as your **Default
+   Project** (Preferences) with that Execute DAT included.
+
+`install()` is idempotent — re-running just reconfigures the existing ops, so
+it is safe to leave the Execute DAT in place permanently.
+
+## Endpoints
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| GET | `/api/info` | TD/Python/bridge versions |
+| POST | `/api/nodes` | create node `{parent_path,type,name?,parameters?}` |
+| GET | `/api/nodes?parent=…` | list children |
+| GET | `/api/nodes/{path}` | node detail (path is percent-encoded) |
+| PATCH | `/api/nodes/{path}` | update `{parameters}` |
+| DELETE | `/api/nodes/{path}` | delete node |
+| POST | `/api/exec` | run Python `{script,return_output?}` |
+| POST | `/api/nodes/{path}/method` | call `{method,args?,kwargs?}` |
+| GET | `/api/nodes/{path}/errors` | node errors |
+| GET | `/api/preview/{path}` | TOP as base64 PNG |
+| POST | `/api/batch` | `{operations:[…]}` (create/update/delete/connect) |
+| GET | `/api/network/{path}/errors` | recursive errors |
+| GET | `/api/network/{path}/topology` | nodes + connections |
+| GET | `/api/network/{path}/performance` | cook times |
+
+All responses use the envelope `{ "ok": true, "data": … }` or
+`{ "ok": false, "error": { "message": … } }`.
+
+## Notes / known limitations
+
+- Operator types are resolved with a regex-guarded `eval` of the type name (TD
+  exposes operator classes globally). Only `[A-Za-z][A-Za-z0-9_]*` is accepted.
+- `preview` returns the TOP at its native resolution; the requested width/height
+  are advisory in this version.
+- WebSocket event streaming (errors/cook/preview) is stubbed in the callbacks and
+  not yet consumed by the server.

package/td/bootstrap.py

@@ -0,0 +1,73 @@
+"""One-paste TouchDesigner bridge bootstrap (no clone, no Preferences).
+
+Paste this single line into the Textport (Dialogs -> Textport and DATs) and the
+bridge installs itself and starts:
+
+    import urllib.request; exec(urllib.request.urlopen("https://raw.githubusercontent.com/Pantani/tdmcp/main/td/bootstrap.py").read().decode())
+
+It downloads just the bridge modules to ~/tdmcp-bridge/modules, puts them on
+sys.path for this session, and runs install.run() -> a tdmcp_bridge on port 9980.
+
+Requires the GitHub repo (or release zip) to be reachable. If your repo is
+private, point REPO_ZIP at a public release asset, or use `install-bridge`
+(`node dist/index.js install-bridge`) from a local checkout instead.
+"""
+
+import io
+import os
+import sys
+import zipfile
+import urllib.request
+
+REPO_ZIP = "https://github.com/Pantani/tdmcp/archive/refs/heads/main.zip"
+DEST = os.path.expanduser("~/tdmcp-bridge")
+_MARKER = "/td/modules/"
+
+
+def fetch_modules(repo_zip=REPO_ZIP, dest=DEST):
+    """Download the repo zip and extract only its td/modules tree into dest/modules."""
+    modules_dir = os.path.join(dest, "modules")
+    try:
+        data = urllib.request.urlopen(repo_zip, timeout=30).read()
+    except Exception as exc:  # noqa: BLE001 - surface a friendly hint in the Textport
+        raise RuntimeError(
+            "[tdmcp] Could not download the bridge from %r (%s). If the repo is "
+            "private, use a public release asset or the local 'install-bridge' "
+            "command instead." % (repo_zip, exc)
+        )
+
+    zf = zipfile.ZipFile(io.BytesIO(data))
+    os.makedirs(modules_dir, exist_ok=True)
+    extracted = 0
+    for name in zf.namelist():
+        if name.endswith("/"):
+            continue
+        idx = name.find(_MARKER)
+        if idx == -1:
+            continue
+        rel = name[idx + len(_MARKER):]
+        if not rel:
+            continue
+        target = os.path.join(modules_dir, rel)
+        os.makedirs(os.path.dirname(target), exist_ok=True)
+        with zf.open(name) as src, open(target, "wb") as out:
+            out.write(src.read())
+        extracted += 1
+
+    if extracted == 0:
+        raise RuntimeError("[tdmcp] Downloaded archive had no td/modules — wrong REPO_ZIP?")
+    print("[tdmcp] bridge modules -> %s (%d files)" % (modules_dir, extracted))
+    return modules_dir
+
+
+def run(repo_zip=REPO_ZIP, dest=DEST, port=9980):
+    modules_dir = fetch_modules(repo_zip, dest)
+    if modules_dir not in sys.path:
+        sys.path.insert(0, modules_dir)
+    from mcp import install
+
+    return install.run(port=port, modules_dir=modules_dir)
+
+
+# Running via exec(urlopen(...).read()) or as a script kicks off the install.
+run()

package/td/modules/mcp/__init__.py

@@ -0,0 +1 @@
+"""tdmcp TouchDesigner bridge package."""

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

@@ -0,0 +1 @@
+"""HTTP controllers for the tdmcp bridge."""