touchdesigner-mcp-server 1.3.0 → 1.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 This is an implementation of an MCP (Model Context Protocol) server for TouchDesigner. Its goal is to enable AI agents to control and operate TouchDesigner projects.
 
-[English](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/README.md) / [日本語](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/README.ja.md)
+[English](README.md) / [日本語](README.ja.md)
 
 ## Overview
 
@@ -14,227 +14,12 @@ TouchDesigner MCP acts as a bridge between AI models and the TouchDesigner WebSe
 - Query node properties and project structure
 - Programmatically control TouchDesigner via Python scripts
 
-## Architecture
+## Installation
 
-```mermaid
-flowchart LR
-    A["🤖<br/>MCP client<br/>(Claude / Codex / ...)"]
+Read the **[Installation Guide](docs/installation.md)**.
 
-    subgraph S [Node.js MCP server]
-      B1["🧰<br/>Tools & prompts<br/>(src/features/tools)"]
-      B2["🖌️<br/>Presenters & formatters<br/>(markdown output)"]
-      B3["🌐<br/>OpenAPI HTTP client<br/>(src/tdClient)"]
-    end
-
-    subgraph T [TouchDesigner project]
-      C1["🧩<br/>WebServer DAT<br/>(mcp_webserver_base.tox)"]
-      C2["🐍<br/>Python controllers / services<br/>(td/modules/mcp)"]
-      C3["🎛️<br/>Project nodes & parameters<br/>(/project1/...)"]
-    end
-
-    A --> B1
-    B1 --> B2
-    B1 --> B3
-    B2 --> A
-    B3 <--> C1
-    C1 <--> C2
-    C2 <--> C3
-
-    %% Higher-contrast colors for readability
-    classDef client fill:#d8e8ff,stroke:#1f6feb,stroke-width:2px,color:#111,font-weight:bold
-    classDef server fill:#efe1ff,stroke:#8250df,stroke-width:2px,color:#111,font-weight:bold
-    classDef td fill:#d7f5e3,stroke:#2f9e44,stroke-width:2px,color:#111,font-weight:bold
-    class A client;
-    class B1,B2,B3 server;
-    class C1,C2,C3 td;
-```
-
-## Usage
-
-<details>
-  <summary>Method 1: Using Claude Desktop and MCP Bundle (Recommended)</summary>
-
-### 1. Download Files
-
-Download the following from the [releases page](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest):
-
-- **TouchDesigner Components**: `touchdesigner-mcp-td.zip`
-- **[MCP Bundle](https://github.com/modelcontextprotocol/mcpb) (.mcpb)**: `touchdesigner-mcp.mcpb`
-
-### 2. Set up TouchDesigner Components
-
-1. Extract the TouchDesigner components from `touchdesigner-mcp-td.zip`.
-2. Import `mcp_webserver_base.tox` into your TouchDesigner project.
-3. Place it at `/project1/mcp_webserver_base`.
-
-<https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4>
-
-  You can check the startup logs by opening the Textport from the TouchDesigner menu.
-
-  ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
-
-### 3. Install the MCP Bundle
-
-Double-click the `touchdesigner-mcp.mcpb` file to install the bundle in Claude Desktop.
-
-<https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854>
-
-### 4. Connect to the Server
-
-The MCP bundle will automatically handle the connection to the TouchDesigner server.
-
-**⚠️ Important:** The directory structure must be preserved exactly as extracted. The `mcp_webserver_base.tox` component references relative paths to the `modules/` directory and other files.
-
-</details>
-
-<details>
-  <summary>Method 2: Using npx</summary>
-
-*Requires Node.js to be installed.*
-
-### 1. Set up TouchDesigner Components
-
-1. Download and extract the TouchDesigner components from `touchdesigner-mcp-td.zip` ([releases page](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest)).
-2. Import `mcp_webserver_base.tox` into your TouchDesigner project.
-3. Place it at `/project1/mcp_webserver_base`.
-
-<https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4>
-
-  You can check the startup logs by opening the Textport from the TouchDesigner menu.
-
-  ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
-
-### 2. Set up the MCP Server Configuration
-
-*Example for Claude Desktop:*
-
-```json
-{
-  "mcpServers": {
-    "touchdesigner": {
-      "command": "npx",
-      "args": ["-y", "touchdesigner-mcp-server@latest", "--stdio"]
-    }
-  }
-}
-```
-
-**Customization:** You can customize the TouchDesigner server connection by adding `--host` and `--port` arguments:
-
-```json
-"args": [
-  "-y",
-  "touchdesigner-mcp-server@latest",
-  "--stdio",
-  "--host=http://custom_host",
-  "--port=9982"
-]
-```
-
-</details>
-
-<details>
-  <summary>Method 3: Using a Docker Image</summary>
-
-  [![tutorial](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/tutorial_docker.png)](https://www.youtube.com/watch?v=BRWoIEVb0TU)
-
-### 1. Clone the repository
-
-  ```bash
-  git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
-  cd touchdesigner-mcp
-  ```
-
-### 2. Build the Docker image
-
-  ```bash
-  make build
-  ```
-
-### 3. Install the API Server in Your TouchDesigner Project
-
-  Start TouchDesigner and import the `td/mcp_webserver_base.tox` component into the project you want to control.
-  Example: Place it at `/project1/mcp_webserver_base`.
-
-  Importing the `.tox` file will trigger the `td/import_modules.py` script, which loads the necessary modules for the API server.
-
-<https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4>
-
-  You can check the startup logs by opening the Textport from the TouchDesigner menu.
-
-  ![import](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
-
-### 4. Start the MCP server container
-
-  ```bash
-  docker-compose up -d
-  ```
-
-### 5. Configure your AI agent to use the Docker container
-
-  *Example for Claude Desktop:*
-
-  ```json
-  {
-    "mcpServers": {
-      "touchdesigner": {
-        "command": "docker",
-        "args": [
-          "compose",
-          "-f",
-          "/path/to/your/touchdesigner-mcp/docker-compose.yml",
-          "exec",
-          "-i",
-          "touchdesigner-mcp-server",
-          "node",
-          "dist/cli.js",
-          "--stdio",
-          "--host=http://host.docker.internal"
-        ]
-      }
-    }
-  }
-```
-
-  *On Windows systems, include the drive letter, e.g., `C:\path\to\your\touchdesigner-mcp\docker-compose.yml`.*
-
-**Note:** You can customize the TouchDesigner server connection by adding `--host` and `--port` arguments:
-
-  ```json
-"args": [
-  ...,
-  "--stdio",
-  "--host=http://host.docker.internal",
-  "--port=9982"
-]
-  ```
-
-</details>
-
-## Verify Connection
-
-If the MCP server is recognized, the setup is complete.
-If it's not recognized, try restarting your AI agent.
-If you see an error at startup, try launching the agent again after starting TouchDesigner.
-When the API server is running properly in TouchDesigner, the agent can use the provided tools to operate it.
-
-### Directory Structure Requirements
-
-**Critical:** When using any method, you must maintain the original directory structure:
-
-```
-td/
-├── import_modules.py          # Module loader script
-├── mcp_webserver_base.tox     # Main TouchDesigner component
-└── modules/                   # Python modules directory
-    ├── mcp/                   # MCP core logic
-    ├── utils/                 # Shared utilities
-    └── td_server/             # Generated API server code
-```
-
-The `mcp_webserver_base.tox` component uses relative paths to locate Python modules. Moving or reorganizing these files will cause import errors in TouchDesigner.
-
-![demo](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/nodes_list.png)
+The guide includes the required TouchDesigner preparation, per-agent setup, verification steps, and
+troubleshooting tips.
 
 ## MCP Server Features
 
@@ -273,106 +58,48 @@ Prompts provide instructions for AI agents to perform specific actions in TouchD
 
 Not implemented.
 
-## For Developers
-
-### Quick Start for Development
-
-1. **Set up your environment:**
-
-   ```bash
-   # Clone and install dependencies
-   git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
-   cd touchdesigner-mcp
-   npm install
-   ```
-
-2. **Build the project:**
-
-   ```bash
-   make build        # Docker-based build (recommended)
-   # OR
-   npm run build     # Node.js-based build
-   ```
-
-3. **Available commands:**
-
-   ```bash
-   npm run test      # Run unit and integration tests
-   npm run dev       # Launch the MCP inspector for debugging
-   ```
-
-**Note:** When you update the code, you must restart both the MCP server and TouchDesigner to apply the changes.
-
-### Project Structure Overview
-
-```
-├── src/                       # MCP server source code
-│   ├── api/                  # OpenAPI spec for the TouchDesigner WebServer
-│   ├── core/                 # Core utilities (logger, error handling)
-│   ├── features/             # MCP feature implementations
-│   │   ├── prompts/         # Prompt handlers
-│   │   ├── resources/       # Resource handlers
-│   │   └── tools/           # Tool handlers (e.g., tdTools.ts)
-│   ├── gen/                  # Code generated from the OpenAPI schema for the MCP server
-│   ├── server/               # MCP server logic (connections, main server class)
-│   ├── tdClient/             # TouchDesigner connection API client
-│   ├── index.ts              # Main entry point for the Node.js server
-│   └── ...
-├── td/                        # TouchDesigner-related files
-│   ├── modules/              # Python modules for TouchDesigner
-│   │   ├── mcp/              # Core logic for handling MCP requests in TouchDesigner
-│   │   │   ├── controllers/ # API request controllers (api_controller.py, generated_handlers.py)
-│   │   │   └── services/    # Business logic (api_service.py)
-│   │   ├── td_server/        # Python model code generated from the OpenAPI schema
-│   │   └── utils/            # Shared Python utilities
-│   ├── templates/             # Mustache templates for Python code generation
-│   ├── genHandlers.js         # Node.js script for generating generated_handlers.py
-│   ├── import_modules.py      # Helper script to import API server modules into TouchDesigner
-│   └── mcp_webserver_base.tox # Main TouchDesigner component
-├── tests/                      # Test code
-│   ├── integration/
-│   └── unit/
-└── orval.config.ts             # Orval config (TypeScript client generation)
-```
-
-### API Code Generation Workflow
-
-This project uses OpenAPI-based code generation tools (Orval and openapi-generator-cli).
-
-**API Definition:** The API contract between the Node.js MCP server and the Python server running inside TouchDesigner is defined in `src/api/index.yml`.
-
-1. **Python server generation (`npm run gen:webserver`):**
-    - Uses `openapi-generator-cli` via Docker.
-    - Reads `src/api/index.yml`.
-    - Generates a Python server skeleton (`td/modules/td_server/`) based on the API definition. This code runs inside TouchDesigner's WebServer DAT.
-    - **Requires Docker to be installed and running.**
-2. **Python handler generation (`npm run gen:handlers`):**
-    - Uses a custom Node.js script (`td/genHandlers.js`) and Mustache templates (`td/templates/`).
-    - Reads the generated Python server code or OpenAPI spec.
-    - Generates handler implementations (`td/modules/mcp/controllers/generated_handlers.py`) that connect to the business logic in `td/modules/mcp/services/api_service.py`.
-3. **TypeScript client generation (`npm run gen:mcp`):**
-    - Uses `Orval` to generate an API client and Zod schemas for tool validation from the schema YAML, which is bundled by `openapi-generator-cli`.
-    - Generates a typed TypeScript client (`src/tdClient/`) used by the Node.js server to make requests to the WebServer DAT.
-
-The build process (`npm run build`) runs all necessary generation steps (`npm run gen`), followed by TypeScript compilation (`tsc`).
-
-### Version management
-
-- `package.json` is the single source of truth for every component version (Node.js MCP server, TouchDesigner Python API, MCP bundle, and `server.json` metadata).
-- Run `npm version <patch|minor|major>` (or the underlying `npm run gen:version`) whenever you bump the version. The script rewrites `pyproject.toml`, `td/modules/utils/version.py`, `mcpb/manifest.json`, and `server.json` so that the release workflow can trust the tag value.
-- The GitHub release workflow (`.github/workflows/release.yml`) tags the commit as `v${version}` and publishes `touchdesigner-mcp-td.zip` / `touchdesigner-mcp.mcpb` from the exact same version number. Always run the sync step before triggering a release so that every artifact stays aligned.
+## Developer Guide
+
+Looking for local setup, client configuration, project structure, or release workflow notes?
+See the **[Developer Guide](docs/development.md)** for all developer-facing documentation.
 
 ## Troubleshooting
 
 ### Troubleshooting version compatibility
 
-- During `ConnectionManager.connect` the MCP server compares its own version with the TouchDesigner API server version reported by `getTdInfo`. If the API server does not expose a version or the versions differ (for example because only one side was updated), the MCP server aborts the connection with a descriptive error message in the Claude/Codex console and in the TouchDesigner log DAT.
-- To resolve the mismatch, reinstall both the TouchDesigner components
+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](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest/download/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.
+  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).
-- When developing locally, run `npm run gen: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 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.
+
+### Troubleshooting connection errors
+
+- `TouchDesignerClient` caches failed connection checks for **5 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
 

package/dist/cli.js

@@ -1,11 +1,16 @@
 #!/usr/bin/env node
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ConsoleLogger } from "./core/logger.js";
 import { TouchDesignerServer } from "./server/touchDesignerServer.js";
+import { isStreamableHttpTransportConfig } from "./transport/config.js";
+import { ExpressHttpManager } from "./transport/expressHttpManager.js";
+import { TransportFactory } from "./transport/factory.js";
+import { SessionManager } from "./transport/sessionManager.js";
 // Note: Environment variables should be set by the MCP Bundle runtime or CLI arguments
 const DEFAULT_HOST = "http://127.0.0.1";
 const DEFAULT_PORT = 9981;
+const DEFAULT_MCP_ENDPOINT = "/mcp";
 /**
- * Parse command line arguments
+ * Parse command line arguments for TouchDesigner connection
  */
 export function parseArgs(args) {
     const argsToProcess = args || process.argv.slice(2);
@@ -25,38 +30,149 @@ export function parseArgs(args) {
     return parsed;
 }
 /**
- * Determine if the server should run in stdio mode
+ * Parse transport configuration from command line arguments
+ *
+ * Detects if HTTP mode is requested via --mcp-http-port flag.
+ * If not specified, defaults to stdio mode.
+ *
+ * @param args - Command line arguments (defaults to process.argv.slice(2))
+ * @returns Transport configuration (stdio or streamable-http)
+ *
+ * @example
+ * ```bash
+ * # Stdio mode (default)
+ * touchdesigner-mcp-server --host=http://localhost --port=9981
+ *
+ * # HTTP mode
+ * touchdesigner-mcp-server --mcp-http-port=6280 --mcp-http-host=127.0.0.1
+ * ```
  */
-export function isStdioMode(nodeEnv, argv) {
-    const env = nodeEnv ?? process.env.NODE_ENV;
-    const args = argv ?? process.argv;
-    return env === "cli" || args.includes("--stdio");
+export function parseTransportConfig(args) {
+    const argsToProcess = args || process.argv.slice(2);
+    // Check for HTTP mode
+    const httpPortArg = argsToProcess.find((arg) => arg.startsWith("--mcp-http-port="));
+    if (httpPortArg) {
+        const portStr = httpPortArg.split("=")[1];
+        const port = Number.parseInt(portStr, 10);
+        if (Number.isNaN(port) || port < 1 || port > 65535) {
+            console.error(`Invalid value for --mcp-http-port: "${portStr}". Please specify a valid port number (1-65535).`);
+            process.exit(1);
+        }
+        const hostArg = argsToProcess.find((arg) => arg.startsWith("--mcp-http-host="));
+        const host = hostArg ? hostArg.split("=")[1] : "127.0.0.1";
+        const config = {
+            endpoint: DEFAULT_MCP_ENDPOINT,
+            host,
+            port,
+            sessionConfig: { enabled: true },
+            type: "streamable-http",
+        };
+        return config;
+    }
+    // Default to stdio mode
+    return { type: "stdio" };
 }
 /**
  * Start TouchDesigner MCP server
+ *
+ * Supports both stdio and HTTP transport modes based on command line arguments.
+ *
+ * @param params - Server startup parameters
+ * @param params.argv - Command line arguments
+ * @param params.nodeEnv - Node environment
+ *
+ * @example
+ * ```bash
+ * # Stdio mode (default)
+ * touchdesigner-mcp-server --host=http://localhost --port=9981
+ *
+ * # HTTP mode
+ * touchdesigner-mcp-server --mcp-http-port=6280 --host=http://localhost --port=9981
+ * ```
  */
 export async function startServer(params) {
     try {
-        const isStdioModeFlag = isStdioMode(params?.nodeEnv, params?.argv);
-        if (!isStdioModeFlag) {
-            throw new Error("Sorry, this server is not yet available in the browser. Please use the CLI mode.");
-        }
-        // Parse command line arguments and set environment variables
+        // Parse transport configuration
+        const transportConfig = parseTransportConfig(params?.argv);
+        // Parse TouchDesigner connection arguments
         const args = parseArgs(params?.argv);
         process.env.TD_WEB_SERVER_HOST = args.host;
         process.env.TD_WEB_SERVER_PORT = args.port.toString();
+        // Create MCP server
         const server = new TouchDesignerServer();
-        const transport = new StdioServerTransport();
-        const result = await server.connect(transport);
-        if (!result.success) {
-            throw new Error(`Failed to connect: ${result.error.message}`);
+        // Handle stdio mode
+        if (transportConfig.type === "stdio") {
+            const transportResult = TransportFactory.create(transportConfig);
+            if (!transportResult.success) {
+                throw transportResult.error;
+            }
+            const result = await server.connect(transportResult.data);
+            if (!result.success) {
+                throw new Error(`Failed to connect: ${result.error.message}`);
+            }
+            console.error("MCP server started in stdio mode");
+            return;
         }
+        // Handle HTTP mode
+        if (isStreamableHttpTransportConfig(transportConfig)) {
+            // Use ConsoleLogger for HTTP manager and session manager
+            // This avoids "Not connected" errors since HTTP mode doesn't have a global MCP connection
+            const logger = new ConsoleLogger();
+            // Create session manager if enabled
+            const sessionManager = transportConfig.sessionConfig?.enabled
+                ? new SessionManager(transportConfig.sessionConfig, logger)
+                : null;
+            // Server factory for creating per-session instances
+            // Each session gets its own TouchDesignerServer with independent MCP protocol state
+            const serverFactory = () => TouchDesignerServer.create();
+            // Create Express HTTP manager with server factory
+            const httpManager = new ExpressHttpManager(transportConfig, serverFactory, sessionManager, logger);
+            // Start HTTP server
+            const startResult = await httpManager.start();
+            if (!startResult.success) {
+                throw startResult.error;
+            }
+            console.error(`MCP server started in HTTP mode on ${transportConfig.host}:${transportConfig.port}${transportConfig.endpoint}`);
+            // Start session cleanup if enabled
+            if (sessionManager) {
+                sessionManager.startTTLCleanup();
+            }
+            // Set up graceful shutdown
+            const shutdown = async () => {
+                console.error("\nShutting down server...");
+                // Stop session cleanup
+                if (sessionManager) {
+                    sessionManager.stopTTLCleanup();
+                }
+                // Stop HTTP server
+                const stopResult = await httpManager.stop();
+                if (!stopResult.success) {
+                    console.error(`Error during shutdown: ${stopResult.error.message}`);
+                }
+                console.error("Server shutdown complete");
+                process.exit(0);
+            };
+            process.on("SIGINT", shutdown);
+            process.on("SIGTERM", shutdown);
+            return;
+        }
+        // Type-safe exhaustive check using never type
+        // This ensures all cases of the TransportConfig discriminated union are handled
+        // If a new transport type is added, TypeScript will error at compile time
+        assertNever(transportConfig);
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         throw new Error(`Failed to initialize server: ${errorMessage}`);
     }
 }
+/**
+ * Helper function for exhaustive type checking
+ * TypeScript will error if called with a non-never type, ensuring all cases are handled
+ */
+function assertNever(value) {
+    throw new Error(`Unsupported transport type: ${value.type}`);
+}
 // Start server if this file is executed directly
 startServer({
     argv: process.argv,