@helix3/helix-mcp 0.2.2-helix3.14

package/docs/publishing.md

@@ -0,0 +1,42 @@
+# Publishing to HELIX Instant
+
+## The pipeline
+
+`publish_world` runs the full creator pipeline against the platform:
+
+1. **Local validation** — the bundle directory is checked with the exact rules the server enforces (manifest schema, slug format, entry exists, file types, size budget). `validate_world` runs the same check standalone.
+2. **World resolution** — the manifest `slug` is matched against your existing worlds; a new world is created on first publish. Re-publishing a slug creates the **next build** (builds are immutable; the newest finalized build is what players get).
+3. **Upload** — each file is uploaded to CDN storage via presigned URLs (size and content type are cryptographically pinned; a mismatched upload is rejected by storage itself).
+4. **Finalize** — the platform verifies every declared file landed byte-exact, then atomically activates the build. A draft world auto-publishes on its first successful build.
+5. You get back the **play URL** — shareable, instant, no install.
+
+## Login (human prerequisite)
+
+Publishing requires a creator account session. Agents cannot log in — the flow is interactive. If `whoami` says not logged in, ask the human to run:
+
+```bash
+npm i -g @hypersoniclabs/helix-cli   # NOT `npx helix` — that's an unrelated package
+helix login
+```
+
+Creator access is currently invite-only (curated launch); the account must have the creator flag.
+
+## Error semantics
+
+- Validation errors list every problem at once — fix all of them, rebuild, re-validate.
+- `409` on world creation: the slug is taken by another creator. Choose a different slug in `helix.json`.
+- "missing upload" / "size mismatch" at finalize: the build directory changed between validate and publish — rebuild and re-publish.
+- `401`/`403`: login expired or the account lacks the creator flag — back to the human.
+
+## After publishing
+
+- World page: `https://helix-instant-website-production.up.railway.app/w/<slug>`
+- Instant play: `https://helix-instant-website-production.up.railway.app/play/<slug>`
+- Title, content rating, mobile support, and `requiresAuth` on the world page all come from the manifest — re-publish to update them.
+
+## Keeping the toolchain current
+
+The `@helix` packages publish independently; call `check_for_updates` (or `helix doctor`) to see what's behind and get the exact update command.
+
+- **CLI and MCP** — run them via `npx -y @hypersoniclabs/helix-cli@latest` / `npx -y @hypersoniclabs/helix-mcp@latest` and they're always current (the MCP config already does this). A global install goes stale; refresh it with `npm i -g @hypersoniclabs/helix-cli@latest`.
+- **SDK** (`@hypersoniclabs/helix-sdk`, pinned in a world's `package.json`) — a `^0.x` range locks the minor, so a new minor isn't picked up by `npm update`. Bump the range and reinstall: `npm i @hypersoniclabs/helix-sdk@latest`.

package/docs/sdk.md

@@ -0,0 +1,117 @@
+# @hypersoniclabs/helix-sdk
+
+The HELIX Instant SDK. Worlds running on HELIX Instant use it for player identity today, and multiplayer / voice / wallet / inventory in upcoming versions. It is the **only** way a world talks to the platform — worlds never call platform APIs or internal services directly.
+
+> This document is the SDK contract. It is written to be sufficient for an AI agent to integrate a world without reading the SDK source.
+
+## Install
+
+```bash
+npm install @hypersoniclabs/helix-sdk
+```
+
+## Core concepts
+
+1. **Your world runs in a sandboxed iframe** inside the HELIX shell (the portal play page, or the `helix dev` shell during local development). The SDK talks to the shell via `postMessage`; the shell talks to the platform.
+2. **Identity is granted, not taken.** Your world receives a short-lived, world-scoped session that only unlocks the permissions declared in your `helix.json` manifest. You never see the player's platform credentials.
+3. **Login UI belongs to the shell.** Your world cannot render a login form — it *requests* login, and the shell overlays its own UI. This is deliberate (anti-phishing) and means you never handle passwords.
+4. **Standalone mode.** When the world is opened directly (e.g. `vite dev` without a shell), `init()` resolves with `embedded: false` and all identity APIs return `null`/`false`. Your world should still run — treat identity as an enhancement.
+
+## Quick start
+
+```ts
+import { Helix } from '@hypersoniclabs/helix-sdk';
+
+const { embedded, user, world } = await Helix.init(); // call once, before anything else
+
+if (user) {
+  greet(user.displayName ?? user.username);
+}
+
+// React to login/logout at any time (e.g. update the HUD):
+Helix.auth.onAuthChanged((user) => updateHud(user));
+
+// Prompt login at a moment that makes sense in your world:
+saveButton.onclick = async () => {
+  try {
+    const user = await Helix.auth.requestLogin(); // shell overlay; no page reload
+    await saveProgress(user.id);
+  } catch {
+    // player dismissed the login — keep playing, nothing is lost
+  }
+};
+```
+
+## API
+
+### `Helix.init(): Promise<HelixInitResult>`
+
+Performs the shell handshake. **Must be called once before any other API.** Safe to call again (returns the same state). Resolves within ~3s even with no shell present.
+
+```ts
+type HelixInitResult = {
+  embedded: boolean;              // false when running standalone (local dev)
+  world: { id: string; slug: string; title: string } | null;
+  user: HelixUser | null;         // null when not logged in
+};
+```
+
+### `Helix.auth.getUser(): Promise<HelixUser | null>`
+
+The current player, or `null` when unauthenticated. Requires the `auth.profile` permission in your manifest.
+
+```ts
+type HelixUser = {
+  id: string;          // stable player id (UUID) — use this as your save key
+  username: string;    // unique handle
+  displayName: string | null;
+};
+```
+
+### `Helix.auth.isAuthenticated(): boolean`
+
+Synchronous check.
+
+### `Helix.auth.requestLogin(): Promise<HelixUser>`
+
+Asks the shell to show its login overlay. Resolves with the user on success. Rejects when: the player dismisses the overlay (`'dismissed'`), no shell is present (standalone), or the request times out. **The world keeps running throughout — there is no reload, and your state is preserved.** If already logged in, resolves immediately.
+
+### `Helix.auth.onAuthChanged(cb: (user: HelixUser | null) => void): () => void`
+
+Subscribes to login/logout. Fires with the user on login and `null` on logout. Returns an unsubscribe function.
+
+### `Helix.getSessionToken(): string | null`
+
+The raw world-scoped session token (JWT, `aud: helix-instant-world`). Most worlds never need this; later SDK modules use it internally.
+
+### `Helix.avatar.getEquipped(): Promise<EquippedAvatar | null>`
+
+The local player's equipped **universal avatar** — the single character a world renders for them.
+`EquippedAvatar = { source: 'equipped' | 'auto' | 'default', itemId, glbUrl, skeleton }`. Resolves `null` for
+guests / standalone / any failure — the world falls back to the default body, never breaks. Feed it to
+`loadCharacterAssets`'s `avatar` option (single-player) or the `AvatarModelCache` (multiplayer) — see the
+character recipe §8 and the `hangout` template §3a. **Gate on `skeleton === 'helix-humanoid'`** (the
+`UNIVERSAL_AVATAR_SKELETON` export): only a converted avatar can be driven by the platform clips; the
+`loadCharacterAssets` `avatar` option does this gate for you. Call **after `Helix.init()`** and **before**
+character assets load — the body is bind-once. In multiplayer, remote players' avatars arrive on room state
+(`player.avatarUrl`, `''` = none) — you never look up another user's avatar yourself.
+
+## Manifest requirements
+
+Your bundle root must contain a `helix.json` manifest (see `@hypersoniclabs/helix-manifest`). To use the identity APIs, declare the permission:
+
+```json
+{
+  "helixVersion": "0.1",
+  "title": "My World",
+  "slug": "my-world",
+  "entry": "index.html",
+  "permissions": ["auth.profile"]
+}
+```
+
+Calling an API whose permission is not declared returns an error — permissions are enforced server-side on the session token, not just in the SDK.
+
+## Coming in later versions
+
+`Helix.multiplayer` (instances), `Helix.voice`, `Helix.wallet`, `Helix.inventory`, `Helix.cloudSave`, `Helix.leaderboards`. The shapes follow the same pattern: capability declared in the manifest → granted on the session → exposed as a namespace.

package/docs/world-recipe.md

@@ -0,0 +1,137 @@
+# HELIX Instant — World Project Recipe
+
+Follow this recipe exactly to generate a **publishable HELIX Instant world**. A world is a static web app (Vite-built) that runs sandboxed in the HELIX portal and talks to the platform only through `@hypersoniclabs/helix-sdk`.
+
+## Project layout
+
+```
+my-world/
+├── package.json
+├── vite.config.ts
+├── index.html
+├── public/
+│   └── helix.json        ← the manifest; lands at dist/ root on build
+└── src/
+    └── main.ts
+```
+
+## package.json
+
+```json
+{
+  "name": "my-world",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "@hypersoniclabs/helix-sdk": "^0.1.0",
+    "three": "^0.172.0"
+  },
+  "devDependencies": {
+    "@types/three": "^0.172.0",
+    "typescript": "~5.7.3",
+    "vite": "^6.0.0"
+  }
+}
+```
+
+Three.js is the usual choice but any web stack works — the only hard requirements are the manifest, the SDK, and a static `dist/` output.
+
+## vite.config.ts — `base: './'` is REQUIRED
+
+```ts
+import { defineConfig } from 'vite';
+
+// base './' makes asset URLs relative so the bundle loads from any CDN path.
+export default defineConfig({
+  base: './',
+  build: { target: 'es2022' },
+});
+```
+
+## public/helix.json — the manifest
+
+```json
+{
+  "helixVersion": "0.1",
+  "title": "My World",
+  "slug": "my-world",
+  "entry": "index.html",
+  "maxPlayers": 1,
+  "permissions": ["auth.profile"],
+  "supportsMobile": true,
+  "requiresAuth": false,
+  "contentRating": "everyone"
+}
+```
+
+Rules that commonly bite:
+- `slug`: 3–50 chars, lowercase letters/digits/hyphens, no leading/trailing hyphen, **globally unique**. Pick something distinctive.
+- `entry` must exist in the built output and be an `.html` file.
+- Only declare permissions you use; `auth.profile` is the only one in v0.1.
+- Read `helix://docs/manifest` for every field and the bundle limits.
+
+## index.html
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>My World</title>
+    <style>html, body { margin: 0; height: 100%; overflow: hidden; background: #0a0a12; }</style>
+  </head>
+  <body>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+
+## src/main.ts — SDK integration pattern
+
+```ts
+import * as THREE from 'three';
+import { Helix } from '@hypersoniclabs/helix-sdk';
+import type { HelixUser } from '@hypersoniclabs/helix-sdk'; // type-only import — required
+
+// 1. Build your scene/game first so the world renders even without identity.
+
+// 2. Initialize the SDK once, early:
+const { embedded, user } = await Helix.init();
+
+// 3. Use identity as an enhancement:
+if (user) {
+  // greet the player: user.username, user.displayName, user.id (stable save key)
+}
+
+// 4. React to login/logout while running:
+Helix.auth.onAuthChanged((nextUser: HelixUser | null) => {
+  // update HUD / game state — fires on overlay login AND logout
+});
+
+// 5. Offer login at a natural moment (never required to render):
+// try { await Helix.auth.requestLogin(); } catch { /* player declined — fine */ }
+```
+
+Hard-won specifics:
+- `import type { HelixUser }` — it is a type-only export; a value import breaks the build.
+- The world MUST run standalone (`npm run dev` with no shell): `embedded` is false there and identity APIs return null. Never block rendering on identity unless the manifest sets `requiresAuth: true`.
+- Never render your own login form — call `Helix.auth.requestLogin()` and the portal overlays the real one.
+
+## Build, validate, publish
+
+```bash
+npm install
+npm run build          # → dist/ (contains helix.json, index.html, assets/)
+```
+
+Then use the MCP tools, in order:
+1. `validate_world` with the **absolute path to `dist/`** — fix every reported problem.
+2. `whoami` — confirm a creator login exists (if not, the human must run `helix login`).
+3. `publish_world` with the same dist path — returns the public play URL.
+
+Budget: ≤ 200 files, ≤ 25 MB per file, ≤ 50 MB total. Allowed types include html/js/css/json/wasm, images (png/jpg/webp/svg/ktx2), models (glb/gltf/bin), audio (mp3/ogg/wav), fonts.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@helix3/helix-mcp",
+  "version": "0.2.2-helix3.14",
+  "description": "HELIX Instant MCP server — gives AI coding agents the platform contract: world recipes, manifest schema, validation, catalog discovery, and publishing.",
+  "type": "commonjs",
+  "main": "dist/server.js",
+  "bin": {
+    "helix-mcp": "dist/server.js"
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint \"src/**/*.ts\"",
+    "test": "node scripts/smoke.mjs"
+  },
+  "dependencies": {
+    "@hypersoniclabs/helix-cli": "npm:@helix3/helix-cli@0.1.4-helix3.24",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "~5.7.3"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}