sceneview-mcp 3.2.0 → 3.4.0

package/dist/index.js

@@ -10,6 +10,7 @@ import { validateCode, formatValidationReport } from "./validator.js";
 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";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 let API_DOCS;
 try {
@@ -19,14 +20,14 @@ catch {
     API_DOCS = "SceneView API docs not found. Run `npm run prepare` to bundle llms.txt.";
 }
 const NODE_SECTIONS = parseNodeSections(API_DOCS);
-const server = new Server({ name: "@sceneview/mcp", version: "3.2.0" }, { capabilities: { resources: {}, tools: {} } });
+const server = new Server({ name: "@sceneview/mcp", version: "3.4.0" }, { capabilities: { resources: {}, tools: {} } });
 // ─── Resources ───────────────────────────────────────────────────────────────
 server.setRequestHandler(ListResourcesRequestSchema, async () => ({
     resources: [
         {
             uri: "sceneview://api",
             name: "SceneView API Reference",
-            description: "Complete SceneView 3.1.1 API — Scene, ARScene, SceneScope DSL, ARSceneScope DSL, node types, resource loading, camera, gestures, math types, threading rules, and common patterns. Read this before writing any SceneView code.",
+            description: "Complete SceneView 3.3.0 API — Scene, ARScene, SceneScope DSL, ARSceneScope DSL, node types, resource loading, camera, gestures, math types, threading rules, and common patterns. Read this before writing any SceneView code.",
             mimeType: "text/markdown",
         },
         {
@@ -79,7 +80,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 properties: {
                     tag: {
                         type: "string",
-                        description: "Optional tag to filter by (e.g. \"ar\", \"3d\", \"anchor\", \"face-tracking\", \"geometry\", \"animation\"). Omit to list all samples.",
+                        description: "Optional tag to filter by (e.g. \"ar\", \"3d\", \"ios\", \"swift\", \"anchor\", \"geometry\", \"animation\", \"video\", \"lighting\"). Omit to list all samples.",
                     },
                 },
                 required: [],
@@ -102,13 +103,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "validate_code",
-            description: "Checks a Kotlin SceneView snippet for common mistakes: threading violations, wrong destroy order, missing null-checks on rememberModelInstance, LightNode trailing-lambda bug, deprecated 2.x APIs, and more. Always call this before presenting generated SceneView code to the user.",
+            description: "Checks a Kotlin or Swift SceneView snippet for common mistakes. For Kotlin: threading violations, wrong destroy order, missing null-checks, LightNode trailing-lambda bug, deprecated 2.x APIs. For Swift: missing @MainActor, async/await patterns, missing imports, RealityKit mistakes. Language is auto-detected. Always call this before presenting generated SceneView code to the user.",
             inputSchema: {
                 type: "object",
                 properties: {
                     code: {
                         type: "string",
-                        description: "The Kotlin source code to validate (composable function, class, or file).",
+                        description: "The Kotlin or Swift source code to validate (composable function, SwiftUI view, class, or file). Language is auto-detected.",
                     },
                 },
                 required: ["code"],
@@ -137,6 +138,71 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["nodeType"],
             },
         },
+        {
+            name: "get_platform_roadmap",
+            description: "Returns the SceneView multi-platform roadmap — current Android support status, planned iOS/KMP/web targets, and timeline. Use this when the user asks about cross-platform support, iOS, Kotlin Multiplatform, or future plans.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
+        {
+            name: "get_best_practices",
+            description: "Returns SceneView performance and architecture best practices — memory management, model optimization, threading rules, Compose integration patterns, and common anti-patterns. Use this when the user asks about performance, optimization, best practices, or architecture.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    category: {
+                        type: "string",
+                        enum: ["all", "performance", "architecture", "memory", "threading"],
+                        description: 'Category to filter by. "all" returns everything. Defaults to "all" if omitted.',
+                    },
+                },
+                required: [],
+            },
+        },
+        {
+            name: "get_ar_setup",
+            description: "Returns detailed AR setup instructions — AndroidManifest permissions and features, Gradle dependencies, ARCore session configuration options (depth, light estimation, instant placement, plane detection, image tracking, cloud anchors), and a complete working AR starter template. More detailed than `get_setup` for AR-specific configuration.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
+        {
+            name: "get_troubleshooting",
+            description: "Returns the SceneView troubleshooting guide — common crashes (SIGABRT, model not showing), build failures, AR issues (drift, overexposure, image detection), and performance problems. Use this when a user reports something not working, a crash, or unexpected behavior.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
+        {
+            name: "get_ios_setup",
+            description: "Returns the complete iOS setup guide for SceneViewSwift — SPM dependency, Package.swift example, minimum platform versions, Info.plist entries for AR (camera permission), and basic SwiftUI integration code. Use this when a user wants to set up SceneView for iOS, macOS, or visionOS.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    type: {
+                        type: "string",
+                        enum: ["3d", "ar"],
+                        description: '"3d" for 3D-only scenes. "ar" for augmented reality (requires iOS, not macOS/visionOS via this path).',
+                    },
+                },
+                required: ["type"],
+            },
+        },
+        {
+            name: "get_web_setup",
+            description: "Returns the complete Web setup guide for SceneView Web — npm install, Kotlin/JS Gradle config, HTML canvas setup, and basic Filament.js integration code. SceneView Web uses the same Filament rendering engine as Android, compiled to WebAssembly. Use this when a user wants to set up SceneView for browsers.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+            },
+        },
     ],
 }));
 // ─── Tool handlers ────────────────────────────────────────────────────────────
