portals-mcp

An MCP server that turns AI assistants into game designers for the Portals 3D platform. Any LLM that speaks MCP can build interactive rooms, wire up game logic, and iterate on designs using natural language.

Quick Start

1. Run

npx portals-mcp@latest

2. Configure your MCP client

{
  "mcpServers": {
    "portals": {
      "command": "npx",
      "args": ["portals-mcp"]
    }
  }
}

3. Bootstrap a session

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.

Tools

Authentication & Discovery

| Tool | Description | |------|-------------| | authenticate | Authenticate with Portals access key or browser flow | | get_help | Setup/workflow guidance with matching docs resources | | get_context | Returns targeted specs, syntax references, gotchas, recipes, and suggested tools | | lookup | Fast knowledge lookup for items, triggers, effects, systems, recipes | | resolve_gameplay_capability | Classify gameplay requests as supported directly, workaround, unsupported, or unknown | | 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 |

Room Management

| Tool | Description | |------|-------------| | create_room | Create from 18 templates (art-gallery, blank, spaceship, etc.) | | duplicate_room | Clone a room with all data | | get_room_data | Download room snapshot to temp JSON | | inspect_room_data | Summarize room-data counts, item types, variables, triggers/actions, and warnings without dumping full JSON | | query_room | Query room data for specific items, logic, or structure | | update_room_settings | Modify name, description, image, privacy, loading screens |

Building

| Tool | Description | |------|-------------| | set_room_data | Replace entire room data (full snapshot) | | apply_operations | Targeted ops: add_item, modify_item, remove_item, add_logic_task, clear_logic_tasks, add_quest, remove_quest, add_component |

Assets

| Tool | Description | |------|-------------| | upload_glb | Upload one .glb file or all .glb files in a folder | | upload_image | Upload one image file or all supported image files in a folder |

Scene Design

| Tool | Description | |------|-------------| | analyze_scene | Spatial composition analysis — zones, relationships, design checks | | render_scene | Screenshot of the live 3D scene via the game's MCP camera | | compare_scene | Before/after snapshot diff | | position_camera | Compute optimal camera placement to frame one or more items | | record_video | Record a video fly-through from a CameraObject |

Live Game Connection

| Tool | Description | |------|-------------| | connect_to_game | Connect to a live game client via WebSocket bridge | | poll_game_events | Poll for events from the live game (Ctrl+Click items, Shift+Click locations) | | 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

| 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 | | text_to_speech | Generate speech audio | | generate_sound_effect | Generate sound effect audio | | list_generated_sounds | List generated sounds for the current user |

Resources

The server bundles ~148 docs:// resources covering item specs, workflow guides, recipes, harness grounding data, and more. Resources are served from the package — no external docs repo required.

| Category | URI Pattern | Count | Examples | |----------|-------------|-------|----------| | Reference specs | docs://ref/* | 40 | 26 item specs, systems, interactions, components | | Extended reference | docs://reference/* | 17 | Full API docs, cameras, movement, quests | | Python tools & libs | docs://python/* | 27 | apply_ops, query_room, portals_core, portals_effects | | Recipes | docs://recipes/* | 18 | Dice roll, board game, keypad, side-scroller, leaderboard, cutscene camera | | Workflows | docs://workflows/* | 13 | Scene design, validation, quality review, asset pipeline | | Indexes | docs://index/* | 5 | Items, triggers, effects, knowledge map | | Logic & scripting | docs://logic/* | 5 | JS reference, expressions, multiplayer, string variables | | Guides | docs://guide/* | 3 | Rules & conventions, workflow steps | | AI bootstrap | docs://ai/* | 3 | Execution policy, tool output contracts | | Harness grounding | docs://harness/* | — | Capabilities, limitations, patterns, response contract, eval fixtures | | Architecture | docs://architecture/* | — | Harness architecture assessment and migration plan | | Usage rules | docs://usage-rules | 1 | Tool roles & error handling | | Catalog | docs://catalog | — | JSON index of all resource URIs |

Testing

npm test
npm run build
npm run test:mcp-client

Harness-specific checks:

npm run check:harness
npm run check:harness-package
npm run eval:harness

Shared Harness Core

The harness grounding layer is available as an independently buildable package under packages/harness-core:

import { resolveGameDevRequest } from "@portals/harness-core";

The MCP package also exposes a compatibility subpath:

import { resolveGameDevRequest } from "portals-mcp/harness-core";

Use @portals/harness-core as the target dependency for product-native harness services once it is published or wired internally.

License

ISC