@scene-grid/mcp-server

Model Context Protocol (MCP) server for the SceneGrid virtual mixing console

The SceneGrid MCP Server provides diagnostic and orchestration tools for the SceneGrid audio engine. It acts as a bridge, allowing AI Agents (like Claude Desktop or Cursor) to query the engine's internal telemetry, trigger dynamic changes, and utilize guided Prompts through standard MCP (Model Context Protocol).

Installation & Usage

You can run the SceneGrid MCP Server directly using npx, or integrate it into your AI assistant (like Claude Desktop or Cursor).

Running directly (via npx)

To boot the server directly without cloning the repository, you can use npx:

npx -y @scene-grid/mcp-server

(This command uses mcp-use under the hood to start the server and listener).

Integrating with Claude Desktop

Add the following to your Claude Desktop configuration file (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "scenegrid": {
      "command": "npx",
      "args": [
        "-y",
        "@scene-grid/mcp-server"
      ]
    }
  }
}

Application Setup

Once the MCP Server is running, boot your scenegrid-console engine with the remoteSyncUri configuration:

const audio = new AudioEngine({
    // ... other config ...
    remoteSyncUri: 'ws://localhost:8081'
});

The engine will automatically stream telemetry to the MCP server, and your AI assistant will have real-time access to the console!

Development

If you are developing the server locally inside the monorepo:

npm run dev -w packages/mcp-server

Overview

This server acts as a WebSocket relay, connecting to a running instance of scenegrid-console configured with the remoteSyncUri targeting ws://localhost:8081. Once connected, the engine continuously streams its real-time telemetry (playbacks, buses, RTPC values, RAM limits) to the MCP server.

Agents and AI assistants can query this in-memory snapshot via passive MCP Resources, trigger dynamic changes via Tools, or utilize guided Prompts without requiring direct side-channel integrations with the web application.

Available MCP Resources

Resources provide passive, contextual data that agents can read without executing an action.

• scenegrid://manifest/current
  • Purpose: Always up-to-date static JSON manifest including banks, events, buses, and global settings.
• scenegrid://telemetry/live
  • Purpose: Current active playbacks (voices), buses, and RTPCs in the engine.
• scenegrid://validation/latest
  • Purpose: Latest consistency and validation report generated by the engine.
• scenegrid://ram/budget
  • Purpose: Current memory status (usedBytes / maxQuotaBytes).
• scenegrid://context/conventions
  • Purpose: Dynamically reads the project's AGENTS.md conventions.

Available MCP Tools

Runtime Debugging

These tools interact with the live state of the engine. Use them when you need to trigger logic, adjust parameters interactively, or control global execution on the fly.

• trigger_event
  • Purpose: Fires a specific event ID through the command dispatcher.
  • Usage: Use this to test event bindings or trigger logic paths live in the console. (Requires an active WebSocket connection to the engine).
• set_rtpc_value
  • Purpose: Forcibly overrides an RTPC (Real-Time Parameter Control) value.
  • Usage: Use this to interactively adjust game parameters (like player speed, health, or distance) and monitor how the engine reacts without hardcoding values in a script.
• stop_all_sounds
  • Purpose: Global emergency stop for all physical voices in the engine.
  • Usage: Instant state reset during debugging.
• pause_engine
  • Purpose: Freezes the EngineTicker, pausing all audio processing.
  • Usage: Use this to halt time and inspect the live telemetry state safely.
• resume_engine
  • Purpose: Resumes the EngineTicker.
  • Usage: Use this to continue execution after pausing.
• apply_mixer_snapshot
  • Purpose: Activates a mixer VCA snapshot with a transition over a specified time.
  • Usage: Testing dynamic switching of mixer presets on the fly.
• trace_event
  • Purpose: Returns the recent history of CAUSE_CHAIN and LIFECYCLE events.
  • Usage: Tracing how an audio event originated and propagated through the system over time.
• record_session_telemetry
  • Purpose: Starts or stops telemetry buffering.
  • Usage: Capturing a time-boxed snapshot of live telemetry data for later analysis.

Static Configuration & AOT Processing

• validate_configurations

  • Purpose: Runs a provided JSON configuration payload against the strict ConsistencyChecker rules (such as checking for Routing Cycles, Valid Parent Buses, Sound Maps, etc.).
  • Usage: Call this before saving a configuration payload to ensure it conforms to the scenegrid-console strict validation requirements.

• process_assets

  • Purpose: Programmatically executes the main @scene-grid/cli pipeline.
  • Usage: Use this to automatically apply stream rules, check memory quotas, and generate ready-to-use production assets and JSON manifests from a folder of raw recordings.

• generate_aliases

  • Purpose: Scans a directory of WAV files and generates a SoundId aliases JSON file.
  • Usage: Automatically map raw file names (e.g. explosion_v2.wav) to strict domain types.

• inspect_pcm_weight

  • Purpose: Reads raw audio file headers and returns the exact uncompressed RAM footprint (in bytes) along with duration and sample rate.
  • Usage: Determine how much memory a specific track will consume before adding it to the engine, allowing intelligent decisions on streaming vs preloading.

• get_quota_preview

  • Purpose: Generates a dry-run report showing how raw audio assets will be allocated between memory (AudioBuffer) and disk (ChunkedStream) based on the provided RAM quota and streaming rules.
  • Usage: Simulate memory allocation for a specific folder before running the full asset processing pipeline.

• get_schema

  • Purpose: Exposes the pre-generated JSON Schema for the engine configuration.
  • Usage: Automatically understand the strict domain data structures expected by the engine. Supports returning specific definition slices to prevent context window overflow.

• query_graph

  • Purpose: Fetches localized manifest branches using dot-notation (e.g. buses.sfx).
  • Usage: Surgically query nested configurations when the full static manifest is too large for context.

Available MCP Prompts

• debug-audio-issue
  • Purpose: Guided instructions for troubleshooting missing or incorrect audio playback.
  • Usage: Invoke this prompt when debugging silent voices or routing failures to receive a checklist of required resource checks.

License

MIT © Igor Zabrodin