Prompts

Prompts provide instructions for AI agents to perform specific actions in TouchDesigner.

| Prompt Name | Description | | :------------------| :-------------------------------------------------------------------------- | | Search node | Fuzzy searches for nodes and retrieves information based on name, family, or type. | | Node connection | Provides instructions to connect nodes within TouchDesigner. | | Check node errors| Checks for errors on a specified node, and recursively for its children. |

Resources

Not implemented.

Developer Guide

Looking for local setup, client configuration, project structure, or release workflow notes? See the Developer Guide for all developer-facing documentation.

Troubleshooting

Troubleshooting version compatibility

The MCP server uses semantic versioning for flexible compatibility checks

| MCP Server | API Server | Minimum compatible API version | Behavior | Status | Notes | |------------|------------|----------------|----------|--------|-------| | 1.3.x | 1.3.0 | 1.3.0 | ✅ Works normally | Compatible | Recommended baseline configuration | | 1.3.x | 1.4.0 | 1.3.0 | ⚠️ Warning shown, continues | Warning | Older MCP MINOR with newer API may lack new features | | 1.4.0 | 1.3.x | 1.3.0 | ⚠️ Warning shown, continues | Warning | Newer MCP MINOR may have additional features | | 1.3.2 | 1.3.1 | 1.3.2 | ❌ Execution stops | Error | API below minimum compatible version | | 2.0.0 | 1.x.x | N/A | ❌ Execution stops | Error | Different MAJOR = breaking changes |

Compatibility Rules:

• ✅ Compatible: Same MAJOR version AND API version ≥ 1.3.0 (minimum compatible version)

• ⚠️ Warning: Different MINOR or PATCH versions within the same MAJOR version (shows warning but continues execution)

• ❌ Error: Different MAJOR versions OR API server < 1.3.0 (execution stops immediately, update required)

• To resolve compatibility errors:

  1. Download the latest touchdesigner-mcp-td.zip from the releases page.
  2. Delete the existing touchdesigner-mcp-td folder and replace it with the newly extracted contents.
  3. Remove the old mcp_webserver_base component from your TouchDesigner project and import the .tox from the new folder.
  4. Restart TouchDesigner and the AI agent running the MCP server (e.g., Claude Desktop).

• For developers: When developing locally, run npm run version after editing package.json (or simply use npm version ...). This keeps the Python API (pyproject.toml + td/modules/utils/version.py), MCP bundle manifest, and registry metadata in sync so that the runtime compatibility check succeeds.

For a deeper look at how the MCP server enforces these rules, see Version Compatibility Verification.

Troubleshooting connection errors

• TouchDesignerClient caches failed connection checks for 60 seconds. Subsequent tool calls reuse the cached error to avoid spamming TouchDesigner and automatically retry after the TTL expires.
• When the MCP server cannot reach TouchDesigner, you now get guided error messages with concrete fixes:
  • ECONNREFUSED / "connect refused": start TouchDesigner, ensure the WebServer DAT from mcp_webserver_base.tox is running, and confirm the configured port (default 9981).
  • ETIMEDOUT / "timeout": TouchDesigner is responding slowly or the network is blocked. Restart TouchDesigner/WebServer DAT or check your network connection.
  • ENOTFOUND / getaddrinfo: the host name is invalid. Use 127.0.0.1 unless you explicitly changed it.
• The structured error text is also logged through ILogger, so you can check the MCP logs to understand why a request stopped before hitting TouchDesigner.
• Once the underlying issue is fixed, simply run the tool again—the client clears the cached error and re-verifies the connection automatically.

Contributing

We welcome your contributions!

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Make your changes.
4. Add tests and ensure everything works (npm test).
5. Commit your changes (git commit -m 'Add some amazing feature').
6. Push to your branch (git push origin feature/amazing-feature).
7. Open a pull request.

Please always include appropriate tests when making implementation changes.

License

MIT