sceneview-mcp 3.4.5 → 3.4.7

package/dist/index.js

@@ -11,6 +11,7 @@ import { MIGRATION_GUIDE } from "./migration.js";
 import { fetchKnownIssues } from "./issues.js";
 import { parseNodeSections, findNodeSection, listNodeTypes } from "./node-reference.js";
 import { PLATFORM_ROADMAP, BEST_PRACTICES, AR_SETUP_GUIDE, TROUBLESHOOTING_GUIDE } from "./guides.js";
+import { buildPreviewUrl, validatePreviewInput, formatPreviewResponse } from "./preview.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 let API_DOCS;
 try {
@@ -205,24 +206,32 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "render_3d_preview",
-            description: "Generates an interactive 3D preview link for a glTF/GLB model. Returns a URL to sceneview.github.io/preview that renders the model in the browser with orbit controls, AR support, and sharing. Use this when you want to show a 3D model to the user — paste the link in your response and they can click to see it live. Also works with any publicly accessible .glb URL.",
+            description: "Generates an interactive 3D preview link. Accepts a model URL, a SceneView code snippet, or both. Returns a URL to sceneview.github.io/preview that renders the model in the browser with orbit controls, AR support, and sharing. For model URLs: embeds a model-viewer link directly. For code snippets: shows the 3D preview with the code in a companion panel. Use this when you want to show a 3D model to the user — paste the link in your response and they can click to see it live.",
             inputSchema: {
                 type: "object",
                 properties: {
                     modelUrl: {
                         type: "string",
-                        description: "Public URL to a .glb or .gltf model file. Must be HTTPS and CORS-enabled.",
+                        description: "Public URL to a .glb or .gltf model file. Must be HTTPS and CORS-enabled. If omitted, a default model is used.",
+                    },
+                    codeSnippet: {
+                        type: "string",
+                        description: "SceneView code snippet (Kotlin or Swift) to display alongside the 3D preview in a companion panel. Useful when showing generated code together with a live preview.",
                     },
                     autoRotate: {
                         type: "boolean",
-                        description: "Auto-rotate the model (default: true)",
+                        description: "Auto-rotate the model (default: true).",
                     },
                     ar: {
                         type: "boolean",
-                        description: "Enable AR mode on supported devices (default: true)",
+                        description: "Enable AR mode on supported devices (default: true).",
+                    },
+                    title: {
+                        type: "string",
+                        description: "Custom title shown above the preview.",
                     },
                 },
-                required: ["modelUrl"],
+                required: [],
             },
         },
     ],
