CLAUDE.md · 8beeeaaat/touchdesigner-mcp

Sections

1. Development Commands
2. Architecture Overview
3. Development Workflow
4. TouchDesigner-Specific Patterns
5. Current Development Tasks

First lines (shown under the repo's MIT license)

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

### Building and Development
- `npm run build` - Full build process including code generation and TypeScript compilation (recommended for development)
- `npm run dev` - Start MCP inspector for debugging (`@modelcontextprotocol/inspector`)
- `make build` - Docker-based build that copies both `dist/` and `td/modules/` from container (for CI/CD)
- `npm run build:mcpb` - Build MCP Bundle package for distribution
- `make clean` - Remove all generated files (`dist`, `td/modules`, `node_modules`)

### Code Generation Workflow
The project uses OpenAPI 3.1.0 schema-based code generation with a three-step process:

- `npm run gen:openapi` - Bundle OpenAPI schema files into single YAML using `@redocly/cli`
- `npm run gen:handlers` - Generate Python handlers using custom Node.js script with Mustache templates
- `npm run gen:mcp` - Generate TypeScript client code and Zod schemas using Orval v8
- `npm run gen` - Run all generation steps in sequence

### Testing and Quality
- `npm test` - Run all tests (e2e, integration, unit, and TouchDesigner-side Python)
- `npm run test:e2e` - E2E tests: builds `dist/` and drives the built `dist/cli.js` with the real MCP SDK v2 client over stdio and Streamable HTTP (both protocol eras; no TouchDesigner required)
- `npm run test:integration` - Integration tests with TouchDesigner WebServer
- `npm run test:unit` - Unit tests for MCP server components
- `npm run test:python` - TouchDesigner-side Python tests against a stubbed `td` module (no TouchDesigner needed; requires Python 3.9+ with pytest, or `uv`)
- `npm run ci:test:integration` - The integration suites that need no live TouchDesigner
- `npm run coverage` - Generate test coverage report

### HTTP Transport Mode
- `npm run http` - Build and start the MCP server in HTTP mode (port 6280, TD on 9981)
- `npm run test:integration` - Includes the HTTP transport suite (`tests/integration/httpTransport.test.ts`)

**HTTP Mode Configuration:**
- Default port: `3000`
- Default host: `127.0.0.1`
- Endpoint: `/mcp`
- Health check: `GET /health`

### Linting and Formatting

The project uses multiple formatters and linters for different languages:

**All languages:**

- `npm run lint` - Run all linters (Biome, TypeScript, Ruff, Prettier)
- `npm run format` - Auto-fix formatting for all languages

**TypeScript/JavaScript (Biome):**

- `npm run lint:biome` - Lint TypeScript/JavaScript files
- `npm run format:biome` - Format and fix TypeScript/JavaScript files
- Sorts imports and object keys automatically via Biome Assist

**Python (Ruff):**

- `npm run lint:python` - Lint Python files in `td/` directory
- `npm run format:python` - Format and fix Python files (includes import sorting)
- Configuration in `pyproject.toml`
- Note: Only `td/modules/td_server/openapi_server/openapi/openapi.yaml` is auto-generated

**YAML (Prettier):**

- `npm run lint:yaml` - Check YAML file formatting
- `npm run format:yaml` - Format YAML files (uses Prettier)
- Configuration in `.prettierrc.json`

**Important:**

- Python (Ruff) must be installed separately via pip/pipx/uv for formatting to work

## Architecture Overview

### Dual-Process Architecture
This MCP server operates as a bridge between AI agents and TouchDesigner through a dual-process architecture:

1. **Node.js MCP Server** (`src/`) - Implements MCP protocol, handles AI agent communication
2. **Python WebServer** (`td/modules/`) - Runs inside TouchDesigner via WebServer DAT, controls TD directly

Communication flows: AI Agent ↔ Node.js MCP Server ↔ HTTP API ↔ Python WebServer (in TouchDesigner)

### Key Components

#### MCP Server (Node.js)
- `TouchDesignerServer` class in `src/server/touchDesignerServer.ts` - Main MCP server implementation
- `TouchDesignerClient` in `src/tdClient/` - HTTP client for communicating with TD WebServer
- Tool definitions in `src/features/tools/toolDefinitions.ts` - `TOOL_DEFINITIONS` is the single source of truth for each MCP tool (name, description, input schema, handler). `handlers/tdTools.ts` registers them in a loop, and the `describe_td_tools` manifest derives its parameter metadata from each tool's Zod schema via introspection
- Code generation outputs in `src/gen/` - Auto-generated API client and Zod schemas

#### TouchDesigner Integration (Python)
- `mcp_webserver_base.tox` - Main TouchDesigner component to import
- `api_controller.py` - Routes HTTP requests using OpenAPI schema
- `api_service.py` - Business logic for TouchDesigner operations
- `generated_handlers.py` - Auto-generated handler stubs (connects controller to service)

### Transport Architecture

Both transports serve MCP protocol revision 2026-07-28 and transparently fall back to the 2025-era protocol for older clients, from the same server factory (`TouchDesignerServer.create()`):

- stdio – `serveStdio(factory)` from `@modelcontextprotocol/server/stdio`, wired in `src/cli.ts`; the opening exchange selects the protocol era per connection
- `src/transport/expressHttpManager.ts` – Mounts `createMcpHandler(factory)` (stateless per-request serving for both eras) on the SDK Express app (`createMcpExpressApp`, DNS-rebinding protection) via `toNodeHandler`, wiring `/mcp` and `/health`, plus graceful shutdown
- `src/transport/config.ts` – Type definitions and Zod validators for `TransportConfig`

Protocol-level sessions were removed by spec revision 2026-07-28: there is no `Mcp-Session-Id` header, and `GET`/`DELETE /mcp` answer `405`. The MCP `logging` capability is no longer declared (deprecated by SEP-2577); logs go to stderr via `ConsoleLogger`.

Design references: `.doc/streamable-http-implementation-plan.md` and `.doc/refactor_sdk_first.md` cover the SDK-first approach and HTTP rollout plan.

### Code Generation System
The project uses OpenAPI 3.1.0 schema (`src/api/index.yml`) for maintaining consistency:

- OpenAPI schema bundled via `@redocly/cli` to `td/modules/td_server/openapi_server/openapi/openapi.yaml`
- TypeScript API client and Zod schemas generated via Orval v8
- Python handler stubs generated using Mustache templates
- All generation must run after schema changes

### Environment Configuration
- Server accepts `--host` and `--port` CLI arguments instead of using .env files
- Default TouchDesigner WebServer runs on `localhost:9981`
- CLI arguments: `--host=http://localhost --port=9981`
- Environment variables are set programmatically from CLI arguments at runtime

## Development Workflow

1. **Setting up TouchDesigner**: Import `td/mcp_webserver_base.tox` into your TD project
2. **Code changes**: Modify source files in `src/` or TouchDesigner modules in `td/modules/`
3. **API changes**: Update `src/api/index.yml` then run `npm run gen` to regenerate all code
4. **Building**: Run `npm run build` for full build or `make build` for Docker-based build
5. **Testing**: Always run `npm test` before committing changes

## TouchDesigner-Specific Patterns

### Node Operations
- Node paths use TouchDesigner's `/project1/container/node` format
- Family types include `COMP`, `TOP`, `SOP`, `CHOP`, `DAT`, `MAT`
- Parameter updates use TouchDesigner's parameter system via Python API

### Python Execution
- Scripts execute in TouchDesigner's Python environment via `execute_python_script` tool
- Access to `td` module, `me`, `op()`, and all TouchDesigner Python APIs
- Results serialized as JSON for transmission back to MCP client

### Error Handling
- Uses Result pattern for error propagation between Node.js and Python layers
- TouchDesigner errors captured and formatted for MCP protocol
- Logging available in both TouchDesigner Textport and MCP client

## Current Development Tasks

**Recent Update**: MCP protocol revision 2026-07-28

- Migrated from `@modelcontextprotocol/sdk` 1.x to the SDK v2 packages (`@modelcontextprotocol/server` / `node` / `express` / `core` 2.0.0)
- Both transports serve protocol revision 2026-07-28 with transparent 2025-era fallback (`serveStdio` / `createMcpHandler`)
- Streamable HTTP is stateless: `TransportFactory` / `TransportRegistry` / `SessionManager` were deleted
- Tools use `registerTool`, prompts use `registerPrompt` (Zod schemas); the deprecated MCP `logging` capability was dropped (stderr logging instead)
- Node.js 22.18+, 24.x, or 26+ required (odd-numbered releases are not supported by the toolchain)

**Previous Update**: Generation pipeline simplification

- Replaced `@openapitools/openapi-generator-cli` (Java-based python-flask generator) with `@redocly/cli` bundle — only the bundled `openapi.yaml` was ever consumed downstream