@hypersoniclabs/helix-mcp 0.2.4 → 0.2.12

package/README.md

@@ -1,9 +1,19 @@
 # @hypersoniclabs/helix-mcp
 
-The **HELIX Instant MCP server** — gives AI coding agents the platform contract so they can inspect
-it, generate a compatible world, validate it, and publish it. Resources expose the docs an agent
-reads before generating; tools run the same code paths as the human `helix` CLI (it depends on
-`@hypersoniclabs/helix-cli`). Login stays human (`helix login` once); agents check `whoami`.
+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.
+
+**Engine systems are ranges.** Docs, recipes, skills and tool descriptions here say `^0.3`-style ranges for
+`helix.json` `systems`; the CLI's `validate`/`publish` (and so `validate_world`/`publish_world`) refuse an exact
+engine pin unless a human passes `--allow-exact-engine-pin "<reason>"` (logged). To ship an engine fix to Worlds,
+promote it (`POST /api/v1/instant-packages/<slug>/versions/<version>/rollout`); do not pin.
 
 ## Use it
 
@@ -25,13 +35,74 @@ unauthenticated, publishing needs `helix login` (a client token).
 
 ## Tools
 
-`get_started`, `read_doc`, `whoami`, `validate_world`, `publish_world`, `list_my_worlds`,
-`list_systems`, `list_abilities`, `get_package_manifest`, `check_for_updates`.
+World lifecycle: `get_started`, `read_doc`, `whoami`, `validate_world`, `publish_world`,
+`list_my_worlds`, `list_systems`, `list_abilities`, `get_package_manifest`,
+`check_for_updates`, and `analyze_scene_performance`. The performance analyzer reads the exact
+Scene resource closure and optional runtime receipt, reports authored and submitted costs
+separately, and returns specific fixes without predicting FPS from static counts. 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`,
+`publish_owned_item`, `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.
+
+Vehicle lifecycle: `get_started({ kind: "vehicle" })` serves the `helix-vehicles` skill (the
+workflow), `read_doc({ name: "vehicles" })` the HELIX Vehicle Contract (the rules), and
+`read_skill` the skill's references (source bridges for BeamNG, downloaded models, concepts and
+from-scratch builds; physics from real specs; audio; add-ons; publication; QA; a complete live
+reference package). New vehicle content follows the sealed Package workflow; the former vehicle
+Item-first MCP publisher routes are retired. `visual_qa_item` judges a candidate `packageVersion`. `item_thumbnail`
+re-renders (`action: "refresh"`, with `force` / `dryRun`) or replaces (`action: "set"`, `imagePath`) a
+published item's thumbnail in-process through the creator's own credentials.
+
+Avatar lifecycle: `get_started({ kind: "avatar" })` serves the `helix-avatars` skill: any source
+(VRM, generated image-to-3D, rigged game model, robot/CAD) to a published avatar — the
+`helix-humanoid@1` contract and all-LOD budgets, rigging, `helix/dynamics@1` physics bones for hair,
+tails, ears and cloth, faces, publish and version moves, and the motion-vs-control QA that catches
+what the gates miss. `import_character` takes `boneMap`, `fit`, `bake`, `lockBorder`, `ktxMode` and
+`provenance`; VRMs go through `bridge_import`.
+
+`read_skill` serves any first-party skill in `skills/` to agents that only have this server.
+
+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/{character-world,world-recipe,sdk,manifest,publishing,catalog}` — the agent
-documentation, served from `docs/`.
+`helix://docs/{continuum,character-world,world-recipe,scene-performance,sdk,items,purchases,manifest,publishing,catalog,vehicles}` —
+the agent documentation, served from `docs/`.
 
 ## Develop
 
@@ -41,6 +112,5 @@ npm run build   # tsc → dist/ (bin: dist/server.js)
 npm test        # boots the server over stdio and asserts the tools register
 ```
 
-This package is intentionally thin: it depends on `@hypersoniclabs/helix-cli` for all publish/validate/discovery
-logic, so the CLI and MCP can never drift. The `humanoid-character` system, its abilities, and
-asset-packs are authored in `helix-web-engine` and published to the catalog the agent discovers.
+The `humanoid-character` system, its abilities, and asset-packs are authored in
+`helix-web-engine` and published to the catalog the agent discovers.

package/dist/continuumCanary.d.ts

@@ -0,0 +1,17 @@
+type McpCanaryPublicationScope = {
+    package: {
+        id: string;
+    };
+    packagePublication?: {
+        visibility?: string;
+    };
+    listings: ReadonlyArray<{
+        listing: {
+            id: string;
+            visibility: string;
+        };
+    }>;
+};
+/** MCP carries no human confirmation, so ambiguous or public canary scope fails closed. */
+export declare function assertMcpCanaryPublicationScope(publications: ReadonlyArray<McpCanaryPublicationScope>): void;
+export {};

package/dist/continuumCanary.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertMcpCanaryPublicationScope = assertMcpCanaryPublicationScope;
+/** MCP carries no human confirmation, so ambiguous or public canary scope fails closed. */
+function assertMcpCanaryPublicationScope(publications) {
+    const publicListings = publications.flatMap((publication) => publication.listings
+        .filter(({ listing }) => listing.visibility === 'public')
+        .map(({ listing }) => listing.id));
+    const nonPrivatePackages = publications
+        .filter((publication) => publication.packagePublication?.visibility !== 'private')
+        .map(({ package: pkg }) => pkg.id);
+    if (publicListings.length > 0 || nonPrivatePackages.length > 0) {
+        throw new TypeError('MCP cannot authorize public Continuum Packages or Listings. Publish this canary as private/unlisted, ' +
+            'or have the human use the Creator CLI public-listing confirmation path.');
+    }
+}
+//# sourceMappingURL=continuumCanary.js.map

package/dist/continuumCanary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"continuumCanary.js","sourceRoot":"","sources":["../src/continuumCanary.ts"],"names":[],"mappings":";;AAOA,0EAiBC;AAlBD,2FAA2F;AAC3F,SAAgB,+BAA+B,CAC7C,YAAsD;IAEtD,MAAM,cAAc,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,EAAE,CAC1D,WAAW,CAAC,QAAQ;SACjB,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,KAAK,QAAQ,CAAC;SACxD,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CACpC,CAAC;IACF,MAAM,kBAAkB,GAAG,YAAY;SACpC,MAAM,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,kBAAkB,EAAE,UAAU,KAAK,SAAS,CAAC;SACjF,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACrC,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,IAAI,kBAAkB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/D,MAAM,IAAI,SAAS,CACjB,uGAAuG;YACrG,yEAAyE,CAC5E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/server.d.ts

@@ -1,2 +1,15 @@
 #!/usr/bin/env node
-export {};
+/**
+ * First line of every `cliDelegation` result, and a cross-repo CONTRACT: the
+ * Dreamer sandbox bridge matches on it to auto-run the command itself instead
+ * of handing the raw text to the model (`dreamer-worker`
+ * `src/mcp/bridgeClient.ts` → `detectDelegatedCommand`).
+ *
+ * That side cannot import this — separate package, separate deploy — so it
+ * keeps a pinned copy and its test asserts against this exact wording. Named
+ * here so the string has one owner and a grep finds both halves. Before this
+ * existed the worker matched a phrase that only ever appeared in a tool
+ * DESCRIPTION, so the auto-run never fired once and the agent shelled out to
+ * `npx …@latest` on its own (HYPR-5280). Change this and change that.
+ */
+export declare const DELEGATED_RESULT_MARKER = "DELEGATED \u2014 RETURNS A COMMAND, NOT DATA. Run this through the HELIX creator CLI. The MCP transport does not implement this feature:";