portals-mcp 1.3.4 → 1.3.6

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`.