@hybridlabor-api/aos 4.2.0 → 4.4.0

package/mcps/touchdesigner-mcp/docs/installation.md

@@ -1,406 +0,0 @@
-# TouchDesigner MCP Server Installation Guide
-
-Installation guide for TouchDesigner MCP across different AI agents and platforms.
-
-[English](installation.md) / [日本語](installation.ja.md)
-
-## Quick Start
-
-Most users can get running quickly with the Claude Desktop bundle flow. Download both
-`touchdesigner-mcp-td.zip` and `touchdesigner-mcp.mcpb` from the
-[latest release](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest),
-import `mcp_webserver_base.tox` into your TouchDesigner project
-(`project1/mcp_webserver_base` is recommended), then double-click the `.mcpb` file to
-install it in Claude Desktop. The bundle automatically connects to TouchDesigner once the
-component is running.
-
-## Table of Contents
-
-- [Prerequisites](#prerequisites)
-- [TouchDesigner Setup (Required for All Methods)](#touchdesigner-setup-required-for-all-methods)
-- [MCP Server Installation Methods](#mcp-server-installation-methods)
-  - [Method 1: MCP Bundle (Claude Desktop only)](#method-1-mcp-bundle-claude-desktop-only)
-  - [Method 2: NPM Package (Claude Code, Codex, and other MCP clients)](#method-2-npm-package-claude-code-codex-and-other-mcp-clients)
-  - [Method 3: Docker Container](#method-3-docker-container)
-- [For Updates from Previous Versions](#for-updates-from-previous-versions)
-- [HTTP Transport Mode](#http-transport-mode)
-- [Verification](#verification)
-- [Troubleshooting](#troubleshooting)
-
-## Prerequisites
-
-- **TouchDesigner** (latest version recommended)
-- For NPM-based installations: **Node.js** 18.x or later _(not required when you only use Claude Desktop with the MCP bundle)_
-- For Docker-based installations: **Docker** and **Docker Compose**
-
-## TouchDesigner Setup (Required for All Methods)
-
-**This step is required regardless of which installation method you choose.**
-
-1. Download [touchdesigner-mcp-td.zip](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest/download/touchdesigner-mcp-td.zip) from the latest release
-2. Extract the ZIP file
-3. Import `mcp_webserver_base.tox` into your TouchDesigner project
-4. Place it at `/project1/mcp_webserver_base` (or your preferred location)
-
-<https://github.com/user-attachments/assets/215fb343-6ed8-421c-b948-2f45fb819ff4>
-
-**⚠️ Most Important:** Do not change the folder structure or move files within the folder. `mcp_webserver_base.tox` references the contents of `modules/` using relative paths.
-
-**Directory Structure**:
-
-```text
-touchdesigner-mcp-td/
-├── import_modules.py          # Module loader
-├── mcp_webserver_base.tox     # Main component
-└── modules/                   # Python modules
-    ├── mcp/                   # Core MCP logic
-    ├── utils/                 # Utilities
-    └── td_server/             # API server code
-```
-
-You can verify successful setup by checking the Textport (Alt+T or Dialogs → Textport):
-
-![Textport](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/textport.png)
-
-## MCP Server Installation Methods
-
-Choose one of the following installation methods based on your AI agent and preferences.
-They all assume your TouchDesigner project already contains the imported
-`mcp_webserver_base.tox` component from the previous section.
-
-### Method 1: MCP Bundle (Claude Desktop only)
-
-**Best for**: Claude Desktop users who want the simplest installation experience.
-
-#### Downloads
-
-Download the following from the [latest release](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest):
-
-- **TouchDesigner Components**: [touchdesigner-mcp-td.zip](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest/download/touchdesigner-mcp-td.zip)
-- **MCP Bundle**: [touchdesigner-mcp.mcpb](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest/download/touchdesigner-mcp.mcpb)
-
-#### Installation Steps
-
-1. **Prepare TouchDesigner**
-   - Complete the [TouchDesigner Setup](#touchdesigner-setup-required-for-all-methods) once per project (import `mcp_webserver_base.tox`, keep the folder layout intact, verify via Textport).
-
-2. **Install the MCP Bundle**
-   - Double-click the `touchdesigner-mcp.mcpb` file to install it in Claude Desktop
-
-   <https://github.com/user-attachments/assets/0786d244-8b82-4387-bbe4-9da048212854>
-
-3. **Start Using**
-   - The bundle automatically handles the TouchDesigner server connection once the component is running
-   - Restart Claude Desktop if the MCP server is not recognized
-   - Open the Claude Desktop MCP panel to confirm that `touchdesigner-mcp` is available
-
-### Method 2: NPM Package (Claude Code, Codex, and other MCP clients)
-
-**Best for**: Users who want flexibility across different AI agents or need custom configuration.
-
-#### Installation Prerequisites
-
-- Node.js 18.x or later installed
-- TouchDesigner components set up (see [TouchDesigner Setup](#touchdesigner-setup-required-for-all-methods))
-
-Once those prerequisites are in place, add the MCP server to your client using one of the following configurations.
-
-#### For Claude Desktop
-
-Edit your `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "touchdesigner": {
-      "command": "npx",
-      "args": ["-y", "touchdesigner-mcp-server@latest", "--stdio"]
-    }
-  }
-}
-```
-
-_Optional:_ Add `--host` / `--port` arguments if TouchDesigner is not running on the defaults (`http://127.0.0.1:9981`).
-
-#### For Claude Code
-
-Run the following command:
-
-```bash
-claude mcp add -s user touchdesigner -- npx -y touchdesigner-mcp-server@latest --stdio
-```
-
-Or manually edit `~/.claude.json`:
-
-```json
-{
-  "mcpServers": {
-    "touchdesigner": {
-      "command": "npx",
-      "args": ["-y", "touchdesigner-mcp-server@latest", "--stdio"],
-    }
-  }
-}
-```
-
-#### For Codex
-
-Run the following command:
-
-```bash
-codex mcp add touchdesigner -- npx -y touchdesigner-mcp-server@latest --stdio
-```
-
-Or manually edit `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.touchdesigner]
-command = "npx"
-args = ["-y", "touchdesigner-mcp-server@latest", "--stdio"]
-```
-
-#### For Other MCP Clients
-
-Any MCP-compatible client can use the NPM package via stdio transport:
-
-- **Command**: `npx`
-- **Args**: `["-y", "touchdesigner-mcp-server@latest", "--stdio"]`
-- **Optional Args**: `--host=<url>`, `--port=<number>`
-
-Add the optional flags only when TouchDesigner is not running on `http://127.0.0.1:9981`.
-
-### Method 3: Docker Container
-
-**Best for**: Developers, CI/CD pipelines, or users who prefer containerized environments.
-
-#### Docker Prerequisites
-
-- Docker and Docker Compose installed
-- TouchDesigner components set up (see [TouchDesigner Setup](#touchdesigner-setup-required-for-all-methods))
-
-#### Installation Steps
-
-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. **Start the container**
-
-Choose a transport configuration:
-
-##### Option A: Streamable HTTP ([spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http))
-
-<https://github.com/user-attachments/assets/4025f9cd-b19c-42f0-8274-7609650abd34>
-
-1. Start the container with HTTP transport:
-
-   ```bash
-   TRANSPORT=http docker-compose up -d
-   ```
-
-2. (Optional) Override the HTTP port or TouchDesigner host:
-
-   ```bash
-   TRANSPORT=http \
-   MCP_HTTP_PORT=6280 \
-   TD_HOST=http://host.docker.internal \
-   docker compose up -d
-   ```
-
-3. Point your MCP client to the HTTP endpoint. For example:
-
-- **Claude Code (native HTTP entry):**
-
-    ```json
-    {
-      "mcpServers": {
-        "touchdesigner-http": {
-          "type": "http",
-          "url": "http://localhost:6280/mcp"
-        }
-      }
-    }
-    ```
-
-- **Claude Desktop (via `mcp-remote`):**
-
-    ```json
-    {
-      "mcpServers": {
-        "touchdesigner-http": {
-          "command": "npx",
-          "args": [
-            "mcp-remote",
-            "http://localhost:6280/mcp"
-          ]
-        }
-      }
-    }
-    ```
-
-4. Confirm the container is healthy (container binds `0.0.0.0`, Docker publishes to `127.0.0.1` by default):
-
-   ```bash
-   curl http://localhost:6280/health
-   ```
-
-##### Option B: Stdio Passthrough
-
-1. Start the container in stdio mode:
-
-   ```bash
-   docker-compose up -d
-   ```
-
-2. Configure your client to exec into the container (Claude Desktop example):
-
-   ```json
-   {
-     "mcpServers": {
-       "touchdesigner-docker": {
-         "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 include the drive letter (for example `C:\\path\\to\\touchdesigner-mcp\\docker-compose.yml`)._
-
-## For Updates from Previous Versions
-
-If you are updating, please refer to the procedure in the **[Latest Release](https://github.com/8beeeaaat/touchdesigner-mcp/releases/latest#for-updates-from-previous-versions)**.
-
-## HTTP Transport Mode
-
-TouchDesigner MCP Server can run as an HTTP endpoint for remote clients, browser-based
-integrations, or when you prefer not to rely on stdio. Treat this section as optional—only
-follow it if you need HTTP/SSE access instead of stdio. You can start HTTP mode directly
-from the Node.js CLI or inside the Docker container.
-
-### Starting in HTTP Mode
-
-#### Start the container with HTTP transport
-
-```bash
-TRANSPORT=http docker-compose up -d
-```
-
-<https://github.com/user-attachments/assets/4025f9cd-b19c-42f0-8274-7609650abd34>
-
-#### Using npm command
-
-```bash
-# Start HTTP server
-# 127.0.0.1:6280/mcp
-npm run http
-```
-
-<https://github.com/user-attachments/assets/5447e4da-eb5a-4ebd-bbbe-3ba347d1f6fb>
-
-```bash
-touchdesigner-mcp-server \
-  --mcp-http-port=6280 \
-  --mcp-http-host=127.0.0.1 \
-  --host=http://127.0.0.1 \
-  --port=9981
-```
-
-### Configuration Options
-
-| Option | Description | Default |
-| --- | --- | --- |
-| `--mcp-http-port` | HTTP server port (required for HTTP mode) | - |
-| `--mcp-http-host` | Bind address (`0.0.0.0` in Docker entrypoint, `127.0.0.1` in CLI) | `127.0.0.1` (CLI) |
-| `--host` | TouchDesigner WebServer host | `http://127.0.0.1` |
-| `--port` | TouchDesigner WebServer port | `9981` |
-
-> Security tip (Docker): the container binds to `0.0.0.0`, but `docker-compose.yml` publishes `127.0.0.1:${MCP_HTTP_PORT}` by default so the endpoint is loopback-only. If you intentionally expose it to your LAN/WAN, change the compose port mapping (for example `"0.0.0.0:6280:6280"`) and protect it with a firewall/reverse proxy and authentication.
-
-### Health Check
-
-```bash
-curl http://localhost:6280/health
-```
-
-Expected response:
-
-```json
-{
-  "status": "ok",
-  "sessions": 0,
-  "timestamp": "2025-12-06T05:30:00.000Z"
-}
-```
-
-### Transport Differences
-
-| Feature | stdio | Streamable HTTP |
-| --- | --- | --- |
-| Connection | Standard I/O | HTTP/SSE |
-| Use Case | Local CLI / desktop tools | Remote agents, browser integrations |
-| Session Management | Single connection | Multi-session with TTL |
-| Port Required | No | Yes |
-
-## Verification
-
-After installation:
-
-1. Start TouchDesigner with the imported `mcp_webserver_base.tox` component
-2. Start your AI agent (Claude Desktop / Claude Code / Codex / etc.)
-3. Confirm the `touchdesigner-mcp` server appears in the agent UI
-
-If it does not show up:
-
-- Restart the AI agent
-- Make sure TouchDesigner and the WebServer DAT are running
-- Review the logs for error messages
-
-Example view inside an agent:
-
-![Nodes List](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/assets/nodes_list.png)
-
-## Troubleshooting
-
-### Version Compatibility Issues
-
-The MCP server enforces semantic versioning. If you see a compatibility warning or error:
-
-1. Repeat the steps in [TouchDesigner Setup](#touchdesigner-setup-required-for-all-methods)
-2. Remove the old `mcp_webserver_base` component and import the updated `.tox`
-3. Restart both TouchDesigner and your AI agent
-
-See [Troubleshooting version compatibility](https://github.com/8beeeaaat/touchdesigner-mcp#troubleshooting-version-compatibility) in the README for additional details.
-
-### Connection Issues
-
-Refer to [Troubleshooting connection errors](https://github.com/8beeeaaat/touchdesigner-mcp#troubleshooting-connection-errors) in the README for guided error messages (ECONNREFUSED, ETIMEDOUT, ENOTFOUND, etc.).
-
-### Other Issues
-
-- Check [GitHub Issues](https://github.com/8beeeaaat/touchdesigner-mcp/issues) for known reports
-- Review the [main README](https://github.com/8beeeaaat/touchdesigner-mcp/blob/main/README.md) for more background information
-
-## For Developer Setup
-
-Need developer-focused workflows? See the [Developer Guide](development.md).