@hypersoniclabs/helix-mcp

The HELIX Instant MCP server gives AI coding agents the platform contract and tells them how to use the helix creator CLI. Resources expose the docs an agent reads before building; tool schemas route arguments into CLI commands. Login stays human (helix login once).

Architecture boundary

Feature and operational logic, validation, file mutation, network behavior, and their tests belong in helix-creator-cli. This package contains only MCP transport, schemas, resources, instructions, and thin CLI delegation. Do not implement a platform feature here.

Use it

Add to your MCP client config (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "helix-instant": {
      "command": "npx",
      "args": ["-y", "@hypersoniclabs/helix-mcp@latest"]
    }
  }
}

Point it at a backend with the HELIX_API_URL env var (defaults to localhost); discovery tools work unauthenticated, publishing needs helix login (a client token).

Tools

World lifecycle: get_started, read_doc, whoami, validate_world, publish_world, list_my_worlds, list_systems, list_abilities, get_package_manifest, check_for_updates. Measurement comes before pixels on every surface, so each pair is measure-then-look: inspect_world / capture_world_screenshot for layout, inspect_gesture / capture_gesture for poses, and inspect_npc / capture_npc for NPC behaviour — the latter runs the built world headlessly and reports distance walked vs gained, stuck windows, arrived edges and the state timelines, then films a captioned strip of it.

Continuum lifecycle: publish_continuum_source_map, publish_continuum_scratch_world, publish_continuum_package, dry_run_continuum_canary, publish_continuum_canary, and get_continuum_publication_receipt. These are thin Creator delegates; MCP does not compile Scenes, persist checkpoints, or grant public Listing authority. The canary tools call the bundled Creator library directly and accept only one descriptor path; public Listing confirmation remains exclusively human-operated CLI authority.

Device lifecycle: create_device, validate_device, test_device. These delegate to the bundled Creator CLI, which owns GLB/node validation and deterministic single-/two-client simulation. Device authoring is intentionally MCP/CLI-only; the website has no parallel Device workbench.

Vault lifecycle:

• search_assets, get_asset, list_asset_versions, install_asset, track_asset, update_asset_metadata
• list_voices for safe text-to-speech voice discovery and pagination
• start_asset_generation, poll_asset_generation
• convenience tools generate_asset (prop/character, with optional deterministic character reference sheet), generate_image, generate_material, generate_audio, generate_environment_splat, and the explicit generate_animation stub

Vault tools return commands for the environment-matched HELIX CLI. The CLI owns authentication, network calls, polling, checksum verification, installation receipts, mutation, and failure semantics; MCP does not carry a second implementation.

Call list_voices before text-to-speech generation; it returns selectable voice ids, supported languages, preview URLs, and default/recommended choices without exposing vendor credentials or voice administration. generate_audio executes that packaged CLI directly and supports the full shared audio route: sound_effect (default), music, and text_to_speech. The tool exposes the curated MP3 formats, mode-specific duration/model controls, and bounded TTS language, voice, seed, voice-settings, and unique pronunciation-dictionary fields. It allows up to 35 minutes for the CLI's durable generation, ingestion, and default-on Vault publication flow to finish, then returns the CLI's JSON receipt.

Resources

helix://docs/{continuum,character-world,world-recipe,sdk,items,purchases,manifest,publishing,catalog} — the agent documentation, served from docs/.

Develop

npm install
npm run build   # tsc → dist/ (bin: dist/server.js)
npm test        # boots the server over stdio and asserts the tools register

The humanoid-character system, its abilities, and asset-packs are authored in helix-web-engine and published to the catalog the agent discovers.