clbhundley/ossm-mcp-server

OSSM WebSocket Control MCP Server

A Model Context Protocol (MCP) server for controlling OSSM devices via binary WebSocket commands. This tool enables AIs to control OSSM motion patterns with precise timing.

Features

• Smooth point-to-point movement with customizable easing curves
• Continuous loop patterns with independent push/pull stroke characteristics
• Localized vibration patterns with adjustable frequency and waveform
• Global speed and acceleration limits for safety
• Dynamic range controls for motion boundaries
• Emergency pause functionality from multiple control sources

MCP Server Setup

Requirements

• OSSM device with compatible firmware
• Godot WebSocket bridge application running on port 8081
• MCP-compatible AI

1. Install dependencies in the ossm-mcp-server directory:

npm install

2. Add to MCP configuration (example: claude_desktop_config.json):

{
  "mcpServers": {
    "ossm-websocket-control": {
      "command": "node",
      "args": ["/absolute/path/to/ossm-mcp-server.js"]
    }
  }
}

3. Restart AI desktop application to load the new MCP server

Available Functions

ossm_smooth_move

Execute smooth point-to-point motion with easing curves.

Parameters:

• durationMs (required): Duration of movement in milliseconds
• position (required): Target position (0-10000, where 10000 = full rail)
• transition: Transition type - LINEAR, SINE, CIRC, EXPO, QUAD, CUBIC, QUART, QUINT (default: SINE)
• ease: Easing type - EASE_IN, EASE_OUT, EASE_IN_OUT, EASE_OUT_IN (default: EASE_IN_OUT)
• aux: Auxiliary functions bitmask (default: 0)

Example:

// Smooth 2-second move to 75% position with sine transition
ossm_smooth_move(2000, 7500, "SINE", "EASE_IN_OUT", 0)

ossm_loop

Define continuous back-and-forth motion patterns.

Parameters:

• pushStroke (required): Object defining forward motion
  • durationMs: Duration in milliseconds
  • transition: Transition type (required)
  • ease: Easing type (required)
  • aux: Auxiliary functions (default: 0)
• pullStroke (required): Object defining return motion (same structure as pushStroke)

Important: Loop motion range is controlled by global range limits (see ossm_set_range_limit), not position parameters.

Example:

// Fast loop with different characteristics for each stroke
ossm_loop(
  {durationMs: 800, transition: "SINE", ease: "EASE_IN", aux: 0},
  {durationMs: 1200, transition: "CIRC", ease: "EASE_OUT", aux: 0}
)

ossm_vibrate

Configure localized vibration patterns with adjustable waveform.

Parameters:

• durationMs (required): Duration in ms (-1 for infinite, 0 to stop)
• halfPeriodMs (required): Half period in ms (controls frequency, minimum: 10ms)
• position (required): Center position for vibration (0-10000)
• range (required): Stroke range percentage (0-20%)
• smooth: Waveform smoothing (100=triangle, 200=square, default: 112)

Safety Guidelines:

• High frequency + small range: Use 10-50ms halfPeriodMs with 2-10% range for intense, localized vibration
• Low frequency + larger range: Use 50-200ms halfPeriodMs with 10-20% range for pronounced oscillations
• Avoid: Large range (>10%) with very high frequency (<20ms) - can stress hardware

Example:

// Gentle 25Hz vibration at center position
ossm_vibrate(-1, 20, 5000, 5, 112)

ossm_pause

Immediately pause all current motion. Works as emergency stop from any control source.

Parameters: None

ossm_set_speed_limit

Set global motor speed limit across all motion modes.

Parameters:

• speedHz (required): Maximum speed in steps/second

ossm_set_acceleration

Set global motor acceleration limit across all motion modes.

Parameters:

• accel (required): Maximum acceleration in steps/second²

ossm_set_range_limit

Set motion range boundaries for position control.

Parameters:

• range (required): Which limit to set - "MIN_RANGE" or "MAX_RANGE"
• limit (required): Position limit (0-10000)

Note: Range limits affect loop commands automatically but require re-sending vibrate commands to take effect.

Important Behavioral Differences

Loop Commands

• Auto-update with global setting changes (range limits, speed limits)
• Motion boundaries controlled by global range limits
• Ideal for full-rail patterns and sequences

Vibrate Commands

• Manual update required - must re-send command after changing global settings
• Self-contained position and range parameters
• Ideal for localized effects and high-frequency patterns

Safety Guidelines

Emergency Controls

• Pause command works immediately from MCP or device UI
• Mode switching transitions smoothly between different motion types
• UI override - device interface can always stop MCP-initiated motion

Parameter Limits

• Vibration frequency: Tested safe up to 50Hz (20ms halfPeriodMs), higher frequencies may skip steps
• Range boundaries: System automatically constrains motion within physical rail limits
• Speed limits: Global limits prevent excessive motor stress across all modes

Best Practices

1. Test gradually - start with conservative settings and adjust
2. Monitor motor behavior - watch for step skipping, overheating, or strain
3. Use appropriate combinations - high frequency with small range, low frequency with larger range
4. Emergency stop ready - always know how to pause motion quickly