mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-07-31 19:16:29 +00:00
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.
This commit is contained in:
Teknium
parent
ab76cf836f
commit
968efb0d24
5 changed files with 167 additions and 50 deletions
97
optional-mcps/touchdesigner/manifest.yaml
Normal file
97
optional-mcps/touchdesigner/manifest.yaml
Normal file
|
|
@ -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).
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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; then
|
||||
echo -e " ${OK} touchdesigner MCP installed via catalog"
|
||||
else
|
||||
echo -e " ${FAIL} Could not run 'hermes mcp install touchdesigner'"
|
||||
manual_steps+=("Run: hermes mcp install touchdesigner")
|
||||
fi
|
||||
manual_steps+=("Restart Hermes session to pick up the new MCP server")
|
||||
fi
|
||||
|
||||
cfg_path = '$HERMES_CFG'
|
||||
with open(cfg_path, 'r') as f:
|
||||
cfg = yaml.safe_load(f) or {}
|
||||
|
||||
if 'mcp_servers' not in cfg:
|
||||
cfg['mcp_servers'] = {}
|
||||
|
||||
if 'twozero_td' not in cfg['mcp_servers']:
|
||||
cfg['mcp_servers']['twozero_td'] = {
|
||||
'url': '${MCP_ENDPOINT}',
|
||||
'timeout': 120,
|
||||
'connect_timeout': 60
|
||||
}
|
||||
with open(cfg_path, 'w') as f:
|
||||
yaml.dump(cfg, f, default_flow_style=False, sort_keys=False)
|
||||
" 2>/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 ──
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue