touchdesigner-agent-mcp: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code working in the touchdesigner-agent-mcp repository.

What this is

A pure-Python MCP server that drives TouchDesigner. Two halves:

• Host (src/td_agent_mcp/) — the MCP server (FastMCP). Runs wherever the MCP client runs. Defines tools/prompts and an async HTTP client to TD.
• TouchDesigner side (td/) — plain Python loaded by a Web Server DAT inside TouchDesigner. Executes the actual operator calls.

They speak one JSON contract: POST /mcp {op, params} → {ok, data, error}. There is no codegen (no OpenAPI/orval/mustache/Docker) — that is the point.

Layout

src/td_agent_mcp/
  cli.py          entry point (--stdio default, --http)
  server.py       build_server(): FastMCP + register every tool module + prompts
  client.py       TDClient: async httpx wrapper, {ok,data,error}, TDError
  config.py       env/CLI settings (TD_HOST/TD_PORT/TD_TIMEOUT)
  formatting.py   ResponseFormat + json/markdown rendering (shared)
  prompts.py      3 MCP prompts
  tools/          one module per group; each exposes register(mcp, client)
td/
  webserver.py    Web Server DAT callbacks (onHTTPRequest/Start/Stop)
  router.py       op-name -> handler table; {ok,data,error} envelope
  ops.py          base operations (node CRUD, python exec, introspection)
  forkops.py      extended ops (pane, cook, viewport, connect, layout, glsl, scaffold)
  tdapi.py        TD helper library (docked-aware create/move, layout, cook)
  install.py      builds the Web Server DAT component inside TD

Commands

uv sync                       # deps + dev tools (uv, not pip)
uv run touchdesigner-agent-mcp --help
uv run pytest                 # registration tests (no TouchDesigner needed)
uv run ruff check . && uv run ruff format .
python -m py_compile td/*.py  # syntax-check the TD-side modules

There is no test runner that touches a live TouchDesigner — the td/ modules import TD builtins (td, op, ui, operator-type constants) that only exist inside TouchDesigner. Verify host-side logic with pytest; syntax-check td/ with py_compile; integration must be done with TouchDesigner running.