sceneview-mcp 3.1.1 → 3.3.0

package/dist/index.js

@@ -9,6 +9,8 @@ import { getSample, SAMPLE_IDS, SAMPLES } from "./samples.js";
 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 {
@@ -17,14 +19,15 @@ try {
 catch {
     API_DOCS = "SceneView API docs not found. Run `npm run prepare` to bundle llms.txt.";
 }
-const server = new Server({ name: "@sceneview/mcp", version: "3.0.2" }, { capabilities: { resources: {}, tools: {} } });
+const NODE_SECTIONS = parseNodeSections(API_DOCS);
+const server = new Server({ name: "@sceneview/mcp", version: "3.3.0" }, { capabilities: { resources: {}, tools: {} } });
 // ─── Resources ───────────────────────────────────────────────────────────────
 server.setRequestHandler(ListResourcesRequestSchema, async () => ({
     resources: [
         {
             uri: "sceneview://api",
             name: "SceneView API Reference",
-            description: "Complete SceneView 3.0.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.",
+            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",
         },
         {
@@ -77,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: [],
@@ -100,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"],
@@ -121,6 +124,77 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: [],
             },
         },
+        {
+            name: "get_node_reference",
+            description: "Returns the full API reference for a specific SceneView node type or composable — parameters, types, and a usage example — parsed directly from the official llms.txt. Use this when you need the exact signature or options for a node (e.g. ModelNode, LightNode, ARScene). If the requested type is not found, the response lists all available types.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    nodeType: {
+                        type: "string",
+                        description: 'The node type or composable name to look up, e.g. "ModelNode", "LightNode", "ARScene", "AnchorNode". Case-insensitive.',
+                    },
+                },
+                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"],
+            },
+        },
     ],
 }));
 // ─── Tool handlers ────────────────────────────────────────────────────────────
@@ -141,6 +215,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: [
                     {
@@ -150,13 +240,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,
                             `\`\`\``,
                             ``,
@@ -176,7 +263,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`,
                         },
                     ],
                 };
@@ -185,7 +272,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 }] };
         }
@@ -203,7 +293,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 `### build.gradle.kts`,
                                 `\`\`\`kotlin`,
                                 `dependencies {`,
-                                `    implementation("io.github.sceneview:sceneview:3.0.0")`,
+                                `    implementation("io.github.sceneview:sceneview:3.3.0")`,
                                 `}`,
                                 `\`\`\``,
                                 ``,
@@ -224,7 +314,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 `### build.gradle.kts`,
                                 `\`\`\`kotlin`,
                                 `dependencies {`,
-                                `    implementation("io.github.sceneview:arsceneview:3.0.0")`,
+                                `    implementation("io.github.sceneview:arsceneview:3.3.0")`,
                                 `}`,
                                 `\`\`\``,
                                 ``,
@@ -263,6 +353,247 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         case "get_migration_guide": {
             return { content: [{ type: "text", text: MIGRATION_GUIDE }] };
         }
+        // ── get_node_reference ────────────────────────────────────────────────────
+        case "get_node_reference": {
+            const nodeType = request.params.arguments?.nodeType;
+            if (!nodeType || typeof nodeType !== "string") {
+                return {
+                    content: [{ type: "text", text: "Missing required parameter: `nodeType`" }],
+                    isError: true,
+                };
+            }
+            const section = findNodeSection(NODE_SECTIONS, nodeType);
+            if (!section) {
+                const available = listNodeTypes(NODE_SECTIONS).join(", ");
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                `No reference found for node type \`${nodeType}\`.`,
+                                ``,
+                                `**Available node types:**`,
+                                available,
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `## \`${section.name}\` — API Reference`,
+                            ``,
+                            section.content,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        }
+        // ── 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,
+            };
+        }
         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.0.0\` |
-| \`io.github.sceneview:arsceneview:2.x.x\` | \`io.github.sceneview:arsceneview:3.0.0\` |
+| \`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)
     }
 ) { … }
 \`\`\`

package/dist/node-reference.js

@@ -0,0 +1,73 @@
+/**
+ * node-reference.ts
+ *
+ * Parses llms.txt to extract per-node-type API reference sections.
+ * Each section starts at a `###` heading and ends just before the next `###` or `##` heading.
+ */
+// ─── Parsing ─────────────────────────────────────────────────────────────────
+/**
+ * Extract the bare node-type name from a `###` heading line.
+ * Examples:
+ *   "Scene — 3D viewport"        → "Scene"
+ *   "HitResultNode — surface cursor" → "HitResultNode"
+ *   "Primitive geometry nodes"   → "Primitive geometry nodes"
+ */
+function headingToName(heading) {
+    return heading.split(/\s*[—–-]\s*/)[0].trim();
+}
+/**
+ * Parse all `###`-level sections from the full llms.txt content.
+ * Returns a map keyed by the bare node-type name (case-insensitive lookup
+ * handled separately).
+ */
+export function parseNodeSections(llmsTxt) {
+    const sections = new Map();
+    const lines = llmsTxt.split("\n");
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line.startsWith("### ")) {
+            const headingText = line.slice(4).trim(); // text after "### "
+            const name = headingToName(headingText);
+            // Collect lines until the next `##` or `###` heading
+            const bodyLines = [line];
+            i++;
+            while (i < lines.length && !lines[i].startsWith("## ") && !lines[i].startsWith("### ")) {
+                bodyLines.push(lines[i]);
+                i++;
+            }
+            // Trim trailing blank lines
+            while (bodyLines.length > 1 && bodyLines[bodyLines.length - 1].trim() === "") {
+                bodyLines.pop();
+            }
+            sections.set(name.toLowerCase(), {
+                name,
+                heading: headingText,
+                content: bodyLines.join("\n"),
+            });
+        }
+        else {
+            i++;
+        }
+    }
+    return sections;
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Look up a node type section by name (case-insensitive).
+ *
+ * @param sections - The map returned by `parseNodeSections`
+ * @param nodeType - User-supplied name, e.g. "ModelNode", "lightnode", "ARScene"
+ * @returns The matching `NodeSection`, or `undefined` if not found.
+ */
+export function findNodeSection(sections, nodeType) {
+    return sections.get(nodeType.toLowerCase());
+}
+/**
+ * Returns a sorted array of all known node-type names.
+ */
+export function listNodeTypes(sections) {
+    return Array.from(sections.values())
+        .map((s) => s.name)
+        .sort();
+}