@@ -157,6 +223,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     isError: true,
                 };
             }
+            const isIos = sample.language === "swift";
+            const depBlock = isIos
+                ? [
+                    `**SPM dependency:**`,
+                    `\`\`\`swift`,
+                    `.package(url: "${sample.spmDependency ?? sample.dependency}", from: "3.3.0")`,
+                    `\`\`\``,
+                ]
+                : [
+                    `**Gradle dependency:**`,
+                    `\`\`\`kotlin`,
+                    `implementation("${sample.dependency}")`,
+                    `\`\`\``,
+                ];
+            const codeLang = isIos ? "swift" : "kotlin";
+            const codeLabel = isIos ? "**Swift (SwiftUI):**" : "**Kotlin (Jetpack Compose):**";
             return {
                 content: [
                     {
@@ -166,13 +248,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             ``,
                             `**Tags:** ${sample.tags.join(", ")}`,
                             ``,
-                            `**Gradle dependency:**`,
-                            `\`\`\`kotlin`,
-                            `implementation("${sample.dependency}")`,
-                            `\`\`\``,
+                            ...depBlock,
                             ``,
-                            `**Kotlin (Jetpack Compose):**`,
-                            `\`\`\`kotlin`,
+                            codeLabel,
+                            `\`\`\`${codeLang}`,
                             sample.code,
                             `\`\`\``,
                             ``,
@@ -192,7 +271,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     content: [
                         {
                             type: "text",
-                            text: `No samples found with tag "${filterTag}". Available tags: 3d, ar, model, geometry, animation, camera, environment, anchor, plane-detection, image-tracking, face-tracking, placement, gestures`,
+                            text: `No samples found with tag "${filterTag}". Available tags: 3d, ar, model, geometry, animation, camera, environment, anchor, plane-detection, image-tracking, cloud-anchor, point-cloud, placement, gestures, physics, sky, fog, lines, text, reflection, post-processing, ios, swift, video, lighting`,
                         },
                     ],
                 };
@@ -201,7 +280,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ? `## SceneView samples tagged \`${filterTag}\` (${entries.length})\n`
                 : `## All SceneView samples (${entries.length})\n`;
             const rows = entries
-                .map((s) => `### \`${s.id}\`\n**${s.title}**\n${s.description}\n*Tags:* ${s.tags.join(", ")}\n*Dependency:* \`${s.dependency}\`\n\nCall \`get_sample("${s.id}")\` for the full code.`)
+                .map((s) => {
+                const depLabel = s.language === "swift" ? "*SPM:*" : "*Dependency:*";
+                return `### \`${s.id}\`\n**${s.title}**${s.language === "swift" ? " (Swift/iOS)" : ""}\n${s.description}\n*Tags:* ${s.tags.join(", ")}\n${depLabel} \`${s.dependency}\`\n\nCall \`get_sample("${s.id}")\` for the full code.`;
+            })
                 .join("\n\n---\n\n");
             return { content: [{ type: "text", text: header + rows }] };
         }
@@ -219,7 +301,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 `### build.gradle.kts`,
                                 `\`\`\`kotlin`,
                                 `dependencies {`,
-                                `    implementation("io.github.sceneview:sceneview:3.1.1")`,
+                                `    implementation("io.github.sceneview:sceneview:3.3.0")`,
                                 `}`,
                                 `\`\`\``,
                                 ``,
@@ -240,7 +322,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 `### build.gradle.kts`,
                                 `\`\`\`kotlin`,
                                 `dependencies {`,
-                                `    implementation("io.github.sceneview:arsceneview:3.1.1")`,
+                                `    implementation("io.github.sceneview:arsceneview:3.3.0")`,
                                 `}`,
                                 `\`\`\``,
                                 ``,
@@ -318,6 +400,299 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ],
             };
         }
+        // ── get_platform_roadmap ────────────────────────────────────────────────
+        case "get_platform_roadmap": {
+            return { content: [{ type: "text", text: PLATFORM_ROADMAP }] };
+        }
+        // ── get_best_practices ───────────────────────────────────────────────────
+        case "get_best_practices": {
+            const category = request.params.arguments?.category || "all";
+            const text = BEST_PRACTICES[category] ?? BEST_PRACTICES["all"];
+            return { content: [{ type: "text", text }] };
+        }
+        // ── get_ar_setup ─────────────────────────────────────────────────────────
+        case "get_ar_setup": {
+            return { content: [{ type: "text", text: AR_SETUP_GUIDE }] };
+        }
+        // ── get_troubleshooting ──────────────────────────────────────────────────
+        case "get_troubleshooting": {
+            return { content: [{ type: "text", text: TROUBLESHOOTING_GUIDE }] };
+        }
+        // ── get_ios_setup ─────────────────────────────────────────────────────────
+        case "get_ios_setup": {
+            const iosType = request.params.arguments?.type;
+            if (iosType === "3d") {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                `## SceneViewSwift — iOS/macOS/visionOS 3D Setup`,
+                                ``,
+                                `### 1. Add SPM Dependency`,
+                                ``,
+                                `In Xcode: **File → Add Package Dependencies** → paste:`,
+                                `\`\`\``,
+                                `https://github.com/SceneView/sceneview`,
+                                `\`\`\``,
+                                `Set version rule to **"from: 3.3.0"**.`,
+                                ``,
+                                `Or in Package.swift:`,
+                                `\`\`\`swift`,
+                                `// swift-tools-version: 5.10`,
+                                `import PackageDescription`,
+                                ``,
+                                `let package = Package(`,
+                                `    name: "MyApp",`,
+                                `    platforms: [.iOS(.v17), .macOS(.v14), .visionOS(.v1)],`,
+                                `    dependencies: [`,
+                                `        .package(url: "https://github.com/SceneView/sceneview", from: "3.3.0")`,
+                                `    ],`,
+                                `    targets: [`,
+                                `        .executableTarget(`,
+                                `            name: "MyApp",`,
+                                `            dependencies: [`,
+                                `                .product(name: "SceneViewSwift", package: "sceneview")`,
+                                `            ]`,
+                                `        )`,
+                                `    ]`,
+                                `)`,
+                                `\`\`\``,
+                                ``,
+                                `### 2. Minimum Platform Versions`,
+                                ``,
+                                `| Platform | Minimum Version |`,
+                                `|----------|-----------------|`,
+                                `| iOS      | 17.0            |`,
+                                `| macOS    | 14.0            |`,
+                                `| visionOS | 1.0             |`,
+                                ``,
+                                `### 3. Basic SwiftUI Integration`,
+                                ``,
+                                `\`\`\`swift`,
+                                `import SwiftUI`,
+                                `import SceneViewSwift`,
+                                `import RealityKit`,
+                                ``,
+                                `struct ContentView: View {`,
+                                `    @State private var model: ModelNode?`,
+                                ``,
+                                `    var body: some View {`,
+                                `        SceneView { root in`,
+                                `            if let model {`,
+                                `                root.addChild(model.entity)`,
+                                `            }`,
+                                `        }`,
+                                `        .cameraControls(.orbit)`,
+                                `        .task {`,
+                                `            model = try? await ModelNode.load("models/car.usdz")`,
+                                `            model?.scaleToUnits(1.0)`,
+                                `        }`,
+                                `    }`,
+                                `}`,
+                                `\`\`\``,
+                                ``,
+                                `### 4. Model Formats`,
+                                ``,
+                                `| Format | Support |`,
+                                `|--------|---------|`,
+                                `| USDZ   | Native — recommended for iOS |`,
+                                `| .reality | Native — RealityKit format |`,
+                                `| glTF/GLB | Planned via GLTFKit2 |`,
+                                ``,
+                                `No manifest or permission changes needed for 3D-only scenes.`,
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            if (iosType === "ar") {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                `## SceneViewSwift — iOS AR Setup`,
+                                ``,
+                                `### 1. Add SPM Dependency`,
+                                ``,
+                                `\`\`\`swift`,
+                                `.package(url: "https://github.com/SceneView/sceneview", from: "3.3.0")`,
+                                `\`\`\``,
+                                ``,
+                                `### 2. Minimum Platform`,
+                                ``,
+                                `AR requires **iOS 17.0+** (ARKit + RealityKit). macOS and visionOS use different AR APIs.`,
+                                ``,
+                                `### 3. Info.plist — Camera Permission`,
+                                ``,
+                                `Add to your Info.plist (required for AR camera access):`,
+                                `\`\`\`xml`,
+                                `<key>NSCameraUsageDescription</key>`,
+                                `<string>This app uses the camera for augmented reality.</string>`,
+                                `\`\`\``,
+                                ``,
+                                `### 4. Basic AR Integration`,
+                                ``,
+                                `\`\`\`swift`,
+                                `import SwiftUI`,
+                                `import SceneViewSwift`,
+                                `import RealityKit`,
+                                ``,
+                                `struct ARContentView: View {`,
+                                `    @State private var model: ModelNode?`,
+                                ``,
+                                `    var body: some View {`,
+                                `        ARSceneView(`,
+                                `            planeDetection: .horizontal,`,
+                                `            showCoachingOverlay: true,`,
+                                `            onTapOnPlane: { position, arView in`,
+                                `                guard let model else { return }`,
+                                `                let anchor = AnchorNode.world(position: position)`,
+                                `                let clone = model.entity.clone(recursive: true)`,
+                                `                clone.scale = .init(repeating: 0.3)`,
+                                `                anchor.add(clone)`,
+                                `                arView.scene.addAnchor(anchor.entity)`,
+                                `            }`,
+                                `        )`,
+                                `        .edgesIgnoringSafeArea(.all)`,
+                                `        .task {`,
+                                `            model = try? await ModelNode.load("models/robot.usdz")`,
+                                `        }`,
+                                `    }`,
+                                `}`,
+                                `\`\`\``,
+                                ``,
+                                `### 5. AR Configuration Options`,
+                                ``,
+                                `| Parameter | Options | Default |`,
+                                `|-----------|---------|---------|`,
+                                `| \`planeDetection\` | \`.none\`, \`.horizontal\`, \`.vertical\`, \`.both\` | \`.horizontal\` |`,
+                                `| \`showPlaneOverlay\` | \`true\` / \`false\` | \`true\` |`,
+                                `| \`showCoachingOverlay\` | \`true\` / \`false\` | \`true\` |`,
+                                `| \`imageTrackingDatabase\` | \`Set<ARReferenceImage>\` | \`nil\` |`,
+                                ``,
+                                `### 6. Image Tracking`,
+                                ``,
+                                `\`\`\`swift`,
+                                `let images = AugmentedImageNode.createImageDatabase([`,
+                                `    AugmentedImageNode.ReferenceImage(`,
+                                `        name: "poster",`,
+                                `        image: UIImage(named: "poster_ref")!,`,
+                                `        physicalWidth: 0.3  // meters`,
+                                `    )`,
+                                `])`,
+                                ``,
+                                `ARSceneView(`,
+                                `    imageTrackingDatabase: images,`,
+                                `    onImageDetected: { name, anchor, arView in`,
+                                `        let cube = GeometryNode.cube(size: 0.1, color: .blue)`,
+                                `        anchor.add(cube.entity)`,
+                                `        arView.scene.addAnchor(anchor.entity)`,
+                                `    }`,
+                                `)`,
+                                `\`\`\``,
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [{ type: "text", text: `Unknown type "${iosType}". Use "3d" or "ar".` }],
+                isError: true,
+            };
+        }
+        // ── get_web_setup ────────────────────────────────────────────────────────
+        case "get_web_setup": {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `## SceneView Web — Browser 3D Setup`,
+                            ``,
+                            `SceneView Web uses **Filament.js** — the same rendering engine as Android, compiled to WebAssembly (WebGL2).`,
+                            ``,
+                            `### 1. Install`,
+                            ``,
+                            `\`\`\`bash`,
+                            `npm install @sceneview/sceneview-web`,
+                            `\`\`\``,
+                            ``,
+                            `Or in a Kotlin/JS Gradle project:`,
+                            `\`\`\`kotlin`,
+                            `// build.gradle.kts`,
+                            `kotlin {`,
+                            `    js(IR) { browser(); binaries.executable() }`,
+                            `    sourceSets {`,
+                            `        jsMain.dependencies {`,
+                            `            implementation("@sceneview/sceneview-web")`,
+                            `            // or: implementation(project(":sceneview-web"))`,
+                            `        }`,
+                            `    }`,
+                            `}`,
+                            `\`\`\``,
+                            ``,
+                            `### 2. HTML`,
+                            ``,
+                            `\`\`\`html`,
+                            `<canvas id="scene-canvas" style="width:100%;height:100vh"></canvas>`,
+                            `<script src="your-app.js"></script>`,
+                            `\`\`\``,
+                            ``,
+                            `### 3. Kotlin/JS Code`,
+                            ``,
+                            `\`\`\`kotlin`,
+                            `import io.github.sceneview.web.SceneView`,
+                            `import kotlinx.browser.document`,
+                            `import org.w3c.dom.HTMLCanvasElement`,
+                            ``,
+                            `fun main() {`,
+                            `    val canvas = document.getElementById("scene-canvas") as HTMLCanvasElement`,
+                            `    canvas.width = canvas.clientWidth`,
+                            `    canvas.height = canvas.clientHeight`,
+                            ``,
+                            `    SceneView.create(`,
+                            `        canvas = canvas,`,
+                            `        configure = {`,
+                            `            camera {`,
+                            `                eye(0.0, 1.5, 5.0)`,
+                            `                target(0.0, 0.0, 0.0)`,
+                            `                fov(45.0)`,
+                            `            }`,
+                            `            light {`,
+                            `                directional()`,
+                            `                intensity(100_000.0)`,
+                            `            }`,
+                            `            model("models/DamagedHelmet.glb")`,
+                            `            autoRotate()`,
+                            `        },`,
+                            `        onReady = { sceneView ->`,
+                            `            sceneView.startRendering()`,
+                            `        }`,
+                            `    )`,
+                            `}`,
+                            `\`\`\``,
+                            ``,
+                            `### 4. Features`,
+                            ``,
+                            `- Same Filament PBR renderer as Android (WASM)`,
+                            `- glTF 2.0 / GLB model loading`,
+                            `- IBL environment lighting (KTX)`,
+                            `- Orbit camera with mouse/touch/pinch controls`,
+                            `- Auto-rotation`,
+                            `- Directional, point, and spot lights`,
+                            ``,
+                            `### 5. Limitations`,
+                            ``,
+                            `- No AR (requires native sensors)`,
+                            `- WebGL2 required (~95% of browsers)`,
+                            `- glTF/GLB format only (same as Android)`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        }
         default:
             return {
                 content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],

package/dist/issues.js

@@ -9,10 +9,10 @@ export async function fetchKnownIssues() {
     let issues = [];
     let fetchError = null;
     try {
-        const response = await fetch("https://api.github.com/repos/SceneView/sceneview-android/issues?state=open&per_page=30", {
+        const response = await fetch("https://api.github.com/repos/SceneView/sceneview/issues?state=open&per_page=30", {
             headers: {
                 Accept: "application/vnd.github+json",
-                "User-Agent": "sceneview-mcp/3.0",
+                "User-Agent": "sceneview-mcp/3.3.0",
                 "X-GitHub-Api-Version": "2022-11-28",
             },
         });

package/dist/migration.js

@@ -8,8 +8,8 @@ SceneView 3.0 is a full rewrite from Android Views to **Jetpack Compose**. Nearl
 
 | 2.x | 3.0 |
 |-----|-----|
-| \`io.github.sceneview:sceneview:2.x.x\` | \`io.github.sceneview:sceneview:3.1.1\` |
-| \`io.github.sceneview:arsceneview:2.x.x\` | \`io.github.sceneview:arsceneview:3.1.1\` |
+| \`io.github.sceneview:sceneview:2.x.x\` | \`io.github.sceneview:sceneview:3.3.0\` |
+| \`io.github.sceneview:arsceneview:2.x.x\` | \`io.github.sceneview:arsceneview:3.3.0\` |
 
 ---
 
@@ -174,7 +174,7 @@ LightNode(
 val environmentLoader = rememberEnvironmentLoader(engine)
 Scene(
     environment = rememberEnvironment(environmentLoader) {
-        environmentLoader.createHDREnvironment("environments/sky_2k.hdr")!!
+        environmentLoader.createHDREnvironment("environments/sky_2k.hdr") ?: createEnvironment(environmentLoader)
     }
 ) { … }
 \`\`\`