From 968efb0d24a31c2ab5554af68723f67197d60df6 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Tue, 21 Jul 2026 05:49:05 -0700 Subject: [PATCH] feat(mcp): add touchdesigner (twozero) to the MCP catalog Adds optional-mcps/touchdesigner: HTTP transport to the twozero plugin's localhost hub (127.0.0.1:40404/mcp), no auth, no install block. Curates tools.default_enabled to the 25 creative tools; the 7 desktop input-automation tools and 4 admin/dev tools (including td_test_session, which exports transcripts to the vendor hub) are off by default and enableable via 'hermes mcp configure touchdesigner'. Updates the touchdesigner-mcp skill to install via the catalog instead of hand-writing a twozero_td block into config.yaml: SKILL.md setup section, setup.sh (now calls 'hermes mcp install touchdesigner' and warns about the legacy twozero_td key), troubleshooting config example, regenerated docs page. Skill version 1.1.0 -> 1.2.0. --- optional-mcps/touchdesigner/manifest.yaml | 97 +++++++++++++++++++ skills/creative/touchdesigner-mcp/SKILL.md | 32 ++++-- .../references/troubleshooting.md | 13 ++- .../touchdesigner-mcp/scripts/setup.sh | 43 ++++---- .../creative/creative-touchdesigner-mcp.md | 32 ++++-- 5 files changed, 167 insertions(+), 50 deletions(-) create mode 100644 optional-mcps/touchdesigner/manifest.yaml diff --git a/optional-mcps/touchdesigner/manifest.yaml b/optional-mcps/touchdesigner/manifest.yaml new file mode 100644 index 00000000000..41297dabad9 --- /dev/null +++ b/optional-mcps/touchdesigner/manifest.yaml @@ -0,0 +1,97 @@ +# Nous-approved MCP catalog entry. +# Presence in this directory = approval. Merged via PR review. +manifest_version: 1 + +name: touchdesigner +description: Drive a live TouchDesigner session via the twozero plugin. +source: https://github.com/404dotzero/twozero-td-mcp + +# 404.zero's twozero plugin (free, no license/payment) embeds an MCP server +# inside the running TouchDesigner process and serves it over local +# Streamable HTTP. There is nothing to install on the Hermes side — the user +# drops twozero.tox into TD and enables the MCP toggle; the hub binds to +# 127.0.0.1:40404. Hermes's MCP client just connects to the URL. +# +# Multi-instance TD is handled by the hub automatically: keep ONE url here +# (the hub port) — do not add per-instance entries. The default port is +# controlled by the twozero setting "MCP default port"; if you change it, +# edit the url in mcp_servers.touchdesigner to match. +transport: + type: http + url: http://127.0.0.1:40404/mcp + +# The plugin-embedded hub accepts connections only from the same machine and +# has no authentication of its own. Nothing to prompt for. +auth: + type: none + +# Tool selection at install time: +# The server advertises 36 tools. The 25 below are the complete creative +# surface — building networks, setting parameters, reading/writing DATs and +# CHOPs, operator screenshots, search, errors, and performance. The 11 left +# off by default fall in two clusters, both enableable any time with +# `hermes mcp configure touchdesigner`: +# - Desktop input automation (td_input_execute/status/clear, +# td_op_screen_rect, td_click_screen_point, td_screen_point_to_global, +# td_get_screen_screenshot): synthesizes real mouse/keyboard events and +# captures the user's actual screen. Powerful but invasive — opt-in. +# - Admin/dev (td_project_quit, td_test_session, td_dev_log, +# td_clear_dev_log): can save-and-close the user's project, and +# td_test_session exports conversation transcripts / submits bug reports +# to the vendor's hub — off by default per the no-outbound-telemetry +# posture. The dev logs only function in the plugin's Devmode. +tools: + default_enabled: + - td_execute_python + - td_create_operator + - td_set_operator_pars + - td_get_operator_info + - td_get_operators_info + - td_get_par_info + - td_get_network + - td_get_focus + - td_get_errors + - td_get_hints + - td_read_dat + - td_write_dat + - td_read_chop + - td_read_textport + - td_clear_textport + - td_get_screenshot + - td_get_screenshots + - td_navigate_to + - td_find_op + - td_search + - td_get_perf + - td_list_instances + - td_get_docs + - td_agents_md + - td_reinit_extension + +post_install: | + This entry connects to the twozero plugin's MCP server, which runs INSIDE + TouchDesigner (2025.32280+). One-time setup in TD: + + 1. Download https://www.404zero.com/pisang/twozero.tox + 2. Drag twozero.tox into the TD network editor and click Install. + 3. Enable MCP: twozero icon > Settings > mcp > "auto start MCP" > Yes. + The hub binds to http://127.0.0.1:40404/mcp. + + TouchDesigner must be RUNNING with twozero's MCP enabled before the tools + work — start TD first, then your Hermes session. Quick health check: + curl -s http://127.0.0.1:40404/mcp (returns hub JSON with instances) + + SECURITY: td_execute_python runs arbitrary Python inside TouchDesigner with + no sandbox — same trust level as the terminal tool. The server is + localhost-only and unauthenticated (any local process can reach it). + + The desktop input-automation tools (mouse/keyboard control, full-screen + capture) and admin tools (project quit, vendor bug-report/chat export) are + off by default. Enable them with: hermes mcp configure touchdesigner + + If you previously configured this server manually under the key + `twozero_td` (the old skill setup script), remove that entry from + mcp_servers in config.yaml to avoid loading the server twice. + + The bundled `touchdesigner-mcp` skill covers workflows, pitfalls, and + proven recipes (audio-reactive GLSL, recording, instancing). diff --git a/skills/creative/touchdesigner-mcp/SKILL.md b/skills/creative/touchdesigner-mcp/SKILL.md index 745e9ac838e..57d09858d47 100644 --- a/skills/creative/touchdesigner-mcp/SKILL.md +++ b/skills/creative/touchdesigner-mcp/SKILL.md @@ -1,7 +1,7 @@ --- name: touchdesigner-mcp description: "Control a running TouchDesigner instance via twozero MCP — create operators, set parameters, wire connections, execute Python, build real-time visuals. 36 native tools." -version: 1.1.0 +version: 1.2.0 author: kshitijk4poor license: MIT platforms: [linux, macos, windows] @@ -32,21 +32,29 @@ Hermes Agent -> MCP (Streamable HTTP) -> twozero.tox (port 40404) -> TD Python Context-aware (knows selected OP, current network). Hub health check: `GET http://localhost:40404/mcp` returns JSON with instance PID, project name, TD version. -## Setup (Automated) +## Setup -Run the setup script to handle everything: +The server is in the Nous MCP catalog. Install it with: + +```bash +hermes mcp install touchdesigner +``` + +This writes the `mcp_servers.touchdesigner` entry (`http://127.0.0.1:40404/mcp`) +and applies the curated default tool selection: the 25 creative tools are on; +the 11 desktop input-automation tools (`td_input_*`, `td_op_screen_rect`, +`td_click_screen_point`, `td_screen_point_to_global`, `td_get_screen_screenshot`) +and admin tools (`td_project_quit`, `td_test_session`, `td_dev_log`, +`td_clear_dev_log`) are OFF by default. Enable them when needed with +`hermes mcp configure touchdesigner`. + +The optional helper script checks TD, downloads twozero.tox, and health-checks +the port: ```bash bash "${HERMES_HOME:-$HOME/.hermes}/skills/creative/touchdesigner-mcp/scripts/setup.sh" ``` -The script will: -1. Check if TD is running -2. Download twozero.tox if not already cached -3. Add `twozero_td` MCP server to Hermes config (if missing) -4. Test the MCP connection on port 40404 -5. Report what manual steps remain (drag .tox into TD, enable MCP toggle) - ### Manual steps (one-time, cannot be automated) 1. **Drag `~/Downloads/twozero.tox` into the TD network editor** → click Install @@ -58,6 +66,10 @@ After setup, verify: nc -z 127.0.0.1 40404 && echo "twozero MCP: READY" ``` +> Migrating from the old manual setup: earlier versions of this skill wrote a +> `twozero_td` entry into `mcp_servers` directly. If you have one, remove it +> from `~/.hermes/config.yaml` so the server isn't loaded twice under two names. + ## Environment Notes - **Non-Commercial TD** caps resolution at 1280×1280. Use `outputresolution = 'custom'` and set width/height explicitly. diff --git a/skills/creative/touchdesigner-mcp/references/troubleshooting.md b/skills/creative/touchdesigner-mcp/references/troubleshooting.md index b8e201f5c32..da1bcc0555e 100644 --- a/skills/creative/touchdesigner-mcp/references/troubleshooting.md +++ b/skills/creative/touchdesigner-mcp/references/troubleshooting.md @@ -141,12 +141,17 @@ actual = str(n.width) + 'x' + str(n.height) ### MCP entry format -The twozero TD entry should look like: +The catalog install (`hermes mcp install touchdesigner`) writes: ```yaml -mcpServers: - twozero_td: - url: http://localhost:40404/mcp +mcp_servers: + touchdesigner: + url: http://127.0.0.1:40404/mcp + enabled: true + tools: + include: [...] # curated default — 25 creative tools ``` +If you find an old `twozero_td` entry (written by earlier versions of this +skill's setup script), remove it — the catalog entry replaces it. ### After config changes diff --git a/skills/creative/touchdesigner-mcp/scripts/setup.sh b/skills/creative/touchdesigner-mcp/scripts/setup.sh index 15dc662c1cd..b82d57f98cf 100644 --- a/skills/creative/touchdesigner-mcp/scripts/setup.sh +++ b/skills/creative/touchdesigner-mcp/scripts/setup.sh @@ -43,36 +43,27 @@ else fi fi -# ── 3. Ensure Hermes config has twozero_td MCP entry ── +# ── 3. Ensure the touchdesigner MCP catalog entry is installed ── if [[ ! -f "$HERMES_CFG" ]]; then echo -e " ${FAIL} Hermes config not found at ${HERMES_CFG}" - manual_steps+=("Create ${HERMES_CFG} with twozero_td MCP server entry") -elif grep -q 'twozero_td' "$HERMES_CFG" 2>/dev/null; then - echo -e " ${OK} twozero_td MCP entry exists in Hermes config" + manual_steps+=("Run 'hermes setup' first, then 'hermes mcp install touchdesigner'") +elif grep -qE '^\s+touchdesigner:' "$HERMES_CFG" 2>/dev/null; then + echo -e " ${OK} touchdesigner MCP entry exists in Hermes config" else - echo -e " ${WARN} Adding twozero_td MCP entry to Hermes config..." - python3 -c " -import yaml, sys, copy + echo -e " ${WARN} Installing touchdesigner from the MCP catalog..." + if command -v hermes >/dev/null 2>&1 && hermes mcp install touchdesigner /dev/null && echo -e " ${OK} twozero_td MCP entry added to config" \ - || { echo -e " ${FAIL} Could not update config (is PyYAML installed?)"; \ - manual_steps+=("Add twozero_td MCP entry to ${HERMES_CFG} manually"); } - manual_steps+=("Restart Hermes session to pick up config change") +# ── 3b. Warn about a stale legacy entry from the old manual setup ── +if [[ -f "$HERMES_CFG" ]] && grep -q 'twozero_td' "$HERMES_CFG" 2>/dev/null; then + echo -e " ${WARN} Legacy 'twozero_td' entry found in config" + manual_steps+=("Remove the old 'twozero_td' entry from mcp_servers in ${HERMES_CFG} (replaced by the catalog's 'touchdesigner' entry)") fi # ── 4. Test if MCP port is responding ── diff --git a/website/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md b/website/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md index 9a14bceffd9..0d6fb70b0dd 100644 --- a/website/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md +++ b/website/docs/user-guide/skills/bundled/creative/creative-touchdesigner-mcp.md @@ -16,7 +16,7 @@ Control a running TouchDesigner instance via twozero MCP — create operators, s |---|---| | Source | Bundled (installed by default) | | Path | `skills/creative/touchdesigner-mcp` | -| Version | `1.1.0` | +| Version | `1.2.0` | | Author | kshitijk4poor | | License | MIT | | Platforms | linux, macos, windows | @@ -49,21 +49,29 @@ Hermes Agent -> MCP (Streamable HTTP) -> twozero.tox (port 40404) -> TD Python Context-aware (knows selected OP, current network). Hub health check: `GET http://localhost:40404/mcp` returns JSON with instance PID, project name, TD version. -## Setup (Automated) +## Setup -Run the setup script to handle everything: +The server is in the Nous MCP catalog. Install it with: + +```bash +hermes mcp install touchdesigner +``` + +This writes the `mcp_servers.touchdesigner` entry (`http://127.0.0.1:40404/mcp`) +and applies the curated default tool selection: the 25 creative tools are on; +the 11 desktop input-automation tools (`td_input_*`, `td_op_screen_rect`, +`td_click_screen_point`, `td_screen_point_to_global`, `td_get_screen_screenshot`) +and admin tools (`td_project_quit`, `td_test_session`, `td_dev_log`, +`td_clear_dev_log`) are OFF by default. Enable them when needed with +`hermes mcp configure touchdesigner`. + +The optional helper script checks TD, downloads twozero.tox, and health-checks +the port: ```bash bash "${HERMES_HOME:-$HOME/.hermes}/skills/creative/touchdesigner-mcp/scripts/setup.sh" ``` -The script will: -1. Check if TD is running -2. Download twozero.tox if not already cached -3. Add `twozero_td` MCP server to Hermes config (if missing) -4. Test the MCP connection on port 40404 -5. Report what manual steps remain (drag .tox into TD, enable MCP toggle) - ### Manual steps (one-time, cannot be automated) 1. **Drag `~/Downloads/twozero.tox` into the TD network editor** → click Install @@ -75,6 +83,10 @@ After setup, verify: nc -z 127.0.0.1 40404 && echo "twozero MCP: READY" ``` +> Migrating from the old manual setup: earlier versions of this skill wrote a +> `twozero_td` entry into `mcp_servers` directly. If you have one, remove it +> from `~/.hermes/config.yaml` so the server isn't loaded twice under two names. + ## Environment Notes - **Non-Commercial TD** caps resolution at 1280×1280. Use `outputresolution = 'custom'` and set width/height explicitly.