@hybridlabor-api/aos 4.3.0 → 4.4.0

package/mcps/touchdesigner-mcp/docs/development.ja.md

@@ -1,197 +0,0 @@
-# TouchDesigner MCP Server 開発者向けガイド
-
-ローカル開発環境の構築手順、各 MCP クライアント設定、プロジェクト構成、コード生成ワークフロー、バージョン管理のポイントをこのドキュメントに集約しました。コンポーネント構成の概要は **[アーキテクチャ](./architecture.md)** を参照してください。
-
-## 開発のクイックスタート
-
-1. **環境設定:**
-
-   ```bash
-   # リポジトリをクローンして依存関係をインストール
-   git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
-   cd touchdesigner-mcp
-   npm install
-   ```
-
-2. **ビルド:**
-
-   ```bash
-   make build        # Docker-based build（推奨）
-   # または
-   npm run build     # Node.js-based build
-   ```
-
-3. **利用可能なコマンド:**
-
-   ```bash
-   npm run test      # ユニットテストと統合テスト
-   npm run dev       # デバッグ用の MCP Inspector
-   ```
-
-**注意:** コードを更新した場合は、MCP サーバーと TouchDesigner の両方を再起動してください。
-
-## ローカル MCP クライアント設定
-
-ローカルビルドした MCP サーバーへ接続するための設定例です。
-
-### Claude Desktop (`claude_desktop_config.json`)
-
-```json
-{
-  "mcpServers": {
-    "touchdesigner-stdio": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "/path/to/your/touchdesigner-mcp/dist/cli.js",
-        "--stdio",
-        "--port=9981"
-      ]
-    },
-    "touchdesigner-http-npx": {
-      "command": "npx",
-      "args": [
-        "mcp-remote",
-        "http://localhost:6280/mcp"
-      ]
-    }
-  }
-}
-```
-
-### Claude Code (`~/.claude.json`)
-
-```json
-{
-  "mcpServers": {
-    // claude mcp add -s user touchdesigner-stdio -- npx -y /path/to/your/touchdesigner-mcp/dist/cli.js --stdio --port=9981
-    "touchdesigner-stdio": {
-      "type": "stdio",
-      "command": "npx",
-      "args": [
-        "-y",
-        "/path/to/your/touchdesigner-mcp/dist/cli.js",
-        "--stdio",
-        "--port=9981"
-      ],
-      "env": {}
-    },
-    // claude mcp add -s user --transport http touchdesigner-http http://localhost:6280/mcp
-    "touchdesigner-http": {
-      "type": "http",
-      "url": "http://localhost:6280/mcp"
-    },
-    // claude mcp add -s user touchdesigner-http-npx -- npx mcp-remote http://localhost:6280/mcp
-    "touchdesigner-http-npx": {
-      "type": "stdio",
-      "command": "npx",
-      "args": [
-        "mcp-remote",
-        "http://localhost:6280/mcp"
-      ],
-      "env": {}
-    }
-  }
-}
-```
-
-### Codex (`~/.codex/config.toml`)
-
-```toml
-# codex mcp add touchdesigner-stdio -- npx -y /path/to/your/touchdesigner-mcp/dist/cli.js --stdio --port=9981
-[mcp_servers.touchdesigner-stdio]
-command = "npx"
-args = ["-y", "/path/to/your/touchdesigner-mcp/dist/cli.js", "--stdio", "--port=9981"]
-
-# codex mcp add touchdesigner-http --url http://localhost:6280/mcp
-[mcp_servers.touchdesigner-http]
-url = "http://localhost:6280/mcp"
-
-# codex mcp add touchdesigner-http-npx -- npx mcp-remote http://localhost:6280/mcp
-[mcp_servers.touchdesigner-http-npx]
-command = "npx"
-args = ["mcp-remote", "http://localhost:6280/mcp"]
-```
-
-## 開発ワークフロー
-
-1. **クローン & 依存関係インストール**
-
-   ```bash
-   git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
-   cd touchdesigner-mcp
-   npm install
-   ```
-
-2. **ビルド**
-
-   ```bash
-   npm run build  # コード生成を含むフルビルド
-   # または
-   make build     # Docker ベースのビルド
-   ```
-
-3. **テスト / Inspector**
-
-   ```bash
-   npm test       # すべてのテストを実行
-   npm run dev    # MCP Inspector を起動
-   ```
-
-詳細な開発コマンドは `CLAUDE.md` を参照してください。
-
-## プロジェクト構造
-
-```
-├── src/                       # MCP サーバーのソースコード
-│   ├── api/                  # TouchDesigner WebServer 向け OpenAPI 仕様
-│   ├── core/                 # ロガー / エラーハンドリングなどのコアユーティリティ
-│   ├── features/             # MCP 機能実装
-│   │   ├── prompts/         # プロンプトハンドラ
-│   │   ├── resources/       # リソースハンドラ
-│   │   └── tools/           # ツール定義・ハンドラ (toolDefinitions.ts, tdTools.ts)
-│   ├── gen/                  # OpenAPI スキーマから生成されたコード
-│   ├── server/               # MCP サーバーロジック
-│   ├── tdClient/             # TouchDesigner 接続 API クライアント
-│   ├── index.ts              # Node.js エントリーポイント
-│   └── ...
-├── td/                        # TouchDesigner 関連ファイル
-│   ├── modules/              # TouchDesigner 用 Python モジュール
-│   │   ├── mcp/              # MCP リクエストを処理するコアロジック
-│   │   │   ├── controllers/ # API リクエストコントローラ
-│   │   │   └── services/    # ビジネスロジック
-│   │   ├── td_server/        # OpenAPI から生成された Python モデルコード
-│   │   └── utils/            # 共有 Python ユーティリティ
-│   ├── templates/             # Python コード生成用 Mustache テンプレート
-│   ├── genHandlers.js         # generated_handlers.py 生成用 Node.js スクリプト
-│   ├── import_modules.py      # TouchDesigner へモジュールを読み込むヘルパー
-│   └── mcp_webserver_base.tox # TouchDesigner コンポーネント
-├── tests/                      # テストコード
-│   ├── integration/
-│   └── unit/
-└── orval.config.ts             # Orval 設定 (TS クライアント生成)
-```
-
-## API コード生成ワークフロー
-
-このプロジェクトは OpenAPI ベースのコード生成ツール（Orval / `@redocly/cli`）を使用します。
-
-**API 定義:** Node.js MCP サーバーと TouchDesigner 内の Python サーバー間の契約は `src/api/index.yml` に定義されています。
-
-1. **OpenAPI スキーマバンドル (`npm run gen:openapi`):**
-    - `@redocly/cli` で `src/api/index.yml` の `$ref` をすべて解決。
-    - 単一の YAML を `td/modules/td_server/openapi_server/openapi/openapi.yaml` に出力。TouchDesigner 内の Python `OpenAPIRouter` が読み込むほか、以降の 2 ステップの入力になります。
-2. **Python ハンドラ生成 (`npm run gen:handlers`):**
-    - `td/genHandlers.js` と Mustache テンプレート (`td/templates/`) を使用。
-    - バンドル済み OpenAPI 仕様を読み込み、`td/modules/mcp/controllers/generated_handlers.py` を生成。
-3. **TypeScript クライアント生成 (`npm run gen:mcp`):**
-    - バンドル済みスキーマを元に Orval が API クライアント (`src/gen/endpoints/`) と Zod スキーマ (`src/gen/mcp/`) を生成。
-    - Node.js サーバーが WebServer DAT にアクセスするための型付きクライアント (`src/tdClient/`) から利用されます。
-
-`npm run build` は必要なコード生成 (`npm run gen`) をすべて実行し、その後 TypeScript コンパイル (`tsc`) を行います。
-
-## バージョン管理
-
-- `package.json` が Node.js MCP サーバー / TouchDesigner Python API / MCP バンドル / `server.json` のバージョン情報の単一ソースです。
-- `npm version <patch|minor|major>`（または `npm run version`）を使用してバージョンを上げると、`pyproject.toml`、`td/modules/utils/version.py`、`mcpb/manifest.json`、`server.json` が同期されます。
-- GitHub のリリースワークフロー（`.github/workflows/release.yml`）は `v${version}` でタグ付けし、同じバージョンから `touchdesigner-mcp-td.zip` / `touchdesigner-mcp.mcpb` を公開します。リリース前に必ず同期ステップを実行し、すべての成果物が一致するようにしてください。

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

@@ -1,212 +0,0 @@
-# TouchDesigner MCP Server Developer Guide
-
-This guide consolidates all developer-focused content: local environment setup, MCP client
-configuration, project structure, code generation workflows, and release/versioning tips. For a
-high-level view of components and data flow, see **[Architecture](./architecture.md)**.
-
-## 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, restart both the MCP server and TouchDesigner to apply
-changes.
-
-## Local MCP Client Configuration
-
-Use these snippets to point your preferred MCP client at a local build of the server.
-
-### Claude Desktop (`claude_desktop_config.json`)
-
-```json
-{
-  "mcpServers": {
-    "touchdesigner-stdio": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "/path/to/your/touchdesigner-mcp/dist/cli.js",
-        "--stdio",
-        "--port=9981"
-      ]
-    },
-    "touchdesigner-http-npx": {
-      "command": "npx",
-      "args": [
-        "mcp-remote",
-        "http://localhost:6280/mcp"
-      ]
-    }
-  }
-}
-```
-
-### Claude Code (`~/.claude.json`)
-
-```json
-{
-  "mcpServers": {
-    // claude mcp add -s user touchdesigner-stdio -- npx -y /path/to/your/touchdesigner-mcp/dist/cli.js --stdio --port=9981
-    "touchdesigner-stdio": {
-      "type": "stdio",
-      "command": "npx",
-      "args": [
-        "-y",
-        "/path/to/your/touchdesigner-mcp/dist/cli.js",
-        "--stdio",
-        "--port=9981"
-      ],
-      "env": {}
-    },
-    // claude mcp add -s user --transport http touchdesigner-http http://localhost:6280/mcp
-    "touchdesigner-http": {
-      "type": "http",
-      "url": "http://localhost:6280/mcp"
-    },
-    // claude mcp add -s user touchdesigner-http-npx -- npx mcp-remote http://localhost:6280/mcp
-    "touchdesigner-http-npx": {
-      "type": "stdio",
-      "command": "npx",
-      "args": [
-        "mcp-remote",
-        "http://localhost:6280/mcp"
-      ],
-      "env": {}
-    }
-  }
-}
-```
-
-### Codex (`~/.codex/config.toml`)
-
-```toml
-# codex mcp add touchdesigner-stdio -- npx -y /path/to/your/touchdesigner-mcp/dist/cli.js --stdio --port=9981
-[mcp_servers.touchdesigner-stdio]
-command = "npx"
-args = ["-y", "/path/to/your/touchdesigner-mcp/dist/cli.js", "--stdio", "--port=9981"]
-
-# codex mcp add touchdesigner-http --url http://localhost:6280/mcp
-[mcp_servers.touchdesigner-http]
-url = "http://localhost:6280/mcp"
-
-# codex mcp add touchdesigner-http-npx -- npx mcp-remote http://localhost:6280/mcp
-[mcp_servers.touchdesigner-http-npx]
-command = "npx"
-args = ["mcp-remote", "http://localhost:6280/mcp"]
-```
-
-## Development Workflow
-
-1. **Clone and install**:
-
-   ```bash
-   git clone https://github.com/8beeeaaat/touchdesigner-mcp.git
-   cd touchdesigner-mcp
-   npm install
-   ```
-
-2. **Build**:
-
-   ```bash
-   npm run build  # Full build with code generation
-   # or
-   make build     # Docker-based build
-   ```
-
-3. **Test / inspect**:
-
-   ```bash
-   npm test       # Run all tests
-   npm run dev    # Launch MCP inspector
-   ```
-
-See `CLAUDE.md` for additional developer-focused commands.
-
-## 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 definitions & handlers (toolDefinitions.ts, 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 `@redocly/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. **OpenAPI schema bundling (`npm run gen:openapi`):**
-    - Uses `@redocly/cli` to resolve all `$ref` references in `src/api/index.yml`.
-    - Outputs a single bundled YAML to
-      `td/modules/td_server/openapi_server/openapi/openapi.yaml`, which is loaded by the
-      Python `OpenAPIRouter` inside TouchDesigner and consumed by the following two steps.
-2. **Python handler generation (`npm run gen:handlers`):**
-    - Uses a custom Node.js script (`td/genHandlers.js`) and Mustache templates (`td/templates/`).
-    - Reads the bundled 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 (`src/gen/endpoints/`) and Zod schemas
-      (`src/gen/mcp/`) for tool validation from the bundled schema YAML.
-    - The generated client is consumed by `src/tdClient/` 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 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 every artifact stays aligned.