@dpantani/tdmcp 0.1.0 → 0.2.0

package/README.md

@@ -17,7 +17,9 @@ It works because it pairs two things every other tool was missing:
   TouchDesigner operators instead of guessing.
 - **Real execution** — a small **bridge** running inside TouchDesigner that
   actually creates, connects, inspects and previews nodes — with a
-  create → verify → preview loop so the AI can see and fix its own work.
+  create → verify → preview loop so the AI can see and fix its own work. Every
+  generated network is auto-arranged into a readable left→right layout instead
+  of piling nodes on top of each other.
 
 ---
 
@@ -38,194 +40,176 @@ Three pieces talk to each other on your computer:
 3. **The bridge** — a tiny piece that runs *inside* TouchDesigner so the server
    can actually drive it. You switch it on once per machine.
 
-You set all three up below. It takes about 5 minutes.
+The steps below wire these together — about 5 minutes (less with the one-click
+Claude Desktop extension, which bundles the server for you).
 
 ---
 
 ## What you'll need
 
-- **[TouchDesigner](https://derivative.ca/download)** (free non-commercial
-  edition is fine).
-- **[Node.js](https://nodejs.org) version 20 or newer** — this runs the server.
-  Not sure if you have it? Open a terminal and run `node -v`. If it prints a
-  number ≥ 20 you're set; otherwise install it from the link.
-- An MCP-capable AI client: **Claude Code**, **Claude Desktop**, or **Cursor**.
+- **[TouchDesigner](https://derivative.ca/download)** — the free non-commercial
+  edition is fine.
+- An MCP-capable AI assistant: **Claude Desktop** (easiest), **Claude Code**,
+  **Codex**, or **Cursor**.
+
+**Do I need Node.js?** Only for the build-from-source path (Claude Code, Codex,
+or Cursor), which needs **[Node.js 20+](https://nodejs.org)** — check with
+`node -v`. The
+one-click Claude Desktop extension needs **nothing extra**: Claude Desktop ships
+with its own Node, and the server is bundled inside the `.dxt`.
 
 ---
 
 ## Get started
 
-Setup is **two pieces**: the **bridge** inside TouchDesigner (so it can be
-driven) and the **tdmcp server** connected to your AI. Below, pick the path for
-your AI client — **every path also needs the bridge in Step 2.** Budget ~5 min.
+You set up **two sides**: your **AI** (so it gets the tdmcp tools) and
+**TouchDesigner** (so the AI can drive it). Pick whichever way is easiest for you.
 
-> **Which path?** Claude Desktop → the one-click extension just below. Claude
-> Code or Cursor → Steps 1–3.
+**🤖 The easiest way — let your AI install it for you.** If you already use
+**Claude Code**, **Codex**, or **Cursor**, you don't have to do any of the manual
+steps below. Just **paste this one message** into it:
 
-> 🤖 **Or let an AI do it for you.** Hand
-> [`tdmcp-install-prompt.md`](tdmcp-install-prompt.md) to Claude Code, Codex, or
-> Cursor and it runs the install and client wiring itself — you only paste one
-> line into TouchDesigner at the end. The manual steps below are the alternative
-> if you'd rather drive it yourself.
+```text
+Install and connect tdmcp for me by reading and following
+https://raw.githubusercontent.com/Pantani/tdmcp/main/tdmcp-install-prompt.md
+Do every step yourself; only stop when you need me to paste one line into TouchDesigner.
+```
 
-### Claude Desktop: the one-click extension (`.dxt`) — easiest
+**That's the whole install.** Your AI clones, builds, and wires everything up on
+its own. The *only* thing it will ask you to do is paste one line into
+TouchDesigner's Textport when it's ready — nothing else. (It's the
+[`tdmcp-install-prompt.md`](tdmcp-install-prompt.md) runbook doing the work.)
 
-A `.dxt` is a single file that Claude Desktop installs as an **extension**. The
-tdmcp server is **bundled inside it**, and you set the TouchDesigner host/port in
-a settings form — no JSON, no `claude mcp add`, nothing to keep running yourself.
+**Prefer to do it yourself, or using Claude Desktop?** Follow the three manual
+steps below — Step 1's one-click `.dxt` is the no-terminal, no-Node route for
+Claude Desktop.
 
-**1. Get the `tdmcp.dxt` file.** Download the latest prebuilt bundle:
+### Step 1 — Connect tdmcp to your AI
 
-**[⬇ Download tdmcp.dxt](https://github.com/Pantani/tdmcp/releases/latest/download/tdmcp.dxt)** — always the newest release.
+Pick the one tab that matches your client.
 
-<details>
-<summary>Or build it yourself (needs <a href="https://nodejs.org">Node 20+</a>)</summary>
+<details open>
+<summary><b>🟢 Claude Desktop — one-click <code>.dxt</code> (easiest: no terminal, no Node)</b></summary>
 
-```bash
-git clone https://github.com/Pantani/tdmcp.git
-cd tdmcp
-npm install
-npm run build:dxt      # writes tdmcp.dxt into this folder
-```
+<br />
 
-</details>
+A `.dxt` is **one file** Claude Desktop installs as an extension. The tdmcp server
+is **bundled inside it** — no terminal, no Node install, nothing to keep running
+yourself.
 
-**2. Install it in Claude Desktop.** Open **Settings → Extensions**, choose
-**Install from file** (or drag `tdmcp.dxt` onto the window). When asked, set the
-TouchDesigner **host** / **port** if they differ from `127.0.0.1` / `9980`, then
-**enable** the extension.
+1. **Download** the bundle →
+   **[⬇ tdmcp.dxt](https://github.com/Pantani/tdmcp/releases/latest/download/tdmcp.dxt)**
+   (always the latest release).
+2. **Install it:** in Claude Desktop open **Settings → Extensions**, then drag
+   `tdmcp.dxt` onto the window (or click **Install from file**).
+3. **Enable it.** Leave the TouchDesigner **host** / **port** at `127.0.0.1` /
+   `9980` unless you changed them.
 
-**3. Turn on the bridge** inside TouchDesigner — do **Step 2** below. The
-extension *drives* TouchDesigner; the bridge is what lets it in.
+Connected — **now do Step 2** to turn on the bridge. (Docker/HTTP options live in
+[`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md).)
 
-That's the whole Claude Desktop setup — skip to **Step 4** and start creating.
-More detail (and the Docker/HTTP options) live in
-[`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md).
+</details>
 
----
+<details>
+<summary><b>Claude Code, Codex, or Cursor — build from source (needs Node 20+)</b></summary>
 
-### Step 1 — Install the tdmcp server (once) · Claude Code / Cursor
+<br />
 
-Open a terminal and run these four lines. You only ever do this once.
+This path builds the server locally, so you need
+**[Node.js 20+](https://nodejs.org)** (`node -v` to check).
 
 ```bash
 git clone https://github.com/Pantani/tdmcp.git
 cd tdmcp
-npm install
-npm run build
+npm run setup
 ```
 
-When it finishes you'll have a ready-to-run server at `dist/index.js`.
-
-> ⚡ **Shortcut:** instead of `npm install && npm run build`, run **`npm run
-> setup`** (or `./setup.sh`). It installs, builds, and then prints the exact line
-> to connect your AI — with your real paths already filled in.
-
-> 💡 **Tip — you'll need this folder's full path twice below.** While you're
-> still in the `tdmcp` folder, run `pwd`. Copy what it prints (e.g.
-> `/Users/you/tdmcp`) — that's your **project path**. Wherever the steps below
-> say `<project-path>`, paste it in.
+`npm run setup` installs, builds, and then **prints the exact line to connect your
+AI**, with your real paths already filled in — paste it and you're done. The manual
+equivalents:
 
-### Step 2 — Switch on the bridge inside TouchDesigner
+- **Claude Code:**
 
-This lets the server actually control TouchDesigner. The easy, set-and-forget way:
-
-1. **Open TouchDesigner.**
-2. Open **Preferences** (`Edit → Preferences`, or the **TouchDesigner** menu on
-   macOS). In the **General** section, find **"Python 64-bit Module Path"** and
-   paste:
-
-   ```
-   <project-path>/td/modules
-   ```
+  ```bash
+  claude mcp add tdmcp -- node <project-path>/dist/index.js
+  ```
 
-   (That's the `tdmcp` folder you cloned — e.g. `/Users/you/tdmcp/td/modules`; run
-   `pwd` inside it if you're unsure of the full path.) Click OK.
-3. Open the **Textport** (`Dialogs → Textport and DATs`), type this one line and
-   press Enter:
+- **Codex CLI:**
 
-   ```python
-   from mcp import install; install.run()
-   ```
+  ```bash
+  codex mcp add tdmcp -- node <project-path>/dist/index.js
+  ```
 
-You should see:
+  Prefer editing config by hand? Add this to `~/.codex/config.toml`:
 
-```
-[tdmcp] bridge running on port 9980 (/project1/tdmcp_bridge)
-```
+  ```toml
+  [mcp_servers.tdmcp]
+  command = "node"
+  args = ["<project-path>/dist/index.js"]
+  ```
 
-Done — a `tdmcp_bridge` node now lives in your network and is listening. ✅
+- **Cursor** — create `.cursor/mcp.json` in your workspace:
 
-> This is **safe and reversible**: it only adds one tidy `tdmcp_bridge` component.
-> Re-running the line just reconfigures it. To remove it later, run
-> `from mcp import install; install.uninstall()`.
->
-> Want it to start automatically in *every* project? Save the project (with that
-> Module Path preference) as your **Default Project**, or see
-> [`td/README.md`](td/README.md) for the Execute-DAT auto-start and the fully
-> manual Web Server DAT setup.
+  ```json
+  {
+    "mcpServers": {
+      "tdmcp": { "command": "node", "args": ["<project-path>/dist/index.js"] }
+    }
+  }
+  ```
 
-**Two even-easier ways to do Step 2:**
+`<project-path>` is the folder you cloned — run `pwd` inside it for the full path.
+Restart your client afterward so it loads the server. **Now do Step 2.**
 
-- **No clone, no Preferences** — paste this single line into the Textport. It
-  fetches the bridge and starts it for you:
+</details>
 
-  ```python
-  import urllib.request; exec(urllib.request.urlopen("https://raw.githubusercontent.com/Pantani/tdmcp/main/td/bootstrap.py").read().decode())
-  ```
+### Step 2 — Turn on the bridge inside TouchDesigner (everyone)
 
-- **From the terminal** — if you installed the server with `npx` (so there's no
-  local `td/modules`), run `npx @dpantani/tdmcp install-bridge` (or
-  `node <project-path>/dist/index.js install-bridge` from a clone). It copies the
-  bridge to `~/tdmcp-bridge` and prints the exact line to paste in the Textport.
+This is the **same one line** no matter which client you set up in Step 1 — it's
+what lets the server actually drive TouchDesigner.
 
-### Step 3 — Connect your AI assistant
+1. **Open TouchDesigner.**
+2. Open the **Textport** (`Dialogs → Textport and DATs`), paste this **one line**
+   and press Enter:
 
-Point your AI client at the server you built in Step 1. Pick your client:
+   ```python
+   import urllib.request; exec(urllib.request.urlopen("https://raw.githubusercontent.com/Pantani/tdmcp/main/td/bootstrap.py").read().decode())
+   ```
 
-**Claude Code**
+You should see:
 
-```bash
-claude mcp add tdmcp -- node <project-path>/dist/index.js
 ```
-
-> Once tdmcp is published to npm this becomes path-free:
-> `claude mcp add tdmcp -- npx -y @dpantani/tdmcp`.
-
-**Claude Desktop** — the easiest route is the **one-click `.dxt` extension**
-described at the top of *Get started* (no config file needed). To wire it up
-manually instead, edit `claude_desktop_config.json`
-(`Settings → Developer → Edit Config`) and add:
-
-```json
-{
-  "mcpServers": {
-    "tdmcp": {
-      "command": "node",
-      "args": ["<project-path>/dist/index.js"]
-    }
-  }
-}
+[tdmcp] bridge running on port 9980 (/project1/tdmcp_bridge)
 ```
 
-**Cursor** — create `.cursor/mcp.json` in your workspace:
+Done — a `tdmcp_bridge` node now lives in your network and is listening. ✅ It's
+safe and reversible: it only adds that one tidy component, and re-running the line
+just reconfigures it.
 
-```json
-{
-  "mcpServers": {
-    "tdmcp": {
-      "command": "node",
-      "args": ["<project-path>/dist/index.js"]
-    }
-  }
-}
-```
+<details>
+<summary>Keep it on across restarts · other install methods · removing it</summary>
+
+<br />
+
+- **Start it automatically in every project:** save your project as your
+  **Default Project**, or use the Execute-DAT auto-start in
+  [`td/README.md`](td/README.md).
+- **If you cloned the repo** and want a set-and-forget install: add
+  `<project-path>/td/modules` to TouchDesigner's **Python 64-bit Module Path**
+  (`Edit → Preferences → General`), then run
+  `from mcp import install; install.run()` in the Textport.
+- **From a terminal:** `npx @dpantani/tdmcp install-bridge` (or
+  `node <project-path>/dist/index.js install-bridge` from a clone) copies the
+  bridge to `~/tdmcp-bridge` and prints the Textport line.
+- **Remove it later:** `from mcp import install; install.uninstall()`.
+- **Port 9980 taken?** Set it in both places — the bridge
+  (`install.run(port=9981)`) and the client (`TDMCP_TD_PORT=9981`).
 
-Restart your AI client so it picks up the new server.
+</details>
 
-### Step 4 — Make something
+### Step 3 — Make something
 
-With TouchDesigner open and your AI client connected, just ask in plain language:
+With TouchDesigner open and your AI connected, just ask in plain language:
 
 > *"Create an audio-reactive particle galaxy and show me a preview."*
 
@@ -233,6 +217,9 @@ The AI builds the network in your project, checks it for errors, and returns a
 thumbnail. Iterate from there: *"make it warmer,"* *"add a feedback trail,"*
 *"output it fullscreen."*
 
+> 💡 Once tdmcp is published to npm, the Claude Code wiring becomes path-free:
+> `claude mcp add tdmcp -- npx -y @dpantani/tdmcp`.
+
 ---
 
 ## Troubleshooting
@@ -240,7 +227,7 @@ thumbnail. Iterate from there: *"make it warmer,"* *"add a feedback trail,"*
 | What you see | What to do |
 | --- | --- |
 | The AI says **"TouchDesigner isn't reachable."** | Make sure TD is open and the bridge is on (Step 2). Test it: `curl http://127.0.0.1:9980/api/info` should return JSON. |
-| `from mcp import install` → **`No module named 'mcp'`** | The Module Path isn't set. Re-check Step 2.2 — it must point at `<project-path>/td/modules`, then restart TouchDesigner. |
+| `from mcp import install` → **`No module named 'mcp'`** | You're using the Module-Path method but it isn't set — point it at `<project-path>/td/modules` (see Step 2's collapsed options) and restart TouchDesigner. Or just use the one-line bootstrap in Step 2 instead. |
 | **`command not found: node` / `npm`** | Node isn't installed (or is too old). Install Node ≥ 20 from [nodejs.org](https://nodejs.org) and reopen the terminal. |
 | **Your AI client doesn't list any tdmcp tools** | Restart the client after adding the server, and double-check the path to `dist/index.js` is the full absolute path. |
 | **Port 9980 is already taken** | Set a different port in *both* places: the bridge (`install.run(port=9981)`) and the client (`TDMCP_TD_PORT=9981`). |
@@ -255,11 +242,24 @@ return a friendly "not reachable" message instead of crashing.
 **Artist tools** (describe the result, get a whole network):
 `create_visual_system`, `create_feedback_network`, `create_generative_art`,
 `create_audio_reactive`, `create_particle_system`, `create_data_visualization`,
-`apply_post_processing`, `setup_output`, `get_preview`, `plan_visual`.
+`apply_post_processing`, `setup_output`, `get_preview`, `plan_visual`. Feedback,
+particle, generative and audio-reactive systems arrive already playable — they
+auto-expose a control panel (a Feedback knob, particle Drag/Turbulence/Gravity/Lifetime,
+an evolution-Speed knob, an audio Sensitivity knob) you can tweak, animate, preset, or
+map to a controller. Pass `expose_controls: false` to opt out.
 
 **Building blocks**: `create_node_chain`, `connect_nodes`, `create_glsl_shader`,
 `create_python_script`, `set_parameters_batch`, `create_container`,
-`duplicate_network`.
+`duplicate_network`, `arrange_network` (tidy a messy network into a readable
+left→right layout).
+
+**Live control, animation & I/O** (make a generated system playable):
+`create_control_panel` (add knobs/sliders/toggles to a COMP and bind them to node
+parameters), `manage_presets` (store/recall/list named snapshots of those controls),
+`animate_parameter` (drive parameters with an LFO over time — no manual keyframing),
+`create_external_io` (OSC/MIDI input mapped straight to parameters, DMX/Art-Net out
+for lighting, NDI/Syphon-Spout video in), and `manage_component` (save/load reusable
+`.tox` components).
 
 **Atomic operations**: `create_td_node`, `delete_td_node`,
 `update_td_node_parameters`, `execute_python_script`, `exec_node_method`.
@@ -269,10 +269,12 @@ return a friendly "not reachable" message instead of crashing.
 `get_td_class_details`, `get_module_help` (plus search / summary / compare /
 snapshot helpers).
 
-**Recipes** — 10 validated, ready-to-build templates: `feedback_tunnel`,
-`reaction_diffusion`, `noise_landscape`, `audio_spectrum_bars`, `particle_galaxy`,
-`webcam_glitch`, `data_sonification`, `kinect_silhouette`, `led_strip_mapper`,
-`projection_mapping`.
+**Recipes** — 11 validated, ready-to-build templates: `feedback_tunnel`,
+`performable_feedback_tunnel` (the same tunnel pre-wired with live knobs for
+decay/zoom/spin/blur — ready to perform, animate with an LFO, or snapshot as
+presets), `reaction_diffusion`, `noise_landscape`, `audio_spectrum_bars`,
+`particle_galaxy`, `webcam_glitch`, `data_sonification`, `kinect_silhouette`,
+`led_strip_mapper`, `projection_mapping`.
 
 **Knowledge resources** the AI reads from:
 `tdmcp://operators/{category|name}`, `tdmcp://python-api/{class}`,
@@ -337,6 +339,11 @@ machine TD runs on:
   holds even without a token); the structured endpoints keep working.
 - The MCP server itself binds to loopback (`127.0.0.1`) for both stdio and HTTP
   transports and enables DNS-rebinding protection on HTTP.
+- **The bridge refuses browser cross-origin requests.** Any request carrying an
+  `Origin` header that isn't loopback (`127.0.0.1`/`localhost`) is rejected (HTTP
+  `401`), so a malicious web page open in your browser can't quietly POST to the
+  bridge (CSRF / DNS-rebinding → drive-by code execution). The MCP server sends no
+  `Origin`, so normal use is unaffected.
 
 ### Command-line agent (`tdmcp-agent`)
 
@@ -385,7 +392,7 @@ npm run smoke:live   # creates a Noise→Null chain in /project1 and grabs a pre
 
 ## Current state
 
-- ✅ 35 tools across 3 layers, 6 resource families, 5 prompts, 10 recipes, a
+- ✅ 41 tools across 3 layers, 6 resource families, 5 prompts, 11 recipes, a
   feedback engine, and the TouchDesigner Python bridge.
 - ✅ Two transports: **stdio** (default) and **Streamable HTTP**; plus an optional
   **WebSocket event stream** (TD → MCP logging notifications).

package/dist/cli/agent.d.ts

@@ -252,6 +252,24 @@ declare const RecipeSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     glsl_code: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     python_code: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    controls: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodDefault<z.ZodEnum<{
+            string: "string";
+            int: "int";
+            float: "float";
+            toggle: "toggle";
+            menu: "menu";
+            rgb: "rgb";
+            pulse: "pulse";
+        }>>;
+        label: z.ZodOptional<z.ZodString>;
+        min: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        max: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean, z.ZodString]>>;
+        menu_items: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        bind_to: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
     preview_description: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>;
 type Recipe = z.infer<typeof RecipeSchema>;
@@ -346,6 +364,7 @@ declare class TouchDesignerClient {
         path: string;
         type: string;
         name: string;
+        parameter_warnings?: string[] | undefined;
     }>;
     deleteNode(path: string): Promise<{
         deleted: string;
@@ -355,6 +374,7 @@ declare class TouchDesignerClient {
             path: string;
             type: string;
             name: string;
+            parameter_warnings?: string[] | undefined;
         }[];
     }>;
     getNode(path: string): Promise<{
@@ -362,6 +382,7 @@ declare class TouchDesignerClient {
         type: string;
         name: string;
         parameters: Record<string, unknown>;
+        parameter_warnings?: string[] | undefined;
         inputs?: string[] | undefined;
         outputs?: string[] | undefined;
         family?: string | undefined;
@@ -372,6 +393,7 @@ declare class TouchDesignerClient {
         type: string;
         name: string;
         parameters: Record<string, unknown>;
+        parameter_warnings?: string[] | undefined;
         inputs?: string[] | undefined;
         outputs?: string[] | undefined;
         family?: string | undefined;
@@ -420,6 +442,7 @@ declare class TouchDesignerClient {
             path: string;
             type: string;
             name: string;
+            parameter_warnings?: string[] | undefined;
         }[];
         connections: {
             source_path: string;
@@ -428,7 +451,7 @@ declare class TouchDesignerClient {
             target_input: number;
         }[];
     }>;
-    getNetworkPerformance(path: string): Promise<{
+    getNetworkPerformance(path: string, recursive?: boolean): Promise<{
         nodes: {
             path: string;
             cook_time_ms: number;