portals-mcp 1.3.6 → 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "portals-mcp",
-  "version": "1.3.6",
-  "description": "AI-first MCP server for Portals room workflows",
+  "version": "1.3.7",
+  "description": "MCP server that turns AI assistants into game developers — prompt to playable 3D multiplayer browser game on Portals",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -40,19 +40,30 @@
   },
   "keywords": [
     "mcp",
-    "portals",
-    "ai",
+    "mcp-server",
     "model-context-protocol",
+    "ai",
+    "game",
+    "game-development",
+    "game-builder",
+    "gamedev",
     "3d",
-    "game"
+    "multiplayer",
+    "webgl",
+    "portals"
   ],
-  "author": "",
+  "author": "Portals (https://theportal.to)",
   "license": "ISC",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/portals-labs/vibes.git",
     "directory": "portals-mcp-server"
   },
+  "homepage": "https://github.com/portals-labs/vibes/tree/master/portals-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/portals-labs/vibes/issues"
+  },
+  "mcpName": "io.github.portals-labs/portals-mcp",
   "engines": {
     "node": ">=18"
   },