dcc-mcp-touchdesigner 0.1.0__tar.gz

dcc_mcp_touchdesigner-0.1.0/.github/scripts/start_mcp_server.py

@@ -0,0 +1,42 @@
+"""CI script — start the TouchDesigner MCP server for smoke testing.
+
+This script CANNOT run in CI without a running TouchDesigner process.
+It serves as a reference for manual smoke testing.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+
+def main() -> int:
+    """Start dcc-mcp-touchdesigner and print the MCP URL as JSON."""
+    try:
+        import dcc_mcp_touchdesigner
+    except ImportError:
+        print(json.dumps({"error": "dcc_mcp_touchdesigner not installed"}))
+        return 1
+
+    try:
+        server = dcc_mcp_touchdesigner.start_server(port=0)
+        server.discover_skills()
+        print(
+            json.dumps(
+                {
+                    "status": "running",
+                    "mcp_url": server.mcp_url,
+                    "port": server.port,
+                    "version": dcc_mcp_touchdesigner.__version__,
+                    "skills_discovered": server.loaded_skill_count(),
+                }
+            )
+        )
+        return 0
+    except Exception as exc:
+        print(json.dumps({"error": str(exc)}))
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dcc_mcp_touchdesigner-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.12"]
+
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: python -m pip install -e ".[dev]" build twine
+      - name: Install dcc-mcp-cli
+        env:
+          DCC_MCP_CLI_VERSION: 0.20.2
+          DCC_MCP_CLI_SHA256: 1168ebe901cfc0526d3d0f363d18ac4f8e21d2bcc874557e5813acbee8480f9c
+        run: |
+          curl --fail --location --retry 3 \
+            --output /tmp/dcc-mcp-cli \
+            "https://github.com/dcc-mcp/dcc-mcp-core/releases/download/v${DCC_MCP_CLI_VERSION}/dcc-mcp-cli-linux-x86_64"
+          echo "${DCC_MCP_CLI_SHA256}  /tmp/dcc-mcp-cli" | sha256sum --check
+          chmod +x /tmp/dcc-mcp-cli
+          sudo install /tmp/dcc-mcp-cli /usr/local/bin/dcc-mcp-cli
+      - name: Lint
+        run: |
+          ruff check src tests packaging .github/scripts
+          ruff format --check src tests packaging .github/scripts
+      - name: Validate packaged Skill
+        run: dcc-mcp-cli lint --warnings-as-errors src/dcc_mcp_touchdesigner/skills/touchdesigner-scripting
+      - name: Test
+        run: pytest
+      - name: Build
+        if: matrix.python-version == '3.12'
+        run: |
+          python -m build
+          twine check dist/*
+          python -m venv wheel-smoke
+          wheel-smoke/bin/python -m pip install dist/*.whl
+          wheel-smoke/bin/python -c "import importlib.resources as r; root = r.files('dcc_mcp_touchdesigner'); assert root.joinpath('skills', 'touchdesigner-scripting', 'tools.yaml').is_file()"

dcc_mcp_touchdesigner-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,68 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      tag_name:
+        description: Existing tag to rebuild and publish
+        required: false
+        default: ""
+      publish_to_pypi:
+        description: Publish a manually rebuilt tag to PyPI
+        type: boolean
+        required: false
+        default: false
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    if: github.ref == 'refs/heads/main'
+    permissions:
+      contents: write
+      pull-requests: write
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name || inputs.tag_name }}
+    steps:
+      - uses: googleapis/release-please-action@0dfd8538845b8e92600d271a895a5372865d4062 # v5
+        id: release
+        with:
+          token: ${{ github.token }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  build-and-publish:
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true' || (github.event_name == 'workflow_dispatch' && inputs.tag_name != '' && inputs.publish_to_pypi)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment:
+      name: pypi
+      url: https://pypi.org/p/dcc-mcp-touchdesigner
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          ref: ${{ needs.release-please.outputs.tag_name || inputs.tag_name }}
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          verbose: true
+          print-hash: true

dcc_mcp_touchdesigner-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# Virtual envs
+venv/
+.venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project
+*.toe.hold

dcc_mcp_touchdesigner-0.1.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}

dcc_mcp_touchdesigner-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 (2026-08-12)
+
+
+### Features
+
+* initial TouchDesigner MCP adapter ([b1df6a7](https://github.com/dcc-mcp/dcc-mcp-touchdesigner/commit/b1df6a70605bc0066ff55a21602de67f662b3d58))
+* ship production-ready TouchDesigner workflows ([#3](https://github.com/dcc-mcp/dcc-mcp-touchdesigner/issues/3)) ([973eef9](https://github.com/dcc-mcp/dcc-mcp-touchdesigner/commit/973eef9b1ee8c6c076b3c66fa4d03771f25cfc04))
+
+
+### Bug Fixes
+
+* start TouchDesigner UI dispatcher lifecycle ([614f59f](https://github.com/dcc-mcp/dcc-mcp-touchdesigner/commit/614f59fced955f7088a6530755cf55263ced8a05))
+
+## Changelog
+
+All notable changes are generated from Conventional Commits by Release Please.

dcc_mcp_touchdesigner-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.5
+Name: dcc-mcp-touchdesigner
+Version: 0.1.0
+Summary: TouchDesigner integration for the DCC Model Context Protocol (MCP) ecosystem — embeds a Streamable HTTP MCP server directly inside TouchDesigner
+Project-URL: Homepage, https://github.com/dcc-mcp/dcc-mcp-touchdesigner
+Project-URL: Repository, https://github.com/dcc-mcp/dcc-mcp-touchdesigner
+Project-URL: Issues, https://github.com/dcc-mcp/dcc-mcp-touchdesigner/issues
+Author-email: Long Hao <hal.long@outlook.com>
+License: MIT
+Keywords: ai,dcc,llm,mcp,model-context-protocol,touchdesigner
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: dcc-mcp-core<1.0.0,>=0.19.91
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=5.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: twine<7.0,>=6.2; (python_version < '3.10') and extra == 'dev'
+Requires-Dist: twine>=7.0; (python_version >= '3.10') and extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dcc-mcp-touchdesigner
+
+<p align="center">
+  <img src="docs/assets/dcc-mcp-touchdesigner.svg" alt="DCC-MCP · TouchDesigner" width="600">
+</p>
+
+Typed, main-thread-safe TouchDesigner control for the [DCC Model Context Protocol](https://github.com/dcc-mcp/dcc-mcp-core).
+
+The adapter embeds the DCC-MCP HTTP runtime in TouchDesigner, registers the instance with the local gateway, and executes TouchDesigner API work through the documented `td.run()` scheduler. Agents can inspect and edit operator networks, set parameters, save projects, and export TOP images without sending TouchDesigner objects to background threads.
+
+![Typed request flows through a main-thread operator graph into a verified visual, project, and PNG artifact](docs/images/touchdesigner-scripting-showcase.webp)
+
+_Illustrative workflow visualization generated with OpenAI ImageGen from the retained source in `docs/images/sources`. It is not a TouchDesigner screenshot or host-validation artifact. The header uses an approved operator-network reference motif rather than an official host mark._
+
+## Install
+
+TouchDesigner 2025 uses Python 3.11. Install this package into a matching external environment and expose that environment to TouchDesigner. The preferred TouchDesigner 2025 route is the built-in `TDPyEnvManager`; the Preferences dialog's external Python module path is also supported.
+
+```powershell
+py -3.11 -m venv .venv
+.\.venv\Scripts\python -m pip install --upgrade pip
+.\.venv\Scripts\python -m pip install dcc-mcp-touchdesigner
+```
+
+See [install.md](install.md) for the complete Windows and macOS setup, dependency isolation guidance, and startup configuration. TouchDesigner documents both [external Python packages](https://docs.derivative.ca/Python#Installing_Custom_Python_Packages) and the [TDPyEnvManager](https://docs.derivative.ca/Palette%3AtdPyEnvManager).
+
+## Start in TouchDesigner
+
+Run this from the Textport or an Execute DAT `onStart()` callback:
+
+```python
+import dcc_mcp_touchdesigner
+
+server = dcc_mcp_touchdesigner.start_server()
+print(server.mcp_url)
+```
+
+`start_server()` is idempotent inside one TouchDesigner process. It loads the bundled skill by default, selects an OS-assigned loopback port, starts the main-thread pump, and advertises the instance to a running DCC-MCP gateway. Stop it explicitly during project teardown when needed:
+
+```python
+dcc_mcp_touchdesigner.stop_server()
+```
+
+## Typed tools
+
+| Tool | Contract | Risk |
+| --- | --- | --- |
+| `get_project_info` | Read project name, folder, build, cook rate, and root count | Read-only |
+| `list_operators` | List direct or recursive operators with an optional family/type filter | Read-only |
+| `get_op_parameters` | Read selected or all parameters from one operator | Read-only |
+| `create_operator` | Create a documented operator type under an explicit COMP | Mutation |
+| `connect_operators` | Connect an explicit output connector to an explicit input | Mutation |
+| `set_op_parameter` | Set one parameter and return its evaluated value | Idempotent mutation |
+| `capture_top` | Save one TOP to an explicit PNG path with size and SHA-256 metadata | File write |
+| `save_project` | Save the current project to an explicit `.toe` path | File write |
+| `delete_operator` | Delete one explicitly addressed non-root operator | Destructive |
+| `execute_python` | Advanced in-host Python escape hatch; disabled by policy when required | Destructive |
+
+Every tool has a JSON input/output contract and is dispatched on TouchDesigner's main thread. File-writing tools require an explicit path and reject accidental overwrite unless `overwrite=true` is supplied. Root deletion is always rejected.
+
+## Security controls
+
+Disable arbitrary Python execution in controlled environments before starting TouchDesigner:
+
+```powershell
+$env:DCC_MCP_TOUCHDESIGNER_DISABLE_EXECUTE_PYTHON = "1"
+```
+
+The adapter binds to loopback by default. Do not expose the per-instance port directly to an untrusted network. Use the DCC-MCP gateway when multiple instances or attributable agent sessions are required.
+
+## Runtime configuration
+
+| Variable | Purpose |
+| --- | --- |
+| `DCC_MCP_TOUCHDESIGNER_SKILL_PATHS` | Additional skill directories |
+| `DCC_MCP_TOUCHDESIGNER_METRICS` | Enable Prometheus `/metrics` |
+| `DCC_MCP_TOUCHDESIGNER_ENABLE_GATEWAY_FAILOVER` | Enable gateway failover; on by default |
+| `DCC_MCP_TOUCHDESIGNER_DISABLE_EXECUTE_PYTHON` | Disable the advanced Python tool |
+
+## Development
+
+```powershell
+py -3.11 -m pip install -e ".[dev]"
+pytest
+ruff check .
+ruff format --check .
+dcc-mcp-cli lint src/dcc_mcp_touchdesigner/skills/touchdesigner-scripting --warnings-as-errors
+python -m build
+python -m twine check dist/*
+```
+
+Unit and contract tests use a deterministic TouchDesigner API double. A release additionally requires a real TouchDesigner process, six readiness checks, discovery of all ten typed tools, and a create/connect/set/capture/save/delete chain through `dcc-mcp-cli`; simulation alone is not release evidence.
+
+## License
+
+MIT

dcc_mcp_touchdesigner-0.1.0/README.md

@@ -0,0 +1,96 @@
+# dcc-mcp-touchdesigner
+
+<p align="center">
+  <img src="docs/assets/dcc-mcp-touchdesigner.svg" alt="DCC-MCP · TouchDesigner" width="600">
+</p>
+
+Typed, main-thread-safe TouchDesigner control for the [DCC Model Context Protocol](https://github.com/dcc-mcp/dcc-mcp-core).
+
+The adapter embeds the DCC-MCP HTTP runtime in TouchDesigner, registers the instance with the local gateway, and executes TouchDesigner API work through the documented `td.run()` scheduler. Agents can inspect and edit operator networks, set parameters, save projects, and export TOP images without sending TouchDesigner objects to background threads.
+
+![Typed request flows through a main-thread operator graph into a verified visual, project, and PNG artifact](docs/images/touchdesigner-scripting-showcase.webp)
+
+_Illustrative workflow visualization generated with OpenAI ImageGen from the retained source in `docs/images/sources`. It is not a TouchDesigner screenshot or host-validation artifact. The header uses an approved operator-network reference motif rather than an official host mark._
+
+## Install
+
+TouchDesigner 2025 uses Python 3.11. Install this package into a matching external environment and expose that environment to TouchDesigner. The preferred TouchDesigner 2025 route is the built-in `TDPyEnvManager`; the Preferences dialog's external Python module path is also supported.
+
+```powershell
+py -3.11 -m venv .venv
+.\.venv\Scripts\python -m pip install --upgrade pip
+.\.venv\Scripts\python -m pip install dcc-mcp-touchdesigner
+```
+
+See [install.md](install.md) for the complete Windows and macOS setup, dependency isolation guidance, and startup configuration. TouchDesigner documents both [external Python packages](https://docs.derivative.ca/Python#Installing_Custom_Python_Packages) and the [TDPyEnvManager](https://docs.derivative.ca/Palette%3AtdPyEnvManager).
+
+## Start in TouchDesigner
+
+Run this from the Textport or an Execute DAT `onStart()` callback:
+
+```python
+import dcc_mcp_touchdesigner
+
+server = dcc_mcp_touchdesigner.start_server()
+print(server.mcp_url)
+```
+
+`start_server()` is idempotent inside one TouchDesigner process. It loads the bundled skill by default, selects an OS-assigned loopback port, starts the main-thread pump, and advertises the instance to a running DCC-MCP gateway. Stop it explicitly during project teardown when needed:
+
+```python
+dcc_mcp_touchdesigner.stop_server()
+```
+
+## Typed tools
+
+| Tool | Contract | Risk |
+| --- | --- | --- |
+| `get_project_info` | Read project name, folder, build, cook rate, and root count | Read-only |
+| `list_operators` | List direct or recursive operators with an optional family/type filter | Read-only |
+| `get_op_parameters` | Read selected or all parameters from one operator | Read-only |
+| `create_operator` | Create a documented operator type under an explicit COMP | Mutation |
+| `connect_operators` | Connect an explicit output connector to an explicit input | Mutation |
+| `set_op_parameter` | Set one parameter and return its evaluated value | Idempotent mutation |
+| `capture_top` | Save one TOP to an explicit PNG path with size and SHA-256 metadata | File write |
+| `save_project` | Save the current project to an explicit `.toe` path | File write |
+| `delete_operator` | Delete one explicitly addressed non-root operator | Destructive |
+| `execute_python` | Advanced in-host Python escape hatch; disabled by policy when required | Destructive |
+
+Every tool has a JSON input/output contract and is dispatched on TouchDesigner's main thread. File-writing tools require an explicit path and reject accidental overwrite unless `overwrite=true` is supplied. Root deletion is always rejected.
+
+## Security controls
+
+Disable arbitrary Python execution in controlled environments before starting TouchDesigner:
+
+```powershell
+$env:DCC_MCP_TOUCHDESIGNER_DISABLE_EXECUTE_PYTHON = "1"
+```
+
+The adapter binds to loopback by default. Do not expose the per-instance port directly to an untrusted network. Use the DCC-MCP gateway when multiple instances or attributable agent sessions are required.
+
+## Runtime configuration
+
+| Variable | Purpose |
+| --- | --- |
+| `DCC_MCP_TOUCHDESIGNER_SKILL_PATHS` | Additional skill directories |
+| `DCC_MCP_TOUCHDESIGNER_METRICS` | Enable Prometheus `/metrics` |
+| `DCC_MCP_TOUCHDESIGNER_ENABLE_GATEWAY_FAILOVER` | Enable gateway failover; on by default |
+| `DCC_MCP_TOUCHDESIGNER_DISABLE_EXECUTE_PYTHON` | Disable the advanced Python tool |
+
+## Development
+
+```powershell
+py -3.11 -m pip install -e ".[dev]"
+pytest
+ruff check .
+ruff format --check .
+dcc-mcp-cli lint src/dcc_mcp_touchdesigner/skills/touchdesigner-scripting --warnings-as-errors
+python -m build
+python -m twine check dist/*
+```
+
+Unit and contract tests use a deterministic TouchDesigner API double. A release additionally requires a real TouchDesigner process, six readiness checks, discovery of all ten typed tools, and a create/connect/set/capture/save/delete chain through `dcc-mcp-cli`; simulation alone is not release evidence.
+
+## License
+
+MIT

dcc_mcp_touchdesigner-0.1.0/install.md

@@ -0,0 +1,123 @@
+# Installing dcc-mcp-touchdesigner
+
+## Requirements
+
+- TouchDesigner 2025 official build
+- A Python environment matching TouchDesigner's embedded Python version
+- `dcc-mcp-touchdesigner` and its `dcc-mcp-core` dependency installed into that environment
+
+TouchDesigner 2025 currently embeds Python 3.11. Confirm the exact interpreter from the Textport before creating an environment:
+
+```python
+app.pythonExecutable
+import sys
+
+sys.version
+```
+
+Do not mix an environment built for a different Python minor version. Avoid overriding TouchDesigner's bundled NumPy or OpenCV unless the project explicitly owns and tests those versions.
+
+## Preferred: TDPyEnvManager
+
+TouchDesigner 2025 includes `TDPyEnvManager` in the Palette. It creates a project-local Python environment, adds it to TouchDesigner's import path, and can restore requirements at startup.
+
+1. Add `TDPyEnvManager` from the Palette to the project.
+2. Select Python vEnv mode and create a `.venv` beside the `.toe` project.
+3. Open that environment's CLI from the component.
+4. Install the adapter:
+
+   ```text
+   python -m pip install --upgrade pip
+   python -m pip install dcc-mcp-touchdesigner
+   ```
+
+5. Restart TouchDesigner so its Python search path is rebuilt.
+
+For a reproducible project, add this line to the project's `requirements.txt` and let the component restore it:
+
+```text
+dcc-mcp-touchdesigner==0.1.0
+```
+
+See Derivative's [TDPyEnvManager documentation](https://docs.derivative.ca/Palette%3AtdPyEnvManager) for `pyproject.toml`, `autoSetup`, and environment lifecycle options.
+
+## Alternative: external Python 3.11 environment
+
+Create a normal Python 3.11 virtual environment outside TouchDesigner:
+
+```powershell
+py -3.11 -m venv .venv
+.\.venv\Scripts\python -m pip install --upgrade pip
+.\.venv\Scripts\python -m pip install dcc-mcp-touchdesigner
+```
+
+In TouchDesigner, open **Edit > Preferences > Python**:
+
+1. Enable **Add Externally Installed Python Site-Packages to Search Path**.
+2. Set **Python 64-bit Module Path** to the environment's `Lib\site-packages` directory on Windows, or `lib/python3.11/site-packages` on macOS.
+3. Restart TouchDesigner.
+
+Derivative documents this path in [Installing Custom Python Packages](https://docs.derivative.ca/Python#Installing_Custom_Python_Packages).
+
+## Verify imports
+
+Open the Textport and run:
+
+```python
+import dcc_mcp_core
+import dcc_mcp_touchdesigner
+
+print(dcc_mcp_touchdesigner.__version__)
+```
+
+The `td` module is only available inside TouchDesigner. A normal terminal can validate package installation, but it cannot validate host dispatch or typed tool execution.
+
+## Start and stop with the project
+
+For manual testing:
+
+```python
+import dcc_mcp_touchdesigner
+
+server = dcc_mcp_touchdesigner.start_server()
+print(server.mcp_url)
+```
+
+For persistent startup, place the same call in an Execute DAT `onStart()` callback. Pair it with `stop_server()` in `onExit()`:
+
+```python
+def onStart():
+    import dcc_mcp_touchdesigner
+
+    dcc_mcp_touchdesigner.start_server()
+    return
+
+
+def onExit():
+    import dcc_mcp_touchdesigner
+
+    dcc_mcp_touchdesigner.stop_server()
+    return
+```
+
+The server uses an OS-assigned loopback port and registers itself when a DCC-MCP gateway is available. Do not hard-code a port unless an isolated integration requires it.
+
+## Verify readiness and tools
+
+From a terminal with `dcc-mcp-cli` installed:
+
+```powershell
+dcc-mcp-cli list --output json
+dcc-mcp-cli search --dcc-type touchdesigner --output json
+```
+
+For release acceptance, verify all six readiness checks and call a cheap read-only typed tool before any mutation. Route later calls to the exact `instance_id` when more than one TouchDesigner process is running.
+
+## Troubleshooting
+
+- `No module named dcc_mcp_touchdesigner`: confirm the configured site-packages path and restart TouchDesigner.
+- Binary import or DLL load errors: rebuild the environment with the exact Python minor version reported by `sys.version`.
+- `No module named td` in a terminal: expected; run host API code inside TouchDesigner.
+- Instance absent from the CLI: compare the registry directory and gateway environment used by TouchDesigner and the terminal.
+- HTTP server is available but host tools time out: confirm the project is cooking and the adapter's `td.run()` main-thread pump has not been stopped.
+- `execute_python` is unavailable: check `DCC_MCP_TOUCHDESIGNER_DISABLE_EXECUTE_PYTHON`; typed tools remain available.

dcc_mcp_touchdesigner-0.1.0/packaging/assemble_release.py

@@ -0,0 +1,69 @@
+"""Assemble dcc-mcp-touchdesigner release payload.
+
+Usage: python packaging/assemble_release.py
+
+Produces a zip archive with the wheel plus a bootstrap script that can be
+extracted into TouchDesigner's site-packages or a custom project folder.
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+from zipfile import ZIP_DEFLATED, ZipFile
+
+ROOT = Path(__file__).resolve().parent.parent
+DIST = ROOT / "dist"
+BOOTSTRAP_TEMPLATE = '''"""TouchDesigner MCP bootstrap — run from a Text DAT on the host thread."""
+import os
+import sys
+
+_WHEEL = os.path.join(os.path.dirname(__file__), "payload", {wheel_name!r})
+if not os.path.isfile(_WHEEL):
+    raise RuntimeError(f"TouchDesigner adapter wheel not found: {{_WHEEL}}")
+if _WHEEL not in sys.path:
+    sys.path.insert(0, _WHEEL)
+
+import dcc_mcp_touchdesigner
+
+server = dcc_mcp_touchdesigner.start_server()
+print(f"[dcc-mcp-touchdesigner] MCP server listening at {{server.mcp_url}}")
+'''
+
+
+def build_wheel() -> Path:
+    """Build the Python wheel and return its path."""
+    subprocess.run(
+        [sys.executable, "-m", "pip", "wheel", "--no-deps", "-w", str(DIST), str(ROOT)],
+        check=True,
+    )
+    wheels = sorted(DIST.glob("dcc_mcp_touchdesigner-*.whl"))
+    if not wheels:
+        raise SystemExit("wheel build failed: no .whl found")
+    return wheels[-1]
+
+
+def assemble_zip(out_path: Path, wheel: Path) -> None:
+    """Create the release zip with bootstrap script + wheel."""
+    with ZipFile(out_path, "w", ZIP_DEFLATED) as zf:
+        zf.writestr("bootstrap.py", BOOTSTRAP_TEMPLATE.format(wheel_name=wheel.name))
+        zf.write(wheel, f"payload/{wheel.name}")
+    print(f"Release zip written to: {out_path}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Assemble dcc-mcp-touchdesigner release")
+    parser.add_argument("-o", "--output", default=None, help="Output zip path")
+    args = parser.parse_args()
+
+    DIST.mkdir(exist_ok=True)
+    wheel = build_wheel()
+    out = args.output or str(DIST / "dcc-mcp-touchdesigner-release.zip")
+    assemble_zip(Path(out), wheel)
+    print("Done.")
+
+
+if __name__ == "__main__":
+    main()