# Tdmcp Bridge Endpoint

> Build a tdmcp TouchDesigner-bridge vertical slice the house way — promote an op from /api/exec to a first-class REST endpoint (e.g. POST /api/connect, GET /api/logs, node_detail flags), add its typed method in src/td-client/touchDesignerClient.ts, its Zod envelope in src/td-client/validators.ts, rewire the tool(s) to prefer the endpoint with an exec fallback, and write py_compile + td/tests unitt…

- **Type:** Skill
- **Install:** `agentstack add skill-hybridlabor-api-bdb-dev-optimized-agent-skills-tdmcp-bridge-endpoint`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [hybridlabor-api](https://agentstack.voostack.com/s/hybridlabor-api)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [hybridlabor-api](https://github.com/hybridlabor-api)
- **Source:** https://github.com/hybridlabor-api/bdb-dev-optimized-agent-skills/tree/main/mcps/tdmcp/.claude/skills/tdmcp-bridge-endpoint

## Install

```sh
agentstack add skill-hybridlabor-api-bdb-dev-optimized-agent-skills-tdmcp-bridge-endpoint
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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/**/.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.

### 3. Validator (`src/td-client/validators.ts`)
- Add a Zod schema for the response envelope and `.parse()` it in the client —
  never hand a raw wire object upward. Reuse the shared envelope helpers already in
  the file.

### 4. Rewire the tool(s)
- Point `connect_nodes`/`disconnect_nodes`/`read_parameter_modes`/
  `set_parameter_expression`/`edit_dat_content`/`set_dat_content`/`get_bridge_logs`/
  the `node_detail` consumers at the new method. **Preserve current behavior and
  output exactly** — this is a transport swap, not a redesign. Keep fail-forward:
  validate inputs with Zod, turn TD failures into friendly `isError` via
  `errorResult`/`friendlyTdError`; never throw out of a handler.

## Probe-live discipline (when TD is offline)

Attribute names that vary by TD build are the trap: connector semantics for
connect/disconnect, `ParMode`/`.expr`/`.mode` names for param-modes, Error DAT
column layout for logs, optype enumeration for createable. The backlog flags these
`probe-live`.

- **TD reachable** (`get_td_info` ok): probe the real names in a scratch network
  first (create a couple of ops, read the actual attrs), *then* lock the schema.
- **TD offline:** implement against the best-known names from the knowledge base
  (`tdmcp://operators/...`, `tdmcp://classes/...`) and TD's documented Python API;
  write the offline tests; and **flag every probe-dependent assumption
  `UNVERIFIED-live`** in your report (with the source you used). Do not claim a live
  pass you could not observe. The campaign-lead holds `UNVERIFIED-live` items for a
  live pass before the final release.

## Tests (offline — no TD)

- **Bridge unittest** `td/tests/test_.py`: import the handler, call it with a
  faked `op()`/payload, assert the report shape and the error branch. At minimum
  `py_compile`. Run `python3 -m unittest discover -s td/tests`.
- **Client msw test** `tests/unit/*`: stub the route; assert (a) success → validated
  shape, (b) 4xx/5xx → correct `TdError` subclass, (c) timeout → `TdTimeoutError`,
  (d) **404 → exec-fallback path** returns the same shape. Mirror the closest
  existing client test.

## Gates (all green before reporting)

`npm run typecheck` · `npm run build` · `./node_modules/.bin/biome check .` (NOT
`npm run lint`) · `npm test` · `npm run test:bridge`. Fix forward; never disable a
gate or use `--no-verify`.

## Report back

Endpoint(s) added + method + validator; tool(s) rewired; the exec-fallback
behavior; every `UNVERIFIED-live` assumption with its source; gate results; and the
ledger fields to set (`files[]`, `status`). On a re-run, treat feedback as a diff —
don't rewrite a green slice.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [hybridlabor-api](https://github.com/hybridlabor-api)
- **Source:** [hybridlabor-api/bdb-dev-optimized-agent-skills](https://github.com/hybridlabor-api/bdb-dev-optimized-agent-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-hybridlabor-api-bdb-dev-optimized-agent-skills-tdmcp-bridge-endpoint
- Seller: https://agentstack.voostack.com/s/hybridlabor-api
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.