@hypersoniclabs/helix-mcp 0.2.1

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": "@hypersoniclabs/helix-mcp",
+  "version": "0.2.1",
+  "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": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "~5.7.3"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}