@@ -718,41 +727,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         // ── render_3d_preview ──────────────────────────────────────────────────
         case "render_3d_preview": {
             const modelUrl = request.params.arguments?.modelUrl;
-            const autoRotate = request.params.arguments?.autoRotate ?? true;
-            const ar = request.params.arguments?.ar ?? true;
-            if (!modelUrl) {
+            const codeSnippet = request.params.arguments?.codeSnippet;
+            const autoRotate = request.params.arguments?.autoRotate;
+            const ar = request.params.arguments?.ar;
+            const title = request.params.arguments?.title;
+            const validationError = validatePreviewInput(modelUrl, codeSnippet);
+            if (validationError) {
                 return {
-                    content: [{ type: "text", text: "Error: modelUrl is required. Provide a public HTTPS URL to a .glb or .gltf file." }],
+                    content: [{ type: "text", text: `Error: ${validationError}` }],
                     isError: true,
                 };
             }
-            const params = new URLSearchParams();
-            params.set("model", modelUrl);
-            if (!autoRotate)
-                params.set("rotate", "false");
-            if (!ar)
-                params.set("ar", "false");
-            const previewUrl = `https://sceneview.github.io/preview?${params.toString()}`;
-            return {
-                content: [{
-                        type: "text",
-                        text: `## 3D Preview
-
-**[Click to view the 3D model interactively →](${previewUrl})**
-
-The link opens an interactive 3D viewer where you can:
-- 🖱️ Drag to orbit, scroll to zoom
-- 📱 "View in AR" on mobile devices (ARCore/ARKit)
-- 🔗 Share the link with anyone
-
-**Preview URL:** ${previewUrl}
-
-**Model:** ${modelUrl}
-
----
-*Powered by SceneView — 3D & AR for every platform*`,
-                    }],
-            };
+            const result = buildPreviewUrl({ modelUrl, codeSnippet, autoRotate, ar, title });
+            const text = formatPreviewResponse(result);
+            return { content: [{ type: "text", text }] };
         }
         default:
             return {

package/dist/preview.js

@@ -0,0 +1,78 @@
+// ─── 3D Preview Link Generator ───────────────────────────────────────────────
+//
+// Generates embeddable preview URLs for sceneview.github.io/preview.
+// Two modes:
+//   1. Model URL → direct model-viewer embed link
+//   2. Code snippet → embed link with default model + code panel
+const PREVIEW_BASE = "https://sceneview.github.io/preview";
+const DEFAULT_MODEL_URL = "https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Assets/main/Models/DamagedHelmet/glTF-Binary/DamagedHelmet.glb";
+/**
+ * Build a sceneview.github.io/preview URL from the given options.
+ *
+ * - If `modelUrl` is supplied it is embedded directly.
+ * - If only `codeSnippet` is supplied a default model is used and the code is
+ *   passed via the `code` query parameter so the preview page can show it in a
+ *   companion panel.
+ * - If both are supplied the model URL takes priority and the code is included.
+ */
+export function buildPreviewUrl(options) {
+    const model = options.modelUrl || DEFAULT_MODEL_URL;
+    const hasCode = Boolean(options.codeSnippet?.trim());
+    const title = options.title || (hasCode && !options.modelUrl ? "SceneView Code Preview" : "3D Model Preview");
+    const params = new URLSearchParams();
+    params.set("model", model);
+    if (options.autoRotate === false)
+        params.set("rotate", "false");
+    if (options.ar === false)
+        params.set("ar", "false");
+    if (options.title)
+        params.set("title", options.title);
+    if (hasCode)
+        params.set("code", options.codeSnippet.trim());
+    const previewUrl = `${PREVIEW_BASE}?${params.toString()}`;
+    return { previewUrl, modelUrl: model, hasCode, title };
+}
+/**
+ * Validate preview input — at least one of modelUrl or codeSnippet must be provided.
+ */
+export function validatePreviewInput(modelUrl, codeSnippet) {
+    if (!modelUrl && !codeSnippet) {
+        return "At least one of `modelUrl` or `codeSnippet` is required.";
+    }
+    if (modelUrl) {
+        if (!modelUrl.startsWith("https://") && !modelUrl.startsWith("http://")) {
+            return "modelUrl must be an HTTP(S) URL.";
+        }
+        if (!/\.(glb|gltf)(\?|$)/i.test(modelUrl)) {
+            return "modelUrl should point to a .glb or .gltf file.";
+        }
+    }
+    return null;
+}
+/**
+ * Format the preview result as a rich text response for the MCP tool.
+ */
+export function formatPreviewResponse(result) {
+    const lines = [
+        `## ${result.title}`,
+        ``,
+        `**[Click to view the 3D model interactively \u2192](${result.previewUrl})**`,
+        ``,
+        `The link opens an interactive 3D viewer where you can:`,
+        `- Drag to orbit, scroll to zoom`,
+        `- "View in AR" on mobile devices (ARCore/ARKit)`,
+        `- Share the link with anyone`,
+        ``,
+        `**Preview URL:** ${result.previewUrl}`,
+        ``,
+        `**Model:** ${result.modelUrl}`,
+    ];
+    if (result.hasCode) {
+        lines.push(``);
+        lines.push(`*The code snippet is included in the preview page as a companion panel.*`);
+    }
+    lines.push(``);
+    lines.push(`---`);
+    lines.push(`*Powered by SceneView \u2014 3D & AR for every platform*`);
+    return lines.join("\n");
+}

package/llms.txt

@@ -2247,12 +2247,123 @@ ARSceneView.checkSupport { supported ->
 
 ---
 
+## Android XR (Planned)
+
+SceneView can be used inside Android XR's spatial layout system via the Jetpack XR SDK
+(Developer Preview). The integration embeds SceneView's `Scene {}` composable inside a
+`SpatialPanel`, giving full Filament rendering inside an XR spatial panel.
+
+**Dependencies (in addition to SceneView):**
+```kotlin
+implementation("androidx.xr.scenecore:scenecore:1.0.0-alpha12")
+implementation("androidx.xr.compose:compose:1.0.0-alpha12")
+```
+
+**Basic pattern:**
+```kotlin
+Subspace {
+    SpatialPanel(SubspaceModifier.width(1200.dp).height(800.dp)) {
+        val engine = rememberEngine()
+        val modelLoader = rememberModelLoader(engine)
+        Scene(modifier = Modifier.fillMaxSize(), engine = engine, modelLoader = modelLoader) {
+            rememberModelInstance(modelLoader, "models/helmet.glb")?.let {
+                ModelNode(modelInstance = it)
+            }
+        }
+    }
+}
+```
+
+Key XR composables: `Subspace`, `SpatialPanel`, `SpatialRow`, `SpatialColumn`, `Orbiter`,
+`SceneCoreEntity`. SceneCore entities: `GltfModelEntity`, `PanelEntity`, `AnchorEntity`,
+`SpatialEnvironment`. Status: **experimental / planned** — Jetpack XR SDK is alpha.
+
+---
+
+## visionOS Spatial Computing (Planned)
+
+SceneViewSwift targets visionOS 1+ via RealityKit. Spatial features are planned for future
+releases, building on the existing `SceneView` and node types.
+
+### Scene Types
+
+| Type | Style | Description | SceneViewSwift |
+|---|---|---|---|
+| Window | 2D | Standard SwiftUI window in shared space | `SceneView { }` (existing) |
+| Volume | 3D bounded | Fixed-size 3D container in shared space | `VolumetricSceneView` (planned) |
+| Immersive Space | `.mixed` | Virtual content blends with passthrough | `ImmersiveSceneView` (planned) |
+| Immersive Space | `.progressive` | Partial passthrough replacement | `ImmersiveSceneView` (planned) |
+| Immersive Space | `.full` | Fully virtual, passthrough off | `ImmersiveSceneView` (planned) |
+
+### Hand Tracking (visionOS 1+, Full Space required)
+
+ARKit `HandTrackingProvider` tracks 27 joints per hand at display refresh rate.
+Requires `NSHandsTrackingUsageDescription` in Info.plist and a `SpatialTrackingSession`.
+
+**Planned API:**
+```swift
+ImmersiveSceneView { root in /* content */ }
+    .handTracking(enabled: true)
+    .onHandUpdate { hands in
+        if let d = hands.jointDistance(.thumbTip, .indexFingerTip, hand: .right), d < 0.02 {
+            // Pinch detected
+        }
+    }
+```
+
+### Spatial Anchors
+
+`SpatialTrackingSession` (visionOS 2.0+) unlocks ARKit data in RealityKit: anchor
+geometry extents, real-world offset, and scene understanding mesh.
+
+**Planned API:**
+```swift
+// World anchor
+SpatialAnchorNode.world(position: SIMD3<Float>(0, 1, -2))
+
+// Plane anchor (on detected surface)
+SpatialAnchorNode.plane(alignment: .horizontal)
+
+// Hand anchor (attached to a joint)
+SpatialAnchorNode.hand(.right, joint: .indexFingerTip)
+```
+
+### Scene Understanding
+
+Real-time mesh of surroundings enabling collision, physics, surface classification
+(floor, wall, ceiling, table, seat, door, window), and environment occlusion.
+
+### Object Manipulation (visionOS 26)
+
+`ManipulationComponent` enables look, tap, drag, rotate, scale on entities with a
+single call. `EnvironmentBlendingComponent` for real-world occlusion.
+`MeshInstancesComponent` for efficient GPU instanced rendering.
+
+**Planned API:**
+```swift
+let model = try await ModelNode.load("models/chair.usdz")
+model.enableManipulation()  // look + grab + drag + rotate + scale via system gestures
+```
+
+### Cross-Platform Mapping (visionOS <-> Android XR)
+
+| Feature | visionOS | Android XR |
+|---|---|---|
+| Spatial container | Volume (`.volumetric`) | `SpatialPanel` |
+| Immersive mode | `ImmersiveSpace` | `SpatialEnvironment` |
+| Hand tracking | `HandTrackingProvider` | Jetpack XR hand tracking |
+| Spatial anchors | `WorldAnchor` | `AnchorEntity` (SceneCore) |
+| Scene understanding | Scene mesh + classification | Perception APIs |
+
+---
+
 ## Platform Coverage Summary
 
 | Platform | Renderer | Framework | Sample | Status |
 |---|---|---|---|---|
 | Android | Filament | Jetpack Compose | `samples/android-demo` | Stable |
 | Android TV | Filament | Compose TV | `samples/android-tv-demo` | Alpha |
+| Android XR | Filament + SceneCore | Compose for XR | — | Planned |
 | iOS | RealityKit | SwiftUI | `samples/ios-demo` | Alpha |
 | macOS | RealityKit | SwiftUI | via SceneViewSwift | Alpha |
 | visionOS | RealityKit | SwiftUI | via SceneViewSwift | Alpha |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sceneview-mcp",
-  "version": "3.4.5",
+  "version": "3.4.7",
   "mcpName": "io.github.sceneview/mcp",
   "description": "MCP server for SceneView — cross-platform 3D & AR SDK for Android and iOS. Give Claude the full SceneView SDK so it writes correct, compilable code.",
   "keywords": [
@@ -43,6 +43,7 @@
     "dist/migration.js",
     "dist/node-reference.js",
     "dist/samples.js",
+    "dist/preview.js",
     "dist/validator.js",
     "llms.txt"
   ],