tdmcp-bridge-endpoint

tdmcp-bridge-endpoint — the bridge vertical slice

A bridge feature is correct only when four layers agree on one shape: the Python route, the TS client method, the Zod validator, and the tool that consumes it. This skill is that contract. Build the slice top-to-bottom, keep an exec fallback so it ships safely before every bridge in the wild updates, and prove it all offline.

Run bridge slices one at a time — they share touchDesignerClient.ts, validators.ts, and the bridge route registry. Two in parallel is merge hell.

Why exec→REST at all

The bridge runs arbitrary Python on /api/exec. A security-conscious VJ runs TDMCP_BRIDGE_ALLOW_EXEC=0 on a venue network — and ~69 tools silently die. Promoting a well-defined op (connect, param-mode read/write, DAT text, node flags, logs) to its own REST route makes it survive that hardened config. You are promoting proven logic, not inventing it — start from the Python the tool already sends through /api/exec.

The slice, in order

1. Bridge (Python, td/)

• Add a handler module (or extend the right existing one) and register the route. Find how routes are registered (the request dispatcher in td/) and follow that exact pattern — don't invent a second mechanism.
• Keep every TD-global (op, app, project, ui) inside the handler function so the module imports cleanly outside TD (the tests rely on this).
• Return a JSON report with a stable shape: a top-level ok/error and the data. Mirror the envelope the existing endpoints return so parsePythonReport/the validators stay uniform.
• Honor TDMCP_BRIDGE_TOKEN (bearer auth) and the ALLOW_EXEC gate exactly as sibling routes do — a new route must not become an auth bypass.
• python3 -m py_compile td/**/<changed>.py on every changed file.

2. Client method (src/td-client/touchDesignerClient.ts)

• Add one typed method that calls the new route (GET/POST/PATCH/PUT as fits).
• Map failures to the existing typed errors: TdApiError (4xx/5xx with a body), TdConnectionError (refused/DNS), TdTimeoutError. Never let a raw fetch error escape.
• Exec fallback: if the endpoint returns 404 (older bridge without the route), fall back to the previous /api/exec Python path. This is what lets the promotion ship before the bridge is reinstalled everywhere. Make the fallback a private helper so the test can force both paths.