{"id":49534554,"url":"https://github.com/dreamrec/tdpilot","last_synced_at":"2026-05-02T09:06:11.405Z","repository":{"id":353581875,"uuid":"1166081641","full_name":"dreamrec/TDPilot","owner":"dreamrec","description":"AI copilot for TouchDesigner — 101 MCP tools for live node graph control, parameter management, diagnostics, knowledge corpus, technique memory, and typed patch sessions. Claude Code plugin marketplace install.","archived":false,"fork":false,"pushed_at":"2026-05-02T06:22:55.000Z","size":3628,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-02T07:08:55.769Z","etag":null,"topics":["ai","audio-reactive","claude","claude-code","creative-coding","generative-art","live-coding","mcp","model-context-protocol","particles","simulations","touchdesigner","visual-programming"],"latest_commit_sha":null,"homepage":"https://github.com/dreamrec/TDPilot/releases/latest","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dreamrec.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-24T21:25:00.000Z","updated_at":"2026-05-01T17:00:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dreamrec/TDPilot","commit_stats":null,"previous_names":["dreamrec/tdpilot"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/dreamrec/TDPilot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dreamrec%2FTDPilot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dreamrec%2FTDPilot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dreamrec%2FTDPilot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dreamrec%2FTDPilot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dreamrec","download_url":"https://codeload.github.com/dreamrec/TDPilot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dreamrec%2FTDPilot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32528669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T01:12:54.858Z","status":"online","status_checked_at":"2026-05-02T02:00:05.923Z","response_time":132,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","audio-reactive","claude","claude-code","creative-coding","generative-art","live-coding","mcp","model-context-protocol","particles","simulations","touchdesigner","visual-programming"],"created_at":"2026-05-02T09:06:10.579Z","updated_at":"2026-05-02T09:06:11.398Z","avatar_url":"https://github.com/dreamrec.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"```\n████████╗██████╗ ██████╗ ██╗██╗      ██████╗ ████████╗\n╚══██╔══╝██╔══██╗██╔══██╗██║██║     ██╔═══██╗╚══██╔══╝\n   ██║   ██║  ██║██████╔╝██║██║     ██║   ██║   ██║\n   ██║   ██║  ██║██╔═══╝ ██║██║     ██║   ██║   ██║\n   ██║   ██████╔╝██║     ██║███████╗╚██████╔╝   ██║\n   ╚═╝   ╚═════╝ ╚═╝     ╚═╝╚══════╝ ╚═════╝    ╚═╝\n```\n\n# TDPilot Runtime v1.5.6\n\n[![CI](https://github.com/dreamrec/TDPilot/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/dreamrec/TDPilot/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/tdpilot?label=npm)](https://www.npmjs.com/package/tdpilot)\n[![downloads](https://img.shields.io/npm/dm/tdpilot?label=downloads)](https://www.npmjs.com/package/tdpilot)\n[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)\n[![python](https://img.shields.io/badge/python-3.10%2B-blue)](./pyproject.toml)\n[![MCP tools](https://img.shields.io/badge/MCP%20tools-101-blueviolet)](./docs/API_REFERENCE.md)\n[![TouchDesigner](https://img.shields.io/badge/TouchDesigner-2025.30000%2B-ff6200)](https://derivative.ca)\n\n**TDPilot Runtime** is an MCP server for TouchDesigner.\nIt lets an AI agent inspect, build, wire, optimize, and stabilize live TD networks with real tool calls — and now remember what works.\n\n`#tdpilot` `#touchdesigner` `#mcp` `#livepatch` `#audioreactive` `#realtime`\n\n## Install — Claude Code plugin (recommended)\n\n**Easiest:** paste these two slash commands into any Claude Code session.\n\n```\n/plugin marketplace add dreamrec/TDPilot\n/plugin install tdpilot@dreamrec-TDPilot\n```\n\nThat installs all **101 MCP tools**, 3 skills (`tdpilot-core`, `tdpilot-production`, `popx-touchdesigner`), 2 slash commands (`/td-check`, `/td-snapshot`), and the TD-side `.tox` component — one command, no Python setup required.\n\n**Shell one-liner alternative:**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/dreamrec/TDPilot/main/scripts/install_claude_plugin.sh | bash\n```\n\n**Or via npx:**\n\n```bash\nnpx tdpilot plugin-install\n```\n\n### TouchDesigner side (once, after install)\n\nDrag `~/.claude/plugins/cache/dreamrec-TDPilot/tdpilot/\u003cversion\u003e/td_component/tdpilot.tox` into your TD `/local` container. Or paste the auto-setup Python block from [`docs/INSTALL_CLAUDE_PLUGIN.md`](docs/INSTALL_CLAUDE_PLUGIN.md) into the Textport (auto-detects the latest installed version).\n\nUsing Claude Desktop instead of Claude Code? See [`docs/INSTALL_CLAUDE_PLUGIN.md`](docs/INSTALL_CLAUDE_PLUGIN.md) — the two flows shouldn't be mixed on one machine.\n\n## Documentation\n\n- Install (Claude Code plugin): `docs/INSTALL_CLAUDE_PLUGIN.md`\n- Getting started: `docs/GETTING_STARTED.md`\n- User guide: `docs/USER_GUIDE.md`\n- Memory guide: `docs/MEMORY_GUIDE.md`\n- Production manual: `docs/MANUAL.md`\n- API reference: `docs/API_REFERENCE.md`\n- Security model: `docs/SECURITY.md`\n- Troubleshooting: `docs/TROUBLESHOOTING.md`\n- MCP 1.1 surface: `docs/MCP_1_1_SURFACE.md`\n- Release notes: `CHANGELOG.md`\n\n## What This Is\n\n- A practical control layer between AI agents and TouchDesigner.\n- A structured toolset for scene edits, diagnostics, event monitoring, and recovery.\n- A workflow-oriented MCP built for iterative patch development, not one-shot guessing.\n- A technique memory system that learns from your projects and builds a reusable library.\n- 101-tool runtime surface with knowledge corpus, vision diagnostics, TD 2025 native inspection, official recommendations, job resources, memory, optimizer, safety, POPx inspection, project lifecycle control, custom parameter authoring, and typed patch sessions.\n\n## Start Here: Core Workflow\n\nYou don't need all 101 tools. Start with these and expand as needed:\n\n| Step | Tools | What You're Doing |\n|------|-------|-------------------|\n| **Inspect** | `td_get_info`, `td_get_nodes`, `td_get_params`, `td_get_errors` | Understand current state before touching anything |\n| **Check memory** | `td_memory_recall` | See if a reusable technique already exists |\n| **Build** | `td_create_node`, `td_connect_nodes`, `td_set_params` | Make changes in small, reversible steps |\n| **Verify** | `td_get_errors`, `td_cooking_info`, `td_screenshot` | Prove the change worked |\n| **Protect** | `td_snapshot_scene`, `td_restore_snapshot` | Save milestones, roll back if needed |\n| **Remember** | `td_memory_learn`, `td_memory_save` | Save successful patterns for reuse |\n\n**The loop:** Inspect -\u003e Build -\u003e Verify -\u003e Snapshot -\u003e Repeat.\n\nEverything else (vision, streaming, optimization, planning, TD2025 inspection) builds on top of this core.\n\n## What's New In 1.5.6\n\nOne-button installer release. The shipped `tdpilot.tox` is now a self-installing component with an Install panel + Update panel inside the .tox itself. Drag the `.tox` into any TD project, click **\"Bootstrap All\"**, and the installer clones the repo into `~/.tdpilot/`, runs `uv sync`, registers the Claude plugin (or skips gracefully if `claude` CLI is missing), writes the TD prefs to autoload TDPilot on next launch, and saves the autoload `.toe`. No Textport, no shell scripts, no manual `.tox` drag into `/local`.\n\n- **Install panel** (custom params on the parent COMP) — `Detect State`, `Bootstrap All`, individual `Install Python Wrapper / Register Claude Plugin / Set TD Autoload`, `Uninstall Everything`, plus `Repo URL` / `Pin to latest tag` / `Disable MCP auth` configuration toggles. Live progress streams into the on-screen status panel as each stage runs.\n- **Update panel** — `Check for Updates Now` (24h-cached GitHub Releases query via `curl` for system-trust-store TLS; falls back gracefully when offline), `Update Now` (smart backup that excludes `.venv`/`knowledge`/`memory`/`*.db` → `git fetch --tags \u0026\u0026 checkout \u003clatest\u003e` → `uv sync` → re-save autoload `.toe`), `Rollback to Previous Backup` (newest-first restore with aside-swap-on-failure safety), `Auto-check on project load` toggle.\n- **Threading model** — long ops run on a daemon thread sharing one lock-protected job state. The bg thread never touches TD ops directly; instead it requests main-thread actions like `project.save()` via a `pending_action` flag that `autostart.onFrameStart` consumes on the next cook tick. Solves TD's \"ops aren't thread-safe outside the cook thread\" rule cleanly.\n- **`.mcpb`-aware plugin detection** — `install_claude_plugin` recognizes both `tdpilot@dreamrec-TDPilot` (Claude Code CLI marketplace) and `tdpilot@local-desktop-app-uploads` (Claude Desktop drag-drop) registration keys, so users who already have the plugin via either flow get a clean \"already installed\" path without needing the `claude` CLI on PATH.\n- **`build_tdpilot_tox.py`** — new container-COMP builder that constructs the parent `tdpilot` COMP with custom param pages, four installer DATs (`installer`/`installer_exec`/`autostart`/`renderer`), the status_text TOP (Courier New 14pt panel), and the nested `mcp_server` sub-COMP via the legacy `_populate_component`. Reuses the proven legacy helpers — the v1.5.6 `.tox` inherits every MCP-server fix the legacy script accumulated.\n- Tool count unchanged at 101 (the installer is COMP-side Python, not new MCP tools). `API_VERSION` stays at `1.5.3` (HTTP protocol unchanged). `.tox` rebuilt with the four new source files tracked by CI's freshness gate.\n\n## What's New In 1.5.3\n\nKnowledge corpus + MCP source-fix release. Adds a parallel surface to technique memory for **prose-with-math reference essays** (vs. replayable network recipes), plus 3 source-side bug fixes surfaced during real-world TD verification on TD 2025.32460.\n\n- **Knowledge store** — 4 new tools (`td_knowledge_save` / `recall` / `get` / `list`) backed by a `KnowledgeStore` class that persists free-form markdown reference essays at `~/.tdpilot/knowledge/{global,projects/\u003cname\u003e}/`. Body cap 200 KB per entry, stored as plain `.md` files for direct user editing. Project-scope auto-derives from `TDPILOT_PROJECT_NAME`.\n- **Silent-null guard expanded to plural OP-reference styles** (`OPS/COMPS/TOPS/CHOPS/SOPS/DATS/MATS/POPS/POPXS/OPLIST`). `renderTOP.cameras/lights/geometry`, attribute-COMP `COMPs`, and similar list-style references no longer silently null on string assignment.\n- **`td_get_node_detail` parameter truncation** — caps at `param_limit` (default 50, ceiling 200) with `parameters_truncated` / `parameters_total` / `parameters_returned` / `parameters_hint` metadata. Heavy COMPs no longer return 80 KB+ JSON.\n- **Better POPx-not-installed message** — `td_search_popx_docs` now returns an actionable `npx tdpilot brains add popx` install command plus the local-docs fallback path.\n- **`tdpilot-core` SKILL §11 \"Render Pipeline Pitfalls\"** — new section documenting the `geometryCOMP`-defaults-to-POP-`torus1` trap, OP-ref-not-string requirement for reference params, `viewer=True` discipline for test/debug COMPs, and the verified-against-Derivative `feedbackTOP` canonical wiring.\n- Tool count: 97 → 101. `API_VERSION` 1.5.2 → 1.5.3 (`.tox` rebuild auto-detected on next TD launch).\n\n## What's New In 1.5.0 – 1.5.2\n\nSee [CHANGELOG.md](CHANGELOG.md) for full details. Highlights:\n- **v1.5.2** — auth-bootstrap ordering bug fixed (the silent 401 on marketplace installs); install scripts now auto-pin to release tags; npm tag-push auto-publish workflow.\n- **v1.5.1** — wire-format alignment for all 6 patch op kinds (`set_params`, `connect`, `layout`, `annotate`, `macro`, `create_node`); plugin-ZIP runtime missing fix; 13-scenario live-TD smoke at `scripts/patch_session_smoke.py`.\n- **v1.5.0** — typed patch-session API (`td_plan_patch`, `td_preflight_patch`, `td_patch_apply`, `td_patch_validate`, `td_patch_variations`); module split into `registry/tools_*.py` themed submodules.\n\n## What's New In 1.4.2\n\nFollow-up bugfix release from the v1.4.1 ultra-debug sweep (N1–N7):\n\n- **Component/server version sync** — `API_VERSION` bumped in `td_component/mcp_webserver_callbacks.py`; `td_get_capabilities` no longer emits `mismatch: true` after a fresh `.tox` rebuild.\n- **`td_build` auto-detect fallback** — new `_ensure_td_build` helper lazily fetches the build from live TD when MCP server outlived a TD restart. Fixes `td_get_release_delta` and `td_get_build_compatibility` without explicit `build=`.\n- **`unstable` agreement** — `td_detect_instability` and `td_get_state_vector.health` now use a shared heuristic and always return matching values.\n- **`td_geometry_data` prim verts** — `getattr(prim, 'numVertices', 0)` → `len(prim)`. Box SOP quads correctly report 4 verts each.\n- **`td_memory_preferences` project scope** — derives project name from TD's `info.project_name` when `TDPILOT_PROJECT_NAME` env var is unset.\n- **`td_validate_recipe` stock allowlist** — honors the v1.4.1 `_STOCK_OP_TYPES` fix so recipes using `base`, `constant`, `feedback`, `null`, etc. don't flag as unknown.\n\n## What's New In 1.4.1\n\nUltra-debug sweep — B1–B9 + restricted-mode + CI guardrails:\n\n- **`td_describe_surface` real counts** — was returning `tool_count: 0, resource_count: 0` due to bad FastMCP attribute access. Now uses `_tool_manager.list_tools()` + `_resource_manager.list_resources()`.\n- **`td_copy_node` offset** — copies are placed +150 px off the original so they don't stack exactly.\n- **`td_get_content` table empty-check** — uses `node.isTable` instead of `numRows \u003e 0`, so empty Table DATs return `[]` instead of erroring.\n- **`td_project_lifecycle end_undo_block`** — idempotent; TD's cascading auto-close no longer errors.\n- **Personal path leak check** — `scripts/check_no_personal_paths.sh` prevents committing `/Users/\u003cname\u003e/` or `C:\\Users\\\u003cname\u003e\\` paths via CI + optional pre-commit hook.\n\n## What's New In 1.4.0\n\n- **Vision diagnostics** — `td_capture_frame` and `td_analyze_frame` for MCP-side and TD-side pixel analysis (histogram, luminance, alpha, dominant color, ROI diff).\n- **TD 2025 native tools** — 6 tools for Python env, threading, logger, TDResources, COMP standardization, and color pipeline inspection.\n- **Official recommendations** — `td_recommend_official_component`, `td_find_official_example`, `td_explain_better_way` search the knowledge corpus for safer official approaches.\n- **Enhanced recipe capture** — Recipes now include `td_build`, `required_op_types`, `external_assets`, and `layout` for portability validation.\n- **Pre-replay checks** — `td_memory_replay` blocks replay when required operator types are missing from the target TD install.\n\n## What's New In 1.3.0\n\n- **Knowledge corpus** — Structured JSON cards for 30 operators, 6 palette components, release notes. Query with `td_search_official_docs`, `td_get_operator_doc`, `td_get_param_help`, and more.\n- **`standard` exec safety** — New middle-tier mode between `restricted` and `full`. Allows 14 safe data-transform imports (json, math, re, datetime, etc.) while blocking system access.\n- **Expanded capabilities** — CapabilitySet now reports MCP Tasks support, transport type, SDK version, and TD build number.\n- **Resource read-through** — Cached resources now attempt a live TD API call on cache miss instead of returning empty.\n- **`td_describe_surface`** — Single tool to inspect the full MCP surface: tool count, resource count, capabilities, version.\n\n## What's New In 1.1\n\n- `td_pop_inspect` adds first-class POP metadata and attribute sampling instead of forcing POP debugging through SOP-shaped geometry reads.\n- `td_project_lifecycle` adds save/load/undo/redo and undo-block control without falling back to ad hoc Python snippets.\n- `td_custom_parameters` adds direct custom page/parameter authoring for COMPs.\n- `td_exec_python` now returns structured result payloads when possible instead of forcing everything through `str(...)`.\n\n## Core Thinking Model (How To Think With This MCP)\n\nUse this loop for every non-trivial task:\n\n1. **Inspect first** — Read current state before touching anything. Start with `td_get_info`, `td_get_nodes`, `td_get_node_detail`, `td_get_params`.\n\n2. **Check memory** — Before building from scratch, use `td_memory_recall` to check if a similar technique already exists in the library.\n\n3. **Build in small steps** — Create or modify one chunk at a time. Prefer: create -\u003e wire -\u003e set params -\u003e verify.\n\n4. **Learn and save** — When you discover a reusable network pattern, use `td_memory_learn` to extract the recipe and `td_memory_save` to persist it.\n\n5. **Validate at the end** — Always run `td_get_errors` on the affected root. Report warnings/errors and fix before marking done.\n\n6. **Control token cost** — Prefer metadata checks over continuous image payloads. Ask the user before enabling high-token frame streaming.\n\n## Tool Map (101 Tools)\n\n### 1) Scene + Timeline + Project Lifecycle\nUse for global context, playback control, save/load, and undo operations.\n\n- `td_get_info`, `td_list_families`, `td_timeline`, `td_timeline_set`, `td_project_lifecycle`\n\n### 2) Network Build + Wiring\nUse for creating, moving, renaming, connecting, and pruning structure.\n\n- `td_get_nodes`, `td_get_node_detail`, `td_search_nodes`\n- `td_create_node`, `td_delete_node`, `td_copy_node`, `td_rename_node`\n- `td_connect_nodes`, `td_disconnect`, `td_get_connections`\n\n### 3) Parameters + DAT Content\nUse for patch logic, expressions, config tables, scripts, and trigger pulses.\n\n- `td_get_params`, `td_set_params`, `td_pulse_param`\n- `td_get_content`, `td_set_content`, `td_custom_parameters`\n\n### 4) Diagnostics + Capture\nUse for proving behavior instead of assuming behavior.\n\n- `td_screenshot`, `td_chop_data`, `td_geometry_data`, `td_pop_inspect`\n- `td_cooking_info`, `td_get_errors`\n- `td_exec_python`, `td_python_help`, `td_python_classes`\n\nStructured exec note: `td_exec_python` now returns JSON-safe `result`, `result_type`, and `result_is_structured` fields. Use it for lightweight structured probes before reaching for stdout parsing.\n\n### 5) Events + Streaming\nUse for reactive and continuous workflows.\n\n- `td_subscribe`, `td_unsubscribe`, `td_get_events`\n- `td_capture_and_analyze`\n- `td_monitor_visual`, `td_stop_monitor_visual`\n- `td_stream_top`, `td_stop_stream_top`\n\nToken guidance: start with `include_image=false` for monitors/streams. Use image payloads only when visual detail is explicitly required. Prefer `td_screenshot` for single checks.\n\n### 6) Optimization + Dynamics\nUse for quality passes and temporal behavior analysis.\n\n- `td_optimize_visual` — now accepts direct `objective_weights` (e.g. `{\"stability\": 0.8, \"complexity\": 0.2}`)\n- `td_describe_dynamics`\n\n### 7) Safety + Recovery\nUse for guardrails, emergency control, and rollback confidence.\n\n- `td_set_param_bounds`, `td_clear_param_bounds`\n- `td_detect_instability`, `td_emergency_stabilize`\n- `td_snapshot_scene`, `td_list_snapshots`, `td_diff_snapshots`, `td_restore_snapshot`\n- `td_get_state_vector`, `td_get_timescale_state`\n\n### 8) Technique Memory \u0026 User Knowledge Store\nTwo parallel persistence surfaces — **technique memory** for replayable network recipes, **knowledge store** (new in v1.5.3) for free-form markdown reference essays (prose + math).\n\n**Technique memory** — learning, saving, and replaying reusable network patterns:\n\n- `td_memory_learn` — Analyze a live network subtree and extract a portable recipe. Auto-detects complexity: small/medium networks get full recipes with all params and expressions; large networks get structure summaries + key params.\n- `td_memory_save` — Persist a technique to the project or global library.\n- `td_memory_recall` — Search the library by text query and/or tags. Returns summaries.\n- `td_memory_replay` — Rebuild a saved technique in a new location. Creates nodes, sets parameters and expressions, wires connections.\n- `td_memory_list` — List all saved techniques with optional filtering.\n- `td_memory_favorite` — Mark techniques as favorites and rate them (0-5).\n- `td_memory_promote` — Copy a project-level technique to the global library for use across all projects.\n- `td_memory_export` — Export the technique library as a portable JSON object for sharing or backup.\n- `td_memory_import` — Import techniques from an exported library (from `td_memory_export`).\n- `td_memory_preferences` — Get/set user preferences (color palettes, default resolutions, naming conventions, etc.)\n\n**User knowledge store** *(new in v1.5.3)* — free-form markdown reference essays for prose-with-math reference content (BZ reaction equations, feedback recipes, \"why this approach works\" essays):\n\n- `td_knowledge_save` — Persist a markdown body with name/description/tags/source/notes. Project- or global-scoped. Body capped at 200 KB; split larger writeups into linked entries.\n- `td_knowledge_recall` — Search by free-text query and/or tags across name/description/tags/source/notes. Optional `full_text=true` also reads bodies (slower but more thorough).\n- `td_knowledge_get` — Fetch full markdown body + metadata for one entry by id.\n- `td_knowledge_list` — List entry summaries newest-first with optional filtering.\n\nStorage lives at `~/.tdpilot/{memory,knowledge}/` with per-project and global scopes:\n```\n~/.tdpilot/\n  memory/\n    global/\n      techniques.json\n      preferences.json\n    projects/{project_name}/\n      techniques.json\n      preferences.json\n  knowledge/\n    global/\n      index.json\n      entries/\u003cuuid\u003e.md\n    projects/{project_name}/\n      index.json\n      entries/\u003cuuid\u003e.md\n```\n\n### 9. Macros \u0026 Planning (7)\n| Tool | Purpose |\n|------|---------|\n| `td_create_macro` | Create a reusable macro from a template |\n| `td_list_macros` | List available macros |\n| `td_get_macro_params` | Get macro parameter schema |\n| `td_plan_patch` | Plan a multi-step network patch |\n| `td_preflight_patch` | Pre-validate a patch plan |\n| `td_validate_recipe` | Validate a technique recipe |\n| `td_audit_project` | Audit project subtree |\n\n### 10. Vision \u0026 Streaming (7)\n| Tool | Purpose |\n|------|---------|\n| `td_capture_frame` | Capture a single frame from a TOP |\n| `td_analyze_frame` | Analyze frame content (colors, regions) |\n| `td_monitor_visual` | Start continuous visual monitoring |\n| `td_stop_monitor_visual` | Stop visual monitoring |\n| `td_stream_top` | Stream TOP output via WebSocket |\n| `td_stop_stream_top` | Stop TOP streaming |\n| `td_optimize_visual` | Get optimization suggestions for visuals |\n\n### 11. Knowledge Corpus (7)\n| Tool | Purpose |\n|------|---------|\n| `td_search_official_docs` | Search official TD documentation |\n| `td_get_operator_doc` | Get detailed operator documentation |\n| `td_get_param_help` | Get parameter-level help |\n| `td_lookup_snippets` | Find code snippets by topic |\n| `td_lookup_palette_component` | Look up Palette component info |\n| `td_get_release_delta` | Get changes between TD builds |\n| `td_get_build_compatibility` | Check operator build compatibility |\n\n### 12. Server Introspection (3)\n| Tool | Purpose |\n|------|---------|\n| `td_get_capabilities` | Report server capabilities |\n| `td_get_server_metrics` | Get server performance metrics |\n| `td_describe_surface` | Describe the full tool surface |\n\n### 13. Recommendations (3)\n| Tool | Purpose |\n|------|---------|\n| `td_recommend_official_component` | Suggest official components |\n| `td_find_official_example` | Find relevant official examples |\n| `td_explain_better_way` | Suggest better approaches |\n\n### 14. TD 2025 Native (6)\n| Tool | Purpose |\n|------|---------|\n| `td_python_env_status` | Inspect Python environment in TD |\n| `td_threading_status` | Check threading configuration |\n| `td_logger_status` | Inspect TD logger state |\n| `td_tdresources_inspect` | Inspect TDResources categories |\n| `td_component_standardize` | Audit/fix COMP standards |\n| `td_color_pipeline` | Inspect color management pipeline |\n\n## How To Use It (Practical Workflow)\n\n1. Connect MCP client to TDPilot.\n2. Ask for current project state.\n3. Request a scoped patch goal.\n4. Let agent apply changes in batches.\n5. Require end-of-task `td_get_errors` check.\n6. Save snapshot at stable milestone.\n7. When you find something worth keeping: learn it, save it, rate it.\n\n## What It Is Good At\n\n- Building and refactoring operator networks quickly.\n- Inspecting modern POP systems with attribute-aware reads.\n- Converting high-level creative goals into concrete TD graph operations.\n- Audio-reactive/control-system patch scaffolding.\n- Automated cleanup, relayout, and consistency passes.\n- Diagnosing wiring/parameter/runtime errors with direct evidence.\n- Remembering what works and reusing it across projects.\n\n## What It Is Not Good At\n\n- Replacing artistic direction by itself.\n- High-level show design without iterative user feedback.\n- Unlimited always-on image streaming without token impact.\n- Ignoring TD-specific context (operator families, cook behavior, timing model).\n- \"One shot perfect patch\" generation in complex scenes.\n\n## Network Design Protocol (Default Aesthetic Rules)\n\nWhen generating or reorganizing networks: use color coding by role, keep clean spacing and avoid overlaps, group nodes into functional clusters, preserve clear flow direction, name nodes by purpose, and run `td_get_errors` after edits.\n\n## Quick Setup\n\nRecommended runtime (no manual Python setup in client config):\n\n```bash\nnpx -y tdpilot\n```\n\nLocal development runtime:\n\n```bash\ngit clone https://github.com/dreamrec/TDPilot.git\ncd TDPilot\nuv sync\nuv run tdpilot\n```\n\n### TouchDesigner Side\n\nRun the setup script once inside the TD Textport:\n\n```python\nexec(open(\"/path/to/TDPilot/setup_mcp_in_td.py\").read(), globals(), globals())\n```\n\nThis installs the MCP component into `/local/mcp_server` by default, which means it **persists across project opens** within the same TD session. You only need to run this once — every project you open afterward will already have TDPilot available.\n\nTo install into a specific project instead: `os.environ[\"TD_MCP_PARENT_PATH\"] = \"/project1\"` before running.\n\nAlternatively, drag-and-drop `td_component/tdpilot.tox` into `/local` manually.\n\nOne-command setup helpers: macOS `./install.sh`, Windows `./install.ps1`\n\n## MCP Bundle (Standardized)\n\nTDPilot ships a standard bundle in-repo:\n\n- `mcp/manifest.json`\n- `mcp/profiles/claude-desktop.json`, `cursor.json`, `generic.json`\n\nAuto-generate client config:\n\n```bash\ntdpilot init --client claude-desktop\ntdpilot init --client cursor --output ./cursor_mcp_config.json\ntdpilot init --client generic --print-only\n```\n\n## Doctor Command\n\nRun a final environment/runtime check:\n\n```bash\ntdpilot doctor\ntdpilot doctor --json\n```\n\n## Environment Variables\n\n- `TD_MCP_HOST` (default `127.0.0.1` — supports hostnames like `desktop-3lurf0p.tail88651a.ts.net`)\n- `TD_MCP_PORT` (default `9981`)\n- `TD_MCP_SCHEME` (default `http` — set to `https` for Tailscale HTTPS or TLS-enabled setups)\n- `TD_MCP_WS_PORT` (default `9982`)\n- `TD_MCP_TRANSPORT` (`stdio` or `streamable_http`)\n- `TD_MCP_HTTP_PORT` (default `8765`)\n- `TD_MCP_CAPTURE_QUALITY` (default `0.3`)\n- `TD_MCP_STREAM_MAX_FPS` (default `15.0`)\n- `TD_MCP_EXEC_MODE` (`off`, `restricted`, `standard`, `full`)\n- `TDPILOT_PROJECT_NAME` (set to enable per-project technique memory)\n- `TDPILOT_MEMORY_DIR` (override default `~/.tdpilot/memory/` path)\n\n## Test Suite\n\nRun the test suite:\n\n```bash\nuv run --extra dev pytest tests/ -v\n```\n\n## Reliability Habit\n\nTreat this as mandatory for every meaningful task: before edits inspect, during edits take small reversible steps, after edits run `td_get_errors`, before risky changes snapshot.\n\n## License\n\nMIT\n\n```\n┌─────────────────────────────────────────────────────────────────────┐\n│ dreamrec // TDPilot // live laugh love                             │\n└─────────────────────────────────────────────────────────────────────┘\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdreamrec%2Ftdpilot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdreamrec%2Ftdpilot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdreamrec%2Ftdpilot/lists"}