X32-MCP CLAUDE.md

MCP TypeScript SDK Guide

Build & Test Commands

npm run build        # Build ESM and CJS versions
npm run lint         # Run ESLint
npm test             # Run all tests
npx jest path/to/file.test.ts  # Run specific test file
npx jest -t "test name"        # Run tests matching pattern

Code Style Guidelines

• TypeScript: Strict type checking, ES modules, explicit return types
• Naming: PascalCase for classes/types, camelCase for functions/variables
• Files: Lowercase with hyphens, test files with .test.ts suffix
• Imports: ES module style, include .js extension, group imports logically
• Error Handling: Use TypeScript's strict mode, explicit error checking in tests
• Formatting: 2-space indentation, semicolons required, single quotes preferred
• Testing: Co-locate tests with source files, use descriptive test names
• Comments: JSDoc for public APIs, inline comments for complex logic

Project description

OSC UDP Transport (raw)
        ↓
Address Pattern DSL (/ch/01/mix/fader)
        ↓
MCP Tool Layer (task-based)

MCP Tool Design Principles

Core Philosophy

Tools represent semantic user intentions, not API endpoints.

MCP tools must be designed as task-based abstractions that reflect meaningful user actions, not thin wrappers around OSC address patterns. Each tool should represent a complete, semantically meaningful operation that an LLM agent would naturally choose.

Tool Naming Convention

Pattern: <domain>_<action>

• Domain: The logical grouping (e.g., channel, bus, fx, main, connection)
• Action: The semantic task being performed (e.g., set_volume, mute, get_state)
• Separator: Use underscore (_) between domain and action
• Case: Use lowercase with underscores (snake_case)

Examples:

✅ GOOD - Task-based, semantic actions:

channel_set_volume           # Set channel fader level
channel_set_gain             # Set channel preamp gain
channel_mute                 # Mute/unmute a channel
channel_solo                 # Solo a channel
channel_get_state            # Get complete channel state
channel_set_eq_band          # Set specific EQ band parameters
bus_set_volume               # Set bus fader level
fx_set_parameter             # Set effects parameter
main_set_volume              # Set main stereo fader
connection_connect           # Connect to X32/M32
connection_get_info          # Get mixer information