# 🎛️ touchdesigner-agent-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Status: Stable](https://img.shields.io/badge/status-stable-green.svg)](https://github.com/axysar/touchdesigner-agent-mcp)
[![Python: 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
[![MCP: 1.0](https://img.shields.io/badge/MCP-1.0-orange.svg)](https://modelcontextprotocol.io)

A premium, open-source **Model Context Protocol (MCP) server** that empowers LLMs (like Claude) to directly control, introspect, and build **TouchDesigner** networks in real-time. 

With this server, an AI coding agent can create and connect operators, query parameters, capture the viewport to *see* what it built, automatically fix compile errors, and stream real-time data from TouchDesigner CHOPs.

---

## 🏗️ Architecture

This repository uses a zero-dependency, dual-process architecture:

```unicode
┌─────────────────────────────────┐
│     Claude / MCP Host           │
└────────────────┬────────────────┘
                 │
                 │ MCP (stdio)
                 ▼
┌─────────────────────────────────┐
│     touchdesigner-agent-mcp (Python Client) │
└────────────────┬────────────────┘
                 │
                 │ HTTP (POST /mcp)
                 ▼
┌─────────────────────────────────┐
│  TouchDesigner Web Server DAT   │ (Installed via td/install.py)
└────────────────┬────────────────┘
                 │
                 ▼
┌─────────────────────────────────┐
│     TouchDesigner Operators     │
└─────────────────────────────────┘
```

The TouchDesigner side is built completely in plain Python (exposed via a Web Server DAT), meaning **no binary `.tox` files** or opaque components. You can read, audit, and diff every single line of code running in your project.

---

## ✨ Features

### 🔄 Dual-Directional Integration
* **25 Tools**: Full CRUD for nodes, wiring, force-cooking, viewport rendering, and GLSL editing.
* **4 Prompt Templates**: Guiding instructions that teach LLMs the best tool combinations for node finding, error handling, operator connections, and network repairs.
* **4 Resource Templates**: Native MCP `td://` resources that let the LLM stream live data from CHOP channels, node parameters, and project metadata.

### 🛡️ Undo Safety (Ctrl+Z)
Every single tool invocation that mutates TouchDesigner is automatically wrapped in a transaction block (`ui.undo`). If the agent makes a mistake, deletes a critical node, or wires something incorrectly, you can instantly revert it by pressing **Ctrl+Z** inside TouchDesigner.

### ⚡ Progress Tracking
Long-running operations (like scene scaffolding, viewport captures, and force-cooking) report real-time progress to the MCP client via the `report_progress` API, showing you exactly what the server is doing.

### 🔒 Zero-Config Security
On first installation, the installer auto-generates a secure, random Auth Token (`secrets.token_urlsafe(32)`) and binds it to the component. The token is preserved across reinstalls, keeping your TouchDesigner instance secure from unauthorized remote code execution (RCE).

---

## 🎛️ Tool Matrix

| Category | Tools | Description |
| :--- | :--- | :--- |
| **System Info** | `get_td_info`, `describe_td_tools` | Inspect TouchDesigner build, OS, and available tool schemas. |
| **Node CRUD** | `get_td_nodes`, `create_td_node`, `update_td_node_parameters`, `delete_td_node` | Create, read, update, and delete operators. |
| **Parameters & Errors** | `get_td_node_parameters`, `get_td_node_errors`, `exec_node_method` | Read parameters, query errors, or trigger pulses/methods. |
| **Python RCE** | `execute_python_script` | Run arbitrary Python scripts directly inside the TouchDesigner execution context. |
| **Introspection** | `get_td_classes`, `get_td_class_details`, `get_td_module_help` | Let the LLM search TouchDesigner's Python API, docs, and help pages. |
| **Visual Vision** | `td_viewport` | Captures any TOP/COMP or the active network pane as an image (Base64 or file path). |
| **Scene Scaffold** | `td_scaffold` | Scaffold complete pipelines (Feedback Loop, Instancing, Render Setup) in one click. |
| **Advanced Wiring** | `td_connect`, `td_layout` | Family-validated operator wiring and automatic positioning without node overlaps. |
| **GLSL & Files** | `td_glsl`, `td_save_tox`, `td_load_tox`, `td_save_project` | Author GLSL shaders, import/export `.tox` assets, and save the `.toe` project. |
| **Media Assets** | `td_list_media_assets` | Scan local project directories for video, audio, images, and geometry assets. |

---

## 📡 Resources

MCP Clients can read or subscribe to real-time resources using the `td://` URI scheme:

| URI Template | Resource Type | Description |
| :--- | :--- | :--- |
| `td://chop/{path}` | **Dynamic CHOP Stream** | Streams active float values for all channels in the target CHOP (e.g. `td://chop/project1/lfo1`). |
| `td://node/{path}` | **Node Parameters** | Lightweight read endpoint for parameters and operator metadata. |
| `td://errors/{path}` | **Error State** | Inspects compilation or wiring errors for the target node and its children. |
| `td://project/info` | **Static Project Info** | Metadata including project name, folder path, and the TouchDesigner app build. |

---

## 🚀 Quick Start

### 1. Set Up TouchDesigner Side
1. Copy the [`td/`](td/) folder somewhere stable on your disk.
2. In TouchDesigner, open the **Textport** (`Alt+T`) and run the installer:
   ```python
   import sys
   sys.path.append('/ABSOLUTE/PATH/TO/td')
   import install
   install.install()
   ```
3. This creates `/project1/td_agent_mcp` with a Web Server DAT running on port `9981`.
4. Note the secure **Auth Token** printed in the Textport—you will need this for step 3.

> [!TIP]
> If you make changes to the scripts in the `td/` directory, you can reload and reinstall them instantly using:
> `import importlib; importlib.reload(install); install.install()`

---

### 2. Install the MCP Server
Build and run the server using `uv` (recommended):

```bash
# To run locally
uv sync
uv run touchdesigner-agent-mcp --stdio
```

---

### 3. Register the Server with Your Client

#### Claude Desktop
Add the server configuration to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "touchdesigner-agent-mcp": {
      "command": "uv",
      "args": [
        "run", 
        "--directory", 
        "/ABSOLUTE/PATH/TO/touchdesigner-agent-mcp", 
        "touchdesigner-agent-mcp", 
        "--stdio"
      ],
      "env": {
        "TD_AUTH_TOKEN": "YOUR_AUTO_GENERATED_TOKEN_HERE"
      }
    }
  }
}
```

#### Claude Code (CLI)
Install the bundled marketplace plugin:
```bash
/plugin marketplace add axysar/touchdesigner-agent-mcp
```

---

## ⚙️ Configuration Reference

You can configure the client using environment variables or command-line flags:

| Environment Variable | CLI Flag | Default | Description |
| :--- | :--- | :--- | :--- |
| `TD_HOST` | `--td-host` | `127.0.0.1` | The hostname/IP of the machine running TouchDesigner. |
| `TD_PORT` | `--td-port` | `9981` | The port of the Web Server DAT. |
| `TD_AUTH_TOKEN` | `--td-token` | *(empty)* | Security token matching the `Authtoken` parameter. |
| `TD_TIMEOUT` | `--timeout` | `30` | Request timeout in seconds. |

---

## 🔒 Security Hardening

Because the server allows arbitrary Python execution inside TouchDesigner (giving the LLM full RCE capabilities on your local system), security is critical:
* **Token Auth**: All incoming HTTP requests require a valid `Authorization: Bearer <token>` header.
* **Auto-Generation**: If a token isn't manually specified, the installer automatically generates a cryptographically secure 32-character token.
* **CORS Protection**: The TouchDesigner Web Server DAT strictly rejects requests from arbitrary browser origins.
* **Traversals**: Asset scanning is restricted to a maximum depth of `5` levels to prevent system performance issues or directory leaks.

---

## 🛠️ Development & Contributing

See [`CLAUDE.md`](CLAUDE.md) for quick-start development guidelines.

### Running Tests
To run registration, schema validation, and resource-binding checks without requiring TouchDesigner to be active:
```bash
uv run pytest
```

### Code Style
We use `ruff` to enforce linting and formatting standards:
```bash
uv run ruff check .
uv run ruff format .
```

---

## 📄 License & Attribution

This project is licensed under the **MIT License** — see [LICENSE](LICENSE).

It synthesizes and extends two outstanding prior open-source works:
* [@8beeeaaat/touchdesigner-mcp](https://github.com/8beeeaaat/touchdesigner-mcp) (Dual-process structure and baseline CRUD operations).
* [@satoruhiga/claude-touchdesigner](https://github.com/satoruhiga/claude-touchdesigner) (TouchDesigner helper libraries).

TouchDesigner is a registered trademark of Derivative.