portals-mcp 1.3.2 → 1.3.4

package/dist/marketplace-client.d.ts

@@ -24,6 +24,12 @@ export interface MarketplaceItem {
     claimCount: number;
     acquireCount: number;
 }
+export interface MarketplaceGlbResolution {
+    glb: string | null;
+    source: "catalog_direct" | "user_inventory" | "room_build_items" | "unresolved";
+    attachedToRoomInventory: boolean;
+    reason?: string | undefined;
+}
 export interface MarketplaceFilter {
     query?: string | undefined;
     type?: string | undefined;
@@ -44,6 +50,8 @@ export interface ClaimResult {
     itemId: string;
     message?: string | undefined;
 }
+export declare function isMarketplaceAssetRoute(value: string | null | undefined): boolean;
+export declare function isRuntimeGlbUrl(value: string | null | undefined): boolean;
 export declare function clearMarketplaceCache(): void;
 export declare function searchMarketplace(filter?: MarketplaceFilter): Promise<MarketplaceItem[]>;
 export declare function getPackItems(packId: string): Promise<MarketplaceItem[]>;
@@ -116,4 +124,5 @@ export interface OwnershipCheck {
 export declare function verifyOwnership(cids: string[]): Promise<OwnershipCheck[]>;
 export declare function attachItemsToRoom(roomId: string, itemIds: string[]): Promise<AttachToRoomResult>;
 export declare function claimMarketplaceItem(itemId: string): Promise<ClaimResult>;
+export declare function resolveMarketplaceGlbUrl(item: MarketplaceItem, roomId?: string): Promise<MarketplaceGlbResolution>;
 //# sourceMappingURL=marketplace-client.d.ts.map

package/dist/marketplace-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"marketplace-client.d.ts","sourceRoot":"","sources":["../src/marketplace-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"marketplace-client.d.ts","sourceRoot":"","sources":["../src/marketplace-client.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,YAAY,CAAC;IAChF,uBAAuB,EAAE,OAAO,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;IAC9C,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAyBD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAOjF;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAQzE;AAkBD,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AA0DD,wBAAsB,iBAAiB,CAAC,MAAM,GAAE,iBAAsB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAkClG;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAK7E;AAED,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAGxF;AAED,wBAAsB,mBAAmB,IAAI,OAAO,CAAC;IACnD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC,CAcD;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CASrE;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAUhF;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACrC,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAkD/E;AAED,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA0CtG;AAED,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA8B/E;AAUD,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAiExH"}

package/dist/marketplace-client.js

@@ -1,7 +1,54 @@
 import fetch from "node-fetch";
+import { getAccessKey, isAuthenticated } from "./api.js";
 const API_BASE = process.env.API_BASE || "https://portals.to";
 const CACHE_TTL_MS = 60_000;
 let catalogueCache = null;
+function getRuntimeAccessKey() {
+    if (process.env.PORTALS_ACCESS_KEY)
+        return process.env.PORTALS_ACCESS_KEY;
+    if (!isAuthenticated())
+        return null;
+    try {
+        return getAccessKey();
+    }
+    catch {
+        return null;
+    }
+}
+function authHeaders() {
+    const headers = {};
+    const token = process.env.PORTALS_USER_TOKEN;
+    const accessKey = getRuntimeAccessKey();
+    if (token)
+        headers["Authorization"] = `Bearer ${token}`;
+    if (accessKey)
+        headers["x-access-key"] = accessKey;
+    return headers;
+}
+function jsonAuthHeaders() {
+    return { "Content-Type": "application/json", ...authHeaders() };
+}
+export function isMarketplaceAssetRoute(value) {
+    if (!value)
+        return false;
+    try {
+        return new URL(value, API_BASE).pathname.startsWith("/api/v2/marketplace/asset/");
+    }
+    catch {
+        return value.startsWith("/api/v2/marketplace/asset/");
+    }
+}
+export function isRuntimeGlbUrl(value) {
+    if (!value)
+        return false;
+    if (isMarketplaceAssetRoute(value))
+        return false;
+    const trimmed = value.trim();
+    if (trimmed.startsWith("http://") || trimmed.startsWith("https://") || trimmed.startsWith("~") || trimmed.startsWith("#")) {
+        return /\.glb(?:[?#]|$)/i.test(trimmed);
+    }
+    return false;
+}
 async function fetchCatalogue() {
     if (catalogueCache && Date.now() - catalogueCache.ts < CACHE_TTL_MS) {
         return catalogueCache.items;
@@ -156,7 +203,7 @@ export async function getUserInventory() {
     if (!token)
         return [];
     const res = await fetch(`${API_BASE}/api/v2/marketplace/my-items`, {
-        headers: { Authorization: `Bearer ${token}` },
+        headers: authHeaders(),
     });
     if (!res.ok)
         return [];
@@ -171,17 +218,10 @@ export async function getUserInventory() {
  * scene with AI so we know what assets the user actually has.
  */
 export async function getRoomBuildItems(roomId) {
-    const token = process.env.PORTALS_USER_TOKEN;
-    const accessKey = process.env.PORTALS_ACCESS_KEY;
     if (!roomId)
         return [];
-    const headers = {};
-    if (token)
-        headers["Authorization"] = `Bearer ${token}`;
-    if (accessKey)
-        headers["x-access-key"] = accessKey;
     try {
-        const res = await fetch(`${API_BASE}/api/v2/room/get-build-items?roomId=${encodeURIComponent(roomId)}`, { headers });
+        const res = await fetch(`${API_BASE}/api/v2/room/get-build-items?roomId=${encodeURIComponent(roomId)}`, { headers: authHeaders() });
         if (!res.ok)
             return [];
         const json = (await res.json());
@@ -199,7 +239,7 @@ export async function getRoomBuildItems(roomId) {
  */
 export async function verifyOwnership(cids) {
     const token = process.env.PORTALS_USER_TOKEN;
-    const accessKey = process.env.PORTALS_ACCESS_KEY;
+    const accessKey = getRuntimeAccessKey();
     if (!token && !accessKey) {
         // No auth — return unknowns (the caller decides how to proceed).
         return cids.map((cid) => ({
@@ -210,9 +250,7 @@ export async function verifyOwnership(cids) {
         }));
     }
     // Pull catalogue + user inventory in parallel.
-    const headers = {};
-    if (token)
-        headers["Authorization"] = `Bearer ${token}`;
+    const headers = authHeaders();
     const [inventoryRes, catalogue] = await Promise.all([
         token ? fetch(`${API_BASE}/api/v2/marketplace/my-items`, { headers }) : Promise.resolve(null),
         fetchCatalogue(),
@@ -248,18 +286,14 @@ export async function verifyOwnership(cids) {
 }
 export async function attachItemsToRoom(roomId, itemIds) {
     const token = process.env.PORTALS_USER_TOKEN;
-    const accessKey = process.env.PORTALS_ACCESS_KEY;
+    const accessKey = getRuntimeAccessKey();
     if (!token && !accessKey) {
-        return { ok: false, code: "AUTH_REQUIRED", message: "No Firebase token or access key in env.", attachedItemIds: [] };
+        return { ok: false, code: "AUTH_REQUIRED", message: "No Firebase token, access key env, or authenticated MCP access key available.", attachedItemIds: [] };
     }
     if (!roomId) {
         return { ok: false, code: "ROOM_ID_REQUIRED", message: "roomId is required.", attachedItemIds: [] };
     }
-    const headers = { "Content-Type": "application/json" };
-    if (token)
-        headers["Authorization"] = `Bearer ${token}`;
-    if (accessKey)
-        headers["x-access-key"] = accessKey;
+    const headers = jsonAuthHeaders();
     let existing = [];
     try {
         const settingsRes = await fetch(`${API_BASE}/api/v2/room/get-settings?roomID=${encodeURIComponent(roomId)}`, { headers });
@@ -324,3 +358,69 @@ export async function claimMarketplaceItem(itemId) {
         message: body.message,
     };
 }
+function matchBuildItem(items, itemId) {
+    return items.find((item) => item.id === itemId) ?? null;
+}
+function matchInventoryItem(items, itemId) {
+    return items.find((item) => item.itemId === itemId || item.id === itemId) ?? null;
+}
+export async function resolveMarketplaceGlbUrl(item, roomId) {
+    if (isRuntimeGlbUrl(item.glb)) {
+        return {
+            glb: item.glb,
+            source: "catalog_direct",
+            attachedToRoomInventory: false,
+        };
+    }
+    const inventoryItem = matchInventoryItem(await getUserInventory(), item.id);
+    if (inventoryItem?.glb && isRuntimeGlbUrl(inventoryItem.glb)) {
+        return {
+            glb: inventoryItem.glb,
+            source: "user_inventory",
+            attachedToRoomInventory: false,
+        };
+    }
+    if (!roomId) {
+        return {
+            glb: null,
+            source: "unresolved",
+            attachedToRoomInventory: false,
+            reason: isMarketplaceAssetRoute(item.glb)
+                ? "Catalog glb is a protected marketplace asset route; pass roomId so MCP can resolve the room build-palette CDN URL."
+                : "Catalog item did not include a runtime GLB URL.",
+        };
+    }
+    let buildItems = await getRoomBuildItems(roomId);
+    let buildItem = matchBuildItem(buildItems, item.id);
+    if (buildItem?.glb && isRuntimeGlbUrl(buildItem.glb)) {
+        return {
+            glb: buildItem.glb,
+            source: "room_build_items",
+            attachedToRoomInventory: false,
+        };
+    }
+    const attachResult = await attachItemsToRoom(roomId, [item.id]);
+    if (!attachResult.ok) {
+        return {
+            glb: null,
+            source: "unresolved",
+            attachedToRoomInventory: false,
+            reason: `Could not attach marketplace item to room inventory for URL resolution (${attachResult.code}${attachResult.message ? `: ${attachResult.message}` : ""}).`,
+        };
+    }
+    buildItems = await getRoomBuildItems(roomId);
+    buildItem = matchBuildItem(buildItems, item.id);
+    if (buildItem?.glb && isRuntimeGlbUrl(buildItem.glb)) {
+        return {
+            glb: buildItem.glb,
+            source: "room_build_items",
+            attachedToRoomInventory: true,
+        };
+    }
+    return {
+        glb: null,
+        source: "unresolved",
+        attachedToRoomInventory: true,
+        reason: "Item was attached to the room inventory, but get_room_build_items did not return a runtime .glb URL for it.",
+    };
+}

package/dist/resources/index/effects.json

@@ -39,6 +39,16 @@
         "Scale in relative mode is ADDITIVE (scale [1,1,1] adds 1 to each axis per trigger)"
       ]
     },
+    {
+      "$type": "SetTransform",
+      "category": "movement",
+      "parameters": {
+        "position": "array - optional [x,y,z] world position",
+        "rotation": "array - optional [x,y,z] Euler degrees",
+        "scale": "array - optional [x,y,z] scale"
+      },
+      "gotchas": ["Immediate local-player transform write. Include at least one of position, rotation, or scale."]
+    },
     {
       "$type": "PortalsAnimation",
       "category": "movement",
@@ -76,6 +86,82 @@
       "parameters": {},
       "gotchas": []
     },
+    {
+      "$type": "AddForceToCubeEffector",
+      "category": "physics",
+      "parameters": {
+        "fx": "float - impulse X",
+        "fy": "float - impulse Y",
+        "fz": "float - impulse Z",
+        "rel": "bool - true=force vector is local to item rotation"
+      },
+      "gotchas": ["Direct task effector only; not in ReactGUI UseEffector/PrepareEffector map. Works on ResizableCube and GLB-family physics items."]
+    },
+    {
+      "$type": "AddTorqueToCubeEffector",
+      "category": "physics",
+      "parameters": {
+        "tx": "float - rotational impulse X",
+        "ty": "float - rotational impulse Y",
+        "tz": "float - rotational impulse Z",
+        "rel": "bool - true=torque vector is local to item rotation"
+      },
+      "gotchas": ["Direct task effector only; not in ReactGUI UseEffector/PrepareEffector map. Works on ResizableCube and GLB-family physics items."]
+    },
+    {
+      "$type": "ExplosionForceCubeEffector",
+      "category": "physics",
+      "parameters": {
+        "f": "float - explosion impulse force",
+        "r": "float - explosion radius",
+        "u": "float - upward modifier",
+        "ox/oy/oz": "floats - origin offset from item position",
+        "aff": "bool - true=also affect nearby physics cubes"
+      },
+      "gotchas": ["Direct task effector only; not in ReactGUI UseEffector/PrepareEffector map."]
+    },
+    {
+      "$type": "SetCubeVelocityEffector",
+      "category": "physics",
+      "parameters": {
+        "vx/vy/vz": "floats - linear velocity",
+        "ax/ay/az": "floats - angular velocity",
+        "sl": "bool - set linear velocity",
+        "sa": "bool - set angular velocity",
+        "rel": "bool - true=vectors are local to item rotation"
+      },
+      "gotchas": ["Direct task effector only. Velocity assignment is most reliable when this client already owns the physics item."]
+    },
+    {
+      "$type": "ResetCubeVelocityEffector",
+      "category": "physics",
+      "parameters": {},
+      "gotchas": ["Direct task effector only. Stops linear and angular velocity on the owned physics item."]
+    },
+    {
+      "$type": "ToggleCubeGravityEffector",
+      "category": "physics",
+      "parameters": {
+        "g": "bool - true=use gravity, false=float"
+      },
+      "gotchas": ["Direct task effector only. Ensures physics is attached before changing gravity."]
+    },
+    {
+      "$type": "AttachToMouseCubeEffector",
+      "category": "physics",
+      "parameters": {
+        "snap": "bool - true=snap item bottom to placeable surfaces"
+      },
+      "gotchas": ["JS UseEffector name is AttachToMouse, while direct room-data $type is AttachToMouseCubeEffector."]
+    },
+    {
+      "$type": "DetachFromMouseCubeEffector",
+      "category": "physics",
+      "parameters": {
+        "save": "bool - true=persist final drop position when server permissions and item opt-in allow it"
+      },
+      "gotchas": ["JS UseEffector name is DetachFromMouse, while direct room-data $type is DetachFromMouseCubeEffector."]
+    },
     {
       "$type": "AddVelocityToPlayer",
       "category": "player",
@@ -235,7 +321,8 @@
       "category": "camera",
       "parameters": {
         "camState": "string — camera state name (matches CameraObject sn)",
-        "transitionSpeed": "float — transition speed"
+        "smoothTransition": "bool — blend to the new state, default true",
+        "transitionSpeed": "float — transition speed, default 6.0"
       },
       "gotchas": []
     },