@dpantani/tdmcp 0.2.0 → 0.3.1

package/README.md

@@ -1,9 +1,14 @@
-# tdmcp — build TouchDesigner from plain language
+# tdmcp — TouchDesigner MCP server
 
-**tdmcp** lets you create real visual systems in
-[TouchDesigner](https://derivative.ca) just by describing them to an AI assistant
-(Claude, Cursor, …). You type what you want; the AI builds the actual network of
-nodes inside your project, checks it for errors, and shows you a preview.
+[![CI](https://github.com/Pantani/tdmcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Pantani/tdmcp/actions/workflows/ci.yml)
+[![Docs](https://github.com/Pantani/tdmcp/actions/workflows/docs.yml/badge.svg)](https://pantani.github.io/tdmcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**tdmcp is a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server
+for [TouchDesigner](https://derivative.ca)** — build TouchDesigner from plain
+language. You describe a visual to an AI assistant (Claude, Claude Code, Cursor,
+Codex); the AI builds the actual network of nodes inside your project, checks it
+for errors, and shows you a preview.
 
 > *"Create a feedback tunnel from noise with blur and displace, then add bloom and
 > output it to a window."*
@@ -13,15 +18,27 @@ nodes inside your project, checks it for errors, and shows you a preview.
 It works because it pairs two things every other tool was missing:
 
 - **Real knowledge** — an embedded reference of 629 operators, 68 Python classes,
-  32 workflow patterns, GLSL techniques and tutorials, so the AI uses real
+  workflow patterns, GLSL techniques and tutorials, so the AI uses real
   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. Every
-  generated network is auto-arranged into a readable left→right layout instead
-  of piling nodes on top of each other.
+  generated network is auto-arranged into a readable left→right layout.
+
+## 📖 Documentation
+
+Full guides and reference live on the **docs site → <https://pantani.github.io/tdmcp/>**
+
+| For artists / musicians | For developers |
+| --- | --- |
+| [What is tdmcp?](https://pantani.github.io/tdmcp/guide/what-is-tdmcp) | [Architecture](https://pantani.github.io/tdmcp/reference/architecture) |
+| [Install (no terminal)](https://pantani.github.io/tdmcp/guide/install) | [Tools reference](https://pantani.github.io/tdmcp/reference/tools) |
+| [Your first visual](https://pantani.github.io/tdmcp/guide/first-visual) | [Environment variables](https://pantani.github.io/tdmcp/reference/environment) |
+| [Prompt cookbook](https://pantani.github.io/tdmcp/guide/prompt-cookbook) | [CLI & local copilot](https://pantani.github.io/tdmcp/reference/cli) |
+| [Recipe gallery](https://pantani.github.io/tdmcp/guide/recipes) | [Bridge & REST API](https://pantani.github.io/tdmcp/reference/bridge-api) |
+| [Troubleshooting](https://pantani.github.io/tdmcp/guide/troubleshooting) | [Roadmap](docs/ROADMAP.md) · [Deployment](docs/DEPLOYMENT.md) |
 
----
+🇧🇷 **Documentação em português:** <https://pantani.github.io/tdmcp/pt/>
 
 ## How it works
 
@@ -40,11 +57,6 @@ 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.
 
-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)** — the free non-commercial
@@ -52,22 +64,17 @@ Claude Desktop extension, which bundles the server for you).
 - 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`.
-
----
+Node.js is only needed for the build-from-source path (**[Node 20+](https://nodejs.org)**).
+The one-click Claude Desktop extension needs nothing extra — the server is bundled
+inside the `.mcpb` (formerly `.dxt`; legacy `.dxt` files still install).
 
 ## Get started
 
 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.
+**TouchDesigner** (so the AI can drive it).
 
-**🤖 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:
+**🤖 Easiest — let your AI install it.** Using **Claude Code**, **Codex**, or
+**Cursor**? Paste this one message in:
 
 ```text
 Install and connect tdmcp for me by reading and following
@@ -75,345 +82,81 @@ 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.
 ```
 
-**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.)
-
-**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.
-
-### Step 1 — Connect tdmcp to your AI
-
-Pick the one tab that matches your client.
-
-<details open>
-<summary><b>🟢 Claude Desktop — one-click <code>.dxt</code> (easiest: no terminal, no Node)</b></summary>
-
-<br />
-
-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.
-
-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.
-
-Connected — **now do Step 2** to turn on the bridge. (Docker/HTTP options live in
-[`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md).)
+It clones, builds and wires everything up; the only manual step is pasting one
+line into TouchDesigner (Step 2 below).
 
-</details>
+**🟢 Claude Desktop — one-click `.mcpb` (no terminal, no Node).** Download
+**[tdmcp.mcpb](https://github.com/Pantani/tdmcp/releases/latest/download/tdmcp.mcpb)**,
+then in Claude Desktop open **Settings → Extensions** and install it (drag it in or
+**Install from file**). Leave host/port at `127.0.0.1` / `9980`. Full walkthrough:
+[the install guide](https://pantani.github.io/tdmcp/guide/install).
 
-<details>
-<summary><b>Claude Code, Codex, or Cursor — build from source (needs Node 20+)</b></summary>
-
-<br />
-
-This path builds the server locally, so you need
-**[Node.js 20+](https://nodejs.org)** (`node -v` to check).
+**🛠️ Claude Code / Codex / Cursor — build from source.**
 
 ```bash
 git clone https://github.com/Pantani/tdmcp.git
 cd tdmcp
-npm run setup
+npm run setup   # installs, builds, and prints the exact line to connect your client
 ```
 
-`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:
-
-- **Claude Code:**
-
-  ```bash
-  claude mcp add tdmcp -- node <project-path>/dist/index.js
-  ```
-
-- **Codex CLI:**
-
-  ```bash
-  codex mcp add tdmcp -- node <project-path>/dist/index.js
-  ```
-
-  Prefer editing config by hand? Add this to `~/.codex/config.toml`:
-
-  ```toml
-  [mcp_servers.tdmcp]
-  command = "node"
-  args = ["<project-path>/dist/index.js"]
-  ```
-
-- **Cursor** — create `.cursor/mcp.json` in your workspace:
-
-  ```json
-  {
-    "mcpServers": {
-      "tdmcp": { "command": "node", "args": ["<project-path>/dist/index.js"] }
-    }
-  }
-  ```
-
-`<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.**
-
-</details>
-
-### Step 2 — Turn on the bridge inside TouchDesigner (everyone)
-
-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.
-
-1. **Open TouchDesigner.**
-2. Open the **Textport** (`Dialogs → Textport and DATs`), paste this **one line**
-   and press Enter:
+### Turn on the bridge inside TouchDesigner (everyone)
 
-   ```python
-   import urllib.request; exec(urllib.request.urlopen("https://raw.githubusercontent.com/Pantani/tdmcp/main/td/bootstrap.py").read().decode())
-   ```
+Open TouchDesigner, open the **Textport** (`Dialogs → Textport and DATs`), paste
+this **one line** and press Enter:
 
-You should see:
-
-```
-[tdmcp] bridge running on port 9980 (/project1/tdmcp_bridge)
+```python
+import urllib.request; exec(urllib.request.urlopen("https://raw.githubusercontent.com/Pantani/tdmcp/main/td/bootstrap.py").read().decode())
 ```
 
-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.
-
-<details>
-<summary>Keep it on across restarts · other install methods · removing it</summary>
-
-<br />
+You should see `[tdmcp] bridge running on port 9980 (/project1/tdmcp_bridge)`. ✅
+It's safe and reversible — it adds one tidy component; remove it later with
+`from mcp import install; install.uninstall()`. Other install methods (module
+path, terminal, reusable `.tox`) are in the
+[bridge docs](https://pantani.github.io/tdmcp/reference/bridge-api).
 
-- **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`).
+### Make something
 
-</details>
-
-### Step 3 — Make something
-
-With TouchDesigner open and your AI connected, just ask in plain language:
+With TouchDesigner open and your AI connected, ask in plain language:
 
 > *"Create an audio-reactive particle galaxy and show me a preview."*
 
-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`.
-
----
+The AI builds the network, checks it for errors, and returns a thumbnail. Iterate:
+*"make it warmer," "add a feedback trail," "output it fullscreen."* More ideas in
+the [prompt cookbook](https://pantani.github.io/tdmcp/guide/prompt-cookbook).
 
-## Troubleshooting
-
-| 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'`** | 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`). |
-
-The server runs fine even when TouchDesigner is closed — TD-dependent tools just
-return a friendly "not reachable" message instead of crashing.
-
----
+> **Not connecting?** The two most common fixes: make sure the bridge is on
+> (`curl http://127.0.0.1:9980/api/info` returns JSON), and **restart your AI
+> client** after adding the server. Full
+> [troubleshooting](https://pantani.github.io/tdmcp/guide/troubleshooting).
 
 ## What you can do
 
-**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`. 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`, `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`.
-
-**Inspect & analyze**: `get_td_info`, `get_td_nodes`, `get_td_node_parameters`,
-`get_td_node_errors`, `get_td_performance`, `get_td_topology`, `get_td_classes`,
-`get_td_class_details`, `get_module_help` (plus search / summary / compare /
-snapshot helpers).
-
-**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}`,
-`tdmcp://patterns/{name}`, `tdmcp://glsl/{name}`, `tdmcp://recipes/{name}`,
-`tdmcp://tutorials/{name}`.
-
-**Prompt modes**: `visual_artist_mode`, `debug_network`, `optimize_performance`,
-`explain_network`, `remix_visual`.
-
----
-
-## Architecture (for developers)
-
-```
-MCP client ──stdio──▶ tdmcp server (Node/TS) ──HTTP──▶ TouchDesigner bridge (Python)
-                       ├── Layer 1  artist tools (create_visual_system, …)
-                       ├── Layer 2  building blocks (create_node_chain, …)
-                       ├── Layer 3  atomic ops (create_td_node, …)
-                       ├── Knowledge base (MCP resources)
-                       ├── Recipes (validated network templates)
-                       └── Feedback engine (errors / preview / performance)
-```
-
-### Environment variables
-
-| Variable | Default | Description |
-| --- | --- | --- |
-| `TDMCP_TD_HOST` | `127.0.0.1` | TouchDesigner bridge host |
-| `TDMCP_TD_PORT` | `9980` | Web Server DAT port |
-| `TDMCP_TRANSPORT` | `stdio` | MCP transport: `stdio` (default) or `http` (Streamable HTTP) |
-| `TDMCP_HTTP_PORT` | `3939` | Port for the HTTP transport (when `TDMCP_TRANSPORT=http`) |
-| `TDMCP_EVENTS` | `on` | Subscribe to TD WebSocket events and forward them as MCP logging notifications (`on`/`off`) |
-| `TDMCP_RAW_PYTHON` | `on` | Whether to expose the raw-Python escape-hatch tools (`execute_python_script`, `exec_node_method`). Set to `off` to lock them out for restricted setups |
-| `TDMCP_BRIDGE_TOKEN` | _(unset)_ | Optional shared bearer token. When set, the server sends it and the bridge requires it — set the **same** value in TouchDesigner's environment to turn auth on |
-| `TDMCP_BRIDGE_ALLOW_EXEC` | `1` | **Set in TouchDesigner's environment.** Set to `0`/`false`/`off` to make the bridge refuse the arbitrary-code endpoints (`/api/exec`, node `method`) — enforced bridge-side, even for direct network callers |
-| `TDMCP_LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` / `silent` (stderr) |
-| `TDMCP_REQUEST_TIMEOUT_MS` | `10000` | Per-request timeout to the bridge |
-
-The HTTP transport (`TDMCP_TRANSPORT=http`) serves MCP at `POST/GET/DELETE /mcp`
-on `127.0.0.1:$TDMCP_HTTP_PORT` with stateful sessions — handy for remote/headless
-setups. See [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) for Docker and the Claude
-Desktop `.dxt` extension.
-
-### Security
-
-The TouchDesigner bridge runs **arbitrary Python inside your TD process** (that is
-what lets the assistant build networks for you). Treat it like an open door to the
-machine TD runs on:
-
-- **The Web Server DAT listens on its port (default `9980`) on all network
-  interfaces.** Anyone who can reach `http://<your-ip>:9980` can run code on that
-  machine. Only run it on a trusted network, and/or firewall the port to localhost.
-- **Turn on bridge auth for untrusted networks:** set `TDMCP_BRIDGE_TOKEN` to a
-  shared secret in **both** the MCP server's environment and TouchDesigner's
-  environment. The bridge then rejects any request without a matching
-  `Authorization: Bearer <token>` (HTTP `401`). Unset (default) keeps the
-  zero-config local flow.
-- `TDMCP_RAW_PYTHON=off` hides the raw-Python MCP tools, but it only gates the
-  **MCP-server side** — a direct network caller could still hit the bridge's
-  `/api/exec` and node-`method` endpoints. To close them at the bridge itself, set
-  `TDMCP_BRIDGE_ALLOW_EXEC=0` in TouchDesigner's environment (defense in depth that
-  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`)
-
-The package also installs a second binary, `tdmcp-agent`, that drives the same
-tools from a shell with machine-readable output — useful for scripts and CI:
-
-```bash
-tdmcp-agent --help                 # list commands
-tdmcp-agent info                   # health check + TD/bridge info
-tdmcp-agent nodes find --params '{"parent_path":"/project1","type":"TOP"}'
-tdmcp-agent nodes create --dry-run --params '{"parent_path":"/project1","type":"noiseTOP"}'
-tdmcp-agent schema "nodes create" # print a command's JSON Schema
-```
-
-Output format is `--output json` (default) / `ndjson` / `text`. Mutating commands
-are tagged `mutates`; the Python escape hatches require `--allow-unsafe` and honour
-`TDMCP_RAW_PYTHON=off`.
-
-### Scripts
-
-| Script | Purpose |
-| --- | --- |
-| `npm run setup` | guided install + build, then prints how to connect your client |
-| `npm run dev` | run the server from source (stdio) |
-| `npm run build` | typecheck + bundle + copy assets to `dist/` |
-| `npm test` | unit + integration tests (Vitest + MSW) |
-| `npm run typecheck` / `npm run lint` | TypeScript / Biome |
-| `npm run smoke:live` | end-to-end test against a running TD |
-| `npm run validate:recipes` | validate every recipe JSON |
-| `npm run import:bottobot` | (re)build the embedded knowledge base — only needed to refresh it |
-| `npm run build:dxt` | package a Claude Desktop `.dxt` extension (see `docs/DEPLOYMENT.md`) |
-
-> The knowledge base ships in the repo, so a fresh clone needs only
-> `npm install && npm run build`. `import:bottobot` is a maintenance command for
-> regenerating it from `@bottobot/td-mcp`.
-
-### Verify end-to-end
-
-With TD open and the bridge running:
-
-```bash
-npm run smoke:live   # creates a Noise→Null chain in /project1 and grabs a preview
-```
-
----
-
-## Current state
-
-- ✅ 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).
-- ✅ `typecheck`, `build`, `lint`, and `test` all pass; the server boots over
-  stdio with clean stdout.
-- 🔌 Verified end-to-end against a live TouchDesigner (CRUD, preview, batch, and
-  `node.created`/`node.deleted` events).
-
-## Known limitations
-
-- **WebSocket events** (`node.created` / `node.deleted` / `node.error` /
-  `project.saved` / `timeline.frame` / `node.cook`) are forwarded as MCP logging
-  notifications on both transports. High-frequency events (`timeline.frame`,
-  `node.cook`) are dropped by the consumer unless explicitly opted in.
-- **Audio / particle / 3D builders and the exotic recipes** (kinect, LED,
-  projection) produce valid, connected networks but use best-effort TD parameter
-  names — fine-tuning may be needed, and they emit warnings to that effect.
-- **Preview** returns the TOP at its native resolution (the requested size is
-  advisory).
-- The bridge ships as Python modules plus a callbacks template (a binary `.tox`
-  can't be generated from source); the one-liner in Step 2 assembles it for you.
+**102+ tools** across three layers, plus an Obsidian vault integration — from
+one-line artist generators (`create_feedback_network`, `create_audio_reactive`,
+`create_particle_system`, `create_generative_art`, …) to building blocks
+(`create_control_panel`, `animate_parameter`, `create_external_io` for
+OSC/MIDI/DMX/NDI, …) down to atomic node CRUD and inspection. Many systems arrive
+**already playable**, with a control panel you can tweak, preset, or map to a
+controller. See the full, always-current
+[tools reference](https://pantani.github.io/tdmcp/reference/tools) and the
+[recipe gallery](https://pantani.github.io/tdmcp/guide/recipes).
+
+## Security
+
+The bridge runs **arbitrary Python inside your TD process** and listens on port
+`9980` on all interfaces — treat it like an open door to that machine. Run it only
+on a trusted network, and for untrusted networks turn on bridge auth
+(`TDMCP_BRIDGE_TOKEN`) and/or disable the exec endpoints
+(`TDMCP_BRIDGE_ALLOW_EXEC=0`). Details:
+[Security](https://pantani.github.io/tdmcp/reference/architecture#security).
+
+## Contributing & development
+
+Build with `npm install && npm run build`; run `npm test`, `npm run typecheck`,
+`npm run lint`. Work on the docs with `npm run docs:dev` (the
+[tools reference](https://pantani.github.io/tdmcp/reference/tools) is generated by
+`scripts/gen-tool-docs.ts`). See [CONTRIBUTING.md](CONTRIBUTING.md),
+[CHANGELOG.md](CHANGELOG.md), and the [roadmap](docs/ROADMAP.md).
 
 ## License
 

package/dist/cli/agent.d.ts

@@ -7,6 +7,12 @@ interface Logger {
     error(message: string, meta?: Record<string, unknown>): void;
 }
 
+interface TdEvent {
+    event: string;
+    data?: unknown;
+}
+type TdEventHandler = (event: TdEvent) => void;
+
 interface OperatorParameter {
     name: string;
     label?: string;
@@ -201,6 +207,38 @@ declare class KnowledgeBase {
     stats(): KnowledgeStats;
 }
 
+interface ParsedNote {
+    /** Parsed YAML frontmatter (empty object when the note has none). */
+    data: Record<string, unknown>;
+    /** Markdown body with the frontmatter stripped. */
+    body: string;
+}
+
+/**
+ * A thin, safe wrapper over an Obsidian vault (a folder of markdown files on the
+ * local filesystem). Every path is resolved relative to the vault root and is
+ * refused if it escapes that root, so user-supplied note names cannot reach
+ * outside the vault.
+ */
+declare class Vault {
+    readonly root: string;
+    private readonly logger;
+    constructor(root: string, logger?: Logger);
+    /** Resolves a vault-relative path, throwing if it would escape the vault root. */
+    resolve(relPath: string): string;
+    exists(relPath: string): boolean;
+    read(relPath: string): string;
+    write(relPath: string, content: string): void;
+    writeBinary(relPath: string, data: Buffer): void;
+    ensureDir(relPath: string): void;
+    /** Lists file names directly inside `subdir`, optionally filtered by extension. */
+    list(subdir: string, ext?: string): string[];
+    /** Reads a markdown note and splits its frontmatter from its body. */
+    readNote(relPath: string): ParsedNote;
+    /** Writes a markdown note from frontmatter data + body. */
+    writeNote(relPath: string, data: Record<string, unknown>, body: string): void;
+}
+
 declare const RecipeSchema: z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
@@ -284,11 +322,14 @@ interface RecipeSummary {
 interface RecipeLibraryOptions {
     dir?: string;
     logger?: Logger;
+    /** Optional Obsidian vault; recipes in `<vault>/Recipes/*.md` are merged in (and override built-ins by id). */
+    vault?: Vault;
 }
-/** Loads and validates recipe JSON files from the recipes directory. */
+/** Loads and validates recipe JSON files from the recipes directory, plus any vault recipes. */
 declare class RecipeLibrary {
     private readonly dir;
     private readonly logger;
+    private readonly vault?;
     private cache?;
     constructor(options?: RecipeLibraryOptions);
     private load;
@@ -338,6 +379,16 @@ interface TouchDesignerClientOptions {
     token?: string;
     /** Overridable for tests (defaults to global `fetch`). */
     fetchImpl?: typeof fetch;
+    /**
+     * Extra attempts for a transient connection failure on an **idempotent** (GET)
+     * request — e.g. TD briefly stalls mid-build. Default 2 (so up to 3 tries).
+     * Only `TdConnectionError` is retried; timeouts and bridge errors are not (a
+     * timeout may mean the request was received, and non-GET methods aren't safe
+     * to repeat). Set 0 to disable.
+     */
+    retries?: number;
+    /** Base backoff between retries, in ms (linear: delay × attempt). Default 150. */
+    retryDelayMs?: number;
 }
 /**
  * HTTP client for the TouchDesigner REST bridge. Every method maps to one of the
@@ -350,9 +401,12 @@ declare class TouchDesignerClient {
     private readonly logger;
     private readonly token;
     private readonly fetchImpl;
+    private readonly retries;
+    private readonly retryDelayMs;
     constructor(options: TouchDesignerClientOptions);
     get endpoint(): string;
     private request;
+    private attemptRequest;
     getInfo(): Promise<{
         td_version?: string | undefined;
         python_version?: string | undefined;
@@ -468,6 +522,8 @@ interface ToolContext {
     knowledge: KnowledgeBase;
     recipes: RecipeLibrary;
     logger: Logger;
+    /** Optional Obsidian vault (set via TDMCP_VAULT_PATH); undefined when not configured. */
+    vault?: Vault;
     /**
      * Whether the raw Python escape-hatch tools may be registered. Undefined means
      * allowed (the default); only an explicit `false` locks them out.
@@ -475,6 +531,39 @@ interface ToolContext {
     allowRawPython?: boolean;
 }
 
+declare const ConfigSchema: z.ZodObject<{
+    tdHost: z.ZodDefault<z.ZodString>;
+    tdPort: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    transport: z.ZodDefault<z.ZodEnum<{
+        stdio: "stdio";
+        http: "http";
+    }>>;
+    logLevel: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+        silent: "silent";
+    }>>;
+    requestTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    httpPort: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    events: z.ZodDefault<z.ZodEnum<{
+        on: "on";
+        off: "off";
+    }>>;
+    rawPython: z.ZodDefault<z.ZodEnum<{
+        on: "on";
+        off: "off";
+    }>>;
+    bridgeToken: z.ZodOptional<z.ZodString>;
+    llmBaseUrl: z.ZodDefault<z.ZodString>;
+    llmModel: z.ZodDefault<z.ZodString>;
+    llmApiKey: z.ZodOptional<z.ZodString>;
+    chatPort: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    vaultPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type TdmcpConfig = z.infer<typeof ConfigSchema>;
+
 interface CliResult {
     stdout: string;
     stderr: string;
@@ -485,5 +574,29 @@ interface RunCliOptions {
     makeCtx?: () => ToolContext;
 }
 declare function runCli(argv: string[], opts?: RunCliOptions): Promise<CliResult>;
+interface RunWatchOptions {
+    config?: TdmcpConfig;
+    includeHighFrequency?: boolean;
+    /** Where each event line goes; defaults to stdout. Overridable for tests. */
+    write?: (line: string) => void;
+    /** Inject a stream factory for tests; defaults to a real `TdEventStream`. */
+    makeStream?: (args: {
+        url: string;
+        onEvent: TdEventHandler;
+        includeHighFrequency: boolean;
+    }) => {
+        start: () => void;
+        close: () => void;
+    };
+    /** Resolve the returned promise when aborted; defaults to listening for SIGINT. */
+    signal?: AbortSignal;
+}
+/**
+ * Streams TouchDesigner bridge events to stdout as ndjson until interrupted.
+ * Runs outside `runCli` because it is a long-lived stream, not a request/response.
+ */
+declare function runWatch(opts?: RunWatchOptions): Promise<void>;
+/** Interactive read-eval-print loop: each line is tokenized and run through runCli. */
+declare function runRepl(opts?: RunCliOptions): Promise<void>;
 
-export { type CliResult, type RunCliOptions, runCli };
+export { type CliResult, type RunCliOptions, type RunWatchOptions, runCli, runRepl, runWatch };