portals-mcp 1.3.5 → 1.3.7

package/README.md

@@ -1,37 +1,90 @@
 # portals-mcp
 
-An [MCP](https://modelcontextprotocol.io) server that turns AI assistants into game designers for the [Portals](https://portals.to) 3D platform. Any LLM that speaks MCP can build interactive rooms, wire up game logic, and iterate on designs using natural language.
+**Prompt → playable 3D multiplayer game in the browser.**
+
+[![npm version](https://img.shields.io/npm/v/portals-mcp)](https://www.npmjs.com/package/portals-mcp)
+[![npm downloads](https://img.shields.io/npm/dw/portals-mcp)](https://www.npmjs.com/package/portals-mcp)
+[![license](https://img.shields.io/npm/l/portals-mcp)](#license)
+
+`portals-mcp` is an [MCP](https://modelcontextprotocol.io) server that turns Claude, Cursor, and any MCP-capable AI assistant into a game developer on [Portals](https://theportal.to). Describe the game you want; the assistant builds the scene, wires the game logic, generates 3D models, textures, music, and sound effects, and hands you a link anyone can play instantly — multiplayer, in the browser, no engine or build step.
+
+<!-- DEMO GIF: docs/demo.gif — record with the shot list below, keep it <60s, ~800px wide, looping.
+  Shot list (prompt → playable game in under 60 seconds):
+  1. 0–5s   MCP client (Claude Code or Cursor) with the prompt typed: "Build a neon parkour course with a timer and a win screen" — hit enter.
+  2. 5–25s  Tools firing in the chat: create_room, apply_operations, text_to_3d_model — fast cuts, no dead air.
+  3. 25–40s render_scene screenshot appears in chat; assistant iterates ("raising the far platforms").
+  4. 40–55s Cut to the browser: the room URL opens, avatar spawns and plays the course.
+  5. 55–60s Second avatar joins (multiplayer beat), room URL overlaid on screen.
+  Uncomment the image line below once docs/demo.gif exists:
+-->
+<!-- ![Demo: prompt to playable 3D game in under 60 seconds](docs/demo.gif) -->
 
 ## Quick Start
 
-### 1. Run
+[![Add portals MCP server to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=portals&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInBvcnRhbHMtbWNwQGxhdGVzdCJdfQ%3D%3D)
+
+Run it directly:
+
+```bash
+npx -y portals-mcp@latest
+```
+
+### Claude Code
 
 ```bash
-npx portals-mcp@latest
+claude mcp add portals -- npx -y portals-mcp@latest
 ```
 
-### 2. Configure your MCP client
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
 
 ```json
 {
   "mcpServers": {
     "portals": {
       "command": "npx",
-      "args": ["portals-mcp"]
+      "args": ["-y", "portals-mcp@latest"]
     }
   }
 }
 ```
 
-### 3. Bootstrap a session
+### Cursor
 
-1. Call `authenticate`. Alternatively, set `PORTALS_ACCESS_KEY` in a `.env` file next to your project to skip the browser prompt.
-2. Call `get_context` with a task description for targeted specs, gotchas, and recipes.
-3. For gameplay mechanics, call `resolve_gameplay_capability` or `plan_gameplay_mechanic` before making platform claims.
-4. Use `apply_operations` for scoped edits or `set_room_data` for full-snapshot replacement.
+Use the button above, or add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "portals": {
+      "command": "npx",
+      "args": ["-y", "portals-mcp@latest"]
+    }
+  }
+}
+```
+
+### Environment variables
+
+All optional — with no configuration the server opens a browser sign-in on first use.
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PORTALS_ACCESS_KEY` | No | Portals access key. Set it (e.g. in a `.env` file next to your project) to skip the browser sign-in prompt. |
+| `PORTALS_ROOM_ID` | No | Default room ID used when a tool call doesn't specify one. |
+| `PORTALS_DISABLE_TELEMETRY` | No | Set to `1` to disable anonymous usage telemetry. |
+
+### First session
+
+1. Ask your assistant to build something: *"Create a mini golf course with a scoreboard."* It will call `authenticate` (browser sign-in) the first time.
+2. Behind the scenes the assistant calls `get_context` for targeted specs, gotchas, and recipes, and `resolve_gameplay_capability` / `plan_gameplay_mechanic` before making platform claims.
+3. Edits land via `apply_operations` (scoped) or `set_room_data` (full snapshot); `render_scene` screenshots let it check its own work.
 
 ## Tools
 
+51 tools across authentication, marketplace assets, room building, scene design, live-game control, and AI asset generation.
+
 ### Authentication & Discovery
 
 | Tool | Description |
@@ -44,6 +97,20 @@ npx portals-mcp@latest
 | `plan_gameplay_mechanic` | Return a compact implementation contract with required capabilities, objects, variables, triggers, validation, risks, and sources |
 | `search_recipes` | Search recipe manifest by keywords, tags, and patterns |
 
+### Marketplace & Inventory
+
+| Tool | Description |
+|------|-------------|
+| `search_marketplace` | Search the Portals creator marketplace for assets (3D models, sounds, packs) |
+| `get_pack_items` | List the items contained in a marketplace pack |
+| `list_marketplace_facets` | List marketplace catalogue facets (categories, themes, visual styles, biomes, types) |
+| `get_user_inventory` | List assets the signed-in user has claimed or purchased |
+| `claim_marketplace_item` | Claim a free marketplace item into the user's inventory |
+| `place_marketplace_items` | Claim a batch of marketplace items and compose the ops to place them in the room |
+| `get_room_build_items` | List every item available in the room's in-game build palette |
+| `add_to_room_inventory` | Add marketplace items or packs to a room's build inventory |
+| `wire_locked_door` | Compose the ops to wire a locked-door mechanic between a key item and a door item |
+
 ### Room Management
 
 | Tool | Description |
@@ -56,6 +123,7 @@ npx portals-mcp@latest
 | `simulate_trigger_zone_input` | Audit and simulate Trigger `pressBtn` / `keyCode` press-inside-zone behavior |
 | `query_room` | Query room data for specific items, logic, or structure |
 | `update_room_settings` | Modify name, description, image, privacy, loading screens |
+| `set_room_settings` | Update only scene settings (lighting, skybox, fog, movement, avatars, voice chat) |
 
 ### Building
 
@@ -90,15 +158,22 @@ npx portals-mcp@latest
 | `change_task_state` | Activate, complete, or reset tasks in a live game |
 | `get_runtime_data` | Fetch live runtime variables and JS effector results |
 
-### Generated Assets
+### AI-Generated Assets
 
 | Tool | Description |
 |------|-------------|
 | `text_to_3d_model` | Generate a 3D model from text |
 | `image_to_3d_model` | Generate a 3D model from an image |
 | `check_3d_model_task` | Poll 3D model generation status |
+| `list_generated_3d_models` | List generated 3D models for the current user |
+| `generate_ai_image` | Generate an image from a text prompt |
+| `list_generated_images` | List generated images for the current user |
+| `generate_ai_texture` | Generate a seamless PBR texture from a text prompt |
+| `list_generated_textures` | List generated textures for the current user |
 | `text_to_speech` | Generate speech audio |
+| `list_voices` | List available text-to-speech voices |
 | `generate_sound_effect` | Generate sound effect audio |
+| `generate_music` | Generate an instrumental or vocal music track from a text prompt |
 | `list_generated_sounds` | List generated sounds for the current user |
 
 ## Resources

package/dist/resources/ai/bootstrap.json

@@ -1,57 +1,57 @@
-{
-  "format": "portals-mcp-ai-bootstrap",
-  "version": "4.0.0",
-  "mode": "ai-first",
-  "knowledge_architecture": {
-    "primary": "Call get_context with a description of your task. It returns inline specs, syntax, gotchas, and recipe matches — everything you need in one call.",
-    "fast_path": "For simple queries (item fields, trigger types, effect schemas), call lookup(term) — returns the spec directly in ~100 tokens.",
-    "deep_dive": "docs://ref/*, docs://logic/*, docs://recipes/* — available for detailed reference when the inline context from get_context isn't enough."
-  },
-  "build_policy": {
-    "default_ambition": "impressive",
-    "principle": "When uncertain about scale, build 5-10x more than the minimum viable version. Players remember abundance, not efficiency.",
-    "anti_patterns": [
-      "Building a handful of something when the request implies abundance",
-      "Creating a 'demo' when a full experience was requested",
-      "Defaulting to the smallest number that technically works"
-    ]
-  },
-  "policy": {
-    "optimize_for": [
-      "accuracy_first",
-      "minimum_context_tokens",
-      "predictable_outputs",
-      "tool_first_execution"
-    ],
-    "game_bridge": [
-      "Call connect_to_game after authentication — no roomId needed, the game client provides it via the WS bridge confirmation",
-      "Call poll_game_events after builds or when expecting user interaction in-game (Ctrl/Cmd+click for items, Shift+click for locations)",
-      "Events: item_ctrl_clicked (Ctrl/Cmd+click — roomItemId), location_selected (Shift+click — position data)"
-    ],
-    "avoid": [
-      "Building without calling get_context first — Portals has specific syntax that you cannot guess",
-      "Loading all resources upfront — use get_context for targeted knowledge, lookup for quick facts",
-      "Reading large guides when a lookup or get_context answers the question",
-      "Writing external Python scripts for room generation — use apply_operations for all builds, including complex ones with 200+ items",
-      "Parsing unstructured log output for control flow — always branch on ok/error.code",
-      "Skipping post-write verification — always get_room_data after set_room_data",
-      "Ignoring game events — always poll_game_events after user says they interacted in-game"
-    ],
-    "testing_workflow": [
-      "After building logic, TEST it live using this flow:",
-      "1. connect_to_game — establish the WS bridge to the live game",
-      "2. get_runtime_data — check initial variable state, confirm init tasks ran",
-      "3. change_task_state with effectorId — trigger effectors programmatically to simulate player actions (e.g. button clicks, triggers)",
-      "4. get_runtime_data — verify variables changed as expected",
-      "5. render_scene — take a screenshot to visually verify displayHtml overlays and scene state",
-      "TIP: Create hidden test helper items (add_item_with_logic) with known effector IDs like 'test-ready-up' that call SetVariable to trigger your reactive logic. This lets you test without needing the user to click in-game.",
-      "TIP: Run get_runtime_data and render_scene in parallel for faster test cycles."
-    ],
-    "ai_feedback": [
-      "REQUIRED: Every call to set_room_data and apply_operations MUST include the feedback parameter. This is not optional — the tool will reject calls without it.",
-      "The feedback parameter requires: confidence (1-5), and at least one of: what_worked, guesses, doc_gaps, ambiguity_flags, recipe_requests, or suspected_errors.",
-      "Report honestly — low confidence (1-2) triggers automatic gap detection, suspected_errors flags doc inaccuracies for review, what_worked helps rank useful docs higher.",
-      "This is AI-submitted feedback, not user-reported. You assess your own confidence and report what you observed. Do NOT ask the user to rate pushes."
-    ]
-  }
-}
+{
+  "format": "portals-mcp-ai-bootstrap",
+  "version": "4.0.0",
+  "mode": "ai-first",
+  "knowledge_architecture": {
+    "primary": "Call get_context with a description of your task. It returns inline specs, syntax, gotchas, and recipe matches — everything you need in one call.",
+    "fast_path": "For simple queries (item fields, trigger types, effect schemas), call lookup(term) — returns the spec directly in ~100 tokens.",
+    "deep_dive": "docs://ref/*, docs://logic/*, docs://recipes/* — available for detailed reference when the inline context from get_context isn't enough."
+  },
+  "build_policy": {
+    "default_ambition": "impressive",
+    "principle": "When uncertain about scale, build 5-10x more than the minimum viable version. Players remember abundance, not efficiency.",
+    "anti_patterns": [
+      "Building a handful of something when the request implies abundance",
+      "Creating a 'demo' when a full experience was requested",
+      "Defaulting to the smallest number that technically works"
+    ]
+  },
+  "policy": {
+    "optimize_for": [
+      "accuracy_first",
+      "minimum_context_tokens",
+      "predictable_outputs",
+      "tool_first_execution"
+    ],
+    "game_bridge": [
+      "Call connect_to_game after authentication — no roomId needed, the game client provides it via the WS bridge confirmation",
+      "Call poll_game_events after builds or when expecting user interaction in-game (Ctrl/Cmd+click for items, Shift+click for locations)",
+      "Events: item_ctrl_clicked (Ctrl/Cmd+click — roomItemId), location_selected (Shift+click — position data)"
+    ],
+    "avoid": [
+      "Building without calling get_context first — Portals has specific syntax that you cannot guess",
+      "Loading all resources upfront — use get_context for targeted knowledge, lookup for quick facts",
+      "Reading large guides when a lookup or get_context answers the question",
+      "Writing external Python scripts for room generation — use apply_operations for all builds, including complex ones with 200+ items",
+      "Parsing unstructured log output for control flow — always branch on ok/error.code",
+      "Skipping post-write verification — always get_room_data after set_room_data",
+      "Ignoring game events — always poll_game_events after user says they interacted in-game"
+    ],
+    "testing_workflow": [
+      "After building logic, TEST it live using this flow:",
+      "1. connect_to_game — establish the WS bridge to the live game",
+      "2. get_runtime_data — check initial variable state, confirm init tasks ran",
+      "3. change_task_state with effectorId — trigger effectors programmatically to simulate player actions (e.g. button clicks, triggers)",
+      "4. get_runtime_data — verify variables changed as expected",
+      "5. render_scene — take a screenshot to visually verify displayHtml overlays and scene state",
+      "TIP: Create hidden test helper items (add_item_with_logic) with known effector IDs like 'test-ready-up' that call SetVariable to trigger your reactive logic. This lets you test without needing the user to click in-game.",
+      "TIP: Run get_runtime_data and render_scene in parallel for faster test cycles."
+    ],
+    "ai_feedback": [
+      "REQUIRED: Every call to set_room_data and apply_operations MUST include the feedback parameter. This is not optional — the tool will reject calls without it.",
+      "The feedback parameter requires: confidence (1-5), and at least one of: what_worked, guesses, doc_gaps, ambiguity_flags, recipe_requests, or suspected_errors.",
+      "Report honestly — low confidence (1-2) triggers automatic gap detection, suspected_errors flags doc inaccuracies for review, what_worked helps rank useful docs higher.",
+      "This is AI-submitted feedback, not user-reported. You assess your own confidence and report what you observed. Do NOT ask the user to rate pushes."
+    ]
+  }
+}

package/dist/resources/ai/contracts/tool-output-envelope.json

@@ -1,35 +1,35 @@
-{
-  "format": "portals-mcp-tool-output-envelope",
-  "version": "1.0.0",
-  "description": "Canonical response envelope used by all MCP tools.",
-  "schema": {
-    "success": {
-      "ok": true,
-      "action": "string",
-      "summary": "string",
-      "data": "object",
-      "next_steps": [
-        "string"
-      ]
-    },
-    "error": {
-      "ok": false,
-      "action": "string",
-      "summary": "string",
-      "error": {
-        "code": "string",
-        "message": "string",
-        "details": "object (optional)"
-      },
-      "next_steps": [
-        "string"
-      ]
-    }
-  },
-  "required_parsing_rules": [
-    "Always parse as JSON from content[0].text.",
-    "Gate behavior on ok=true/false before reading data.",
-    "Use error.code for remediation routing.",
-    "Treat next_steps as actionable suggestions, not guaranteed prerequisites."
-  ]
-}
+{
+  "format": "portals-mcp-tool-output-envelope",
+  "version": "1.0.0",
+  "description": "Canonical response envelope used by all MCP tools.",
+  "schema": {
+    "success": {
+      "ok": true,
+      "action": "string",
+      "summary": "string",
+      "data": "object",
+      "next_steps": [
+        "string"
+      ]
+    },
+    "error": {
+      "ok": false,
+      "action": "string",
+      "summary": "string",
+      "error": {
+        "code": "string",
+        "message": "string",
+        "details": "object (optional)"
+      },
+      "next_steps": [
+        "string"
+      ]
+    }
+  },
+  "required_parsing_rules": [
+    "Always parse as JSON from content[0].text.",
+    "Gate behavior on ok=true/false before reading data.",
+    "Use error.code for remediation routing.",
+    "Treat next_steps as actionable suggestions, not guaranteed prerequisites."
+  ]
+}

package/dist/resources/guide/rules-and-conventions.md

@@ -1,13 +1,13 @@
-# Rules and Conventions
-
-## Core Rules
-
-- **Never read snapshot.json into context.** Use `room_index.md` for overview, query tools for specific items. See `docs://reference/room-index`.
-- **Design before building.** Never skip to generating items.
-- **Always read before writing.** MCP write tools replace entire objects — call `get_room_data` first.
-- **Save everything locally.** Design docs, scripts, snapshots — all in `games/{room-id}/`.
-- **Build with apply_operations.** Use bulk operations for complex builds, `add_item_with_logic` for items with interactions, and `add_component` for common patterns.
-- **Always use the full asset catalog workflow for GLB placement.** See `docs://reference/glb-asset-catalog`.
-- **Always search recipes first.** Use `search_recipes` before designing or building any mechanic.
-- **Test your logic live.** After building, use `connect_to_game` → `get_runtime_data` to verify variables, `change_task_state` to trigger effectors, and `render_scene` to screenshot the result. Create test helper items with known effector IDs to simulate player actions programmatically.
-- **Sync before overwriting.** If a user made manual changes, run `sync_room` before pushing. See `docs://guide/workflow-steps`.
+# Rules and Conventions
+
+## Core Rules
+
+- **Never read snapshot.json into context.** Use `room_index.md` for overview, query tools for specific items. See `docs://reference/room-index`.
+- **Design before building.** Never skip to generating items.
+- **Always read before writing.** MCP write tools replace entire objects — call `get_room_data` first.
+- **Save everything locally.** Design docs, scripts, snapshots — all in `games/{room-id}/`.
+- **Build with apply_operations.** Use bulk operations for complex builds, `add_item_with_logic` for items with interactions, and `add_component` for common patterns.
+- **Always use the full asset catalog workflow for GLB placement.** See `docs://reference/glb-asset-catalog`.
+- **Always search recipes first.** Use `search_recipes` before designing or building any mechanic.
+- **Test your logic live.** After building, use `connect_to_game` → `get_runtime_data` to verify variables, `change_task_state` to trigger effectors, and `render_scene` to screenshot the result. Create test helper items with known effector IDs to simulate player actions programmatically.
+- **Sync before overwriting.** If a user made manual changes, run `sync_room` before pushing. See `docs://guide/workflow-steps`.