sceneview-mcp 3.0.1 → 3.0.3

package/dist/index.js

@@ -6,6 +6,9 @@ import { readFileSync } from "fs";
 import { dirname, resolve } from "path";
 import { fileURLToPath } from "url";
 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";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 let API_DOCS;
 try {
@@ -14,7 +17,8 @@ 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.1" }, { capabilities: { resources: {}, tools: {} } });
+const server = new Server({ name: "@sceneview/mcp", version: "3.0.2" }, { capabilities: { resources: {}, tools: {} } });
+// ─── Resources ───────────────────────────────────────────────────────────────
 server.setRequestHandler(ListResourcesRequestSchema, async () => ({
     resources: [
         {
@@ -23,21 +27,36 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => ({
             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.",
             mimeType: "text/markdown",
         },
+        {
+            uri: "sceneview://known-issues",
+            name: "SceneView Open GitHub Issues",
+            description: "Live list of open issues from the SceneView GitHub repository. Check this before reporting a bug or when something isn't working — there may already be a known workaround.",
+            mimeType: "text/markdown",
+        },
     ],
 }));
 server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-    if (request.params.uri === "sceneview://api") {
-        return {
-            contents: [{ uri: "sceneview://api", mimeType: "text/markdown", text: API_DOCS }],
-        };
+    switch (request.params.uri) {
+        case "sceneview://api":
+            return {
+                contents: [{ uri: "sceneview://api", mimeType: "text/markdown", text: API_DOCS }],
+            };
+        case "sceneview://known-issues": {
+            const issues = await fetchKnownIssues();
+            return {
+                contents: [{ uri: "sceneview://known-issues", mimeType: "text/markdown", text: issues }],
+            };
+        }
+        default:
+            throw new Error(`Unknown resource: ${request.params.uri}`);
     }
-    throw new Error(`Unknown resource: ${request.params.uri}`);
 });
+// ─── Tools ───────────────────────────────────────────────────────────────────
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {
             name: "get_sample",
-            description: "Returns a complete, compilable Kotlin sample for a given SceneView scenario. Use this to get a working starting point before customising.",
+            description: "Returns a complete, compilable Kotlin sample for a given SceneView scenario. Use this to get a working starting point before customising. Call `list_samples` first if you are unsure which scenario fits.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -50,6 +69,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["scenario"],
             },
         },
+        {
+            name: "list_samples",
+            description: "Lists all available SceneView code samples with their IDs, descriptions, and tags. Use this to find the right sample before calling `get_sample`, or to show the user what SceneView can do.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tag: {
+                        type: "string",
+                        description: "Optional tag to filter by (e.g. \"ar\", \"3d\", \"anchor\", \"face-tracking\", \"geometry\", \"animation\"). Omit to list all samples.",
+                    },
+                },
+                required: [],
+            },
+        },
         {
             name: "get_setup",
             description: "Returns the Gradle dependency and AndroidManifest snippet required to use SceneView in an Android project.",
@@ -65,16 +98,46 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["type"],
             },
         },
+        {
+            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.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    code: {
+                        type: "string",
+                        description: "The Kotlin source code to validate (composable function, class, or file).",
+                    },
+                },
+                required: ["code"],
+            },
+        },
+        {
+            name: "get_migration_guide",
+            description: "Returns the full SceneView 2.x → 3.0 migration guide. Use this when a user reports code that worked in 2.x but breaks in 3.0, or when helping someone upgrade.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
     ],
 }));
+// ─── Tool handlers ────────────────────────────────────────────────────────────
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     switch (request.params.name) {
+        // ── get_sample ────────────────────────────────────────────────────────────
         case "get_sample": {
             const scenario = request.params.arguments?.scenario;
             const sample = getSample(scenario);
             if (!sample) {
                 return {
-                    content: [{ type: "text", text: `Unknown scenario "${scenario}". Available: ${SAMPLE_IDS.join(", ")}` }],
+                    content: [
+                        {
+                            type: "text",
+                            text: `Unknown scenario "${scenario}". Call \`list_samples\` to see available options.`,
+                        },
+                    ],
                     isError: true,
                 };
             }
@@ -85,6 +148,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         text: [
                             `## ${sample.title}`,
                             ``,
+                            `**Tags:** ${sample.tags.join(", ")}`,
+                            ``,
                             `**Gradle dependency:**`,
                             `\`\`\`kotlin`,
                             `implementation("${sample.dependency}")`,
@@ -102,6 +167,29 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ],
             };
         }
+        // ── list_samples ──────────────────────────────────────────────────────────
+        case "list_samples": {
+            const filterTag = request.params.arguments?.tag;
+            const entries = Object.values(SAMPLES).filter((s) => !filterTag || s.tags.includes(filterTag));
+            if (entries.length === 0) {
+                return {
+                    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`,
+                        },
+                    ],
+                };
+            }
+            const header = filterTag
+                ? `## 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.`)
+                .join("\n\n---\n\n");
+            return { content: [{ type: "text", text: header + rows }] };
+        }
+        // ── get_setup ─────────────────────────────────────────────────────────────
         case "get_setup": {
             const type = request.params.arguments?.type;
             if (type === "3d") {
@@ -158,6 +246,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 isError: true,
             };
         }
+        // ── validate_code ─────────────────────────────────────────────────────────
+        case "validate_code": {
+            const code = request.params.arguments?.code;
+            if (!code || typeof code !== "string") {
+                return {
+                    content: [{ type: "text", text: "Missing required parameter: `code`" }],
+                    isError: true,
+                };
+            }
+            const issues = validateCode(code);
+            const report = formatValidationReport(issues);
+            return { content: [{ type: "text", text: report }] };
+        }
+        // ── get_migration_guide ───────────────────────────────────────────────────
+        case "get_migration_guide": {
+            return { content: [{ type: "text", text: MIGRATION_GUIDE }] };
+        }
         default:
             return {
                 content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],

package/dist/issues.js

@@ -0,0 +1,72 @@
+// Cache for 10 minutes — avoids hammering the GitHub API on every tool call
+const CACHE_TTL_MS = 10 * 60 * 1000;
+let cache = null;
+export async function fetchKnownIssues() {
+    const now = Date.now();
+    if (cache && now - cache.fetchedAt < CACHE_TTL_MS) {
+        return cache.data;
+    }
+    let issues = [];
+    let fetchError = null;
+    try {
+        const response = await fetch("https://api.github.com/repos/SceneView/sceneview-android/issues?state=open&per_page=30", {
+            headers: {
+                Accept: "application/vnd.github+json",
+                "User-Agent": "sceneview-mcp/3.0",
+                "X-GitHub-Api-Version": "2022-11-28",
+            },
+        });
+        if (!response.ok) {
+            fetchError = `GitHub API returned ${response.status}: ${response.statusText}`;
+        }
+        else {
+            issues = (await response.json());
+        }
+    }
+    catch (err) {
+        fetchError = `Failed to fetch issues: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    const result = formatIssues(issues, fetchError);
+    cache = { data: result, fetchedAt: now };
+    return result;
+}
+function formatIssues(issues, fetchError) {
+    const lines = ["# SceneView — Open GitHub Issues\n"];
+    if (fetchError) {
+        lines.push(`> ⚠️ ${fetchError}. Showing cached data if available.\n`);
+    }
+    else {
+        lines.push(`*Fetched live from GitHub — ${issues.length} open issue(s). Cached for 10 minutes.*\n`);
+    }
+    if (issues.length === 0) {
+        lines.push("No open issues. 🎉");
+        return lines.join("\n");
+    }
+    // Group by label: bugs first, then questions/other
+    const bugs = issues.filter((i) => i.labels.some((l) => l.name === "bug"));
+    const others = issues.filter((i) => !i.labels.some((l) => l.name === "bug"));
+    const renderGroup = (title, group) => {
+        if (group.length === 0)
+            return;
+        lines.push(`## ${title}\n`);
+        for (const issue of group) {
+            const labelStr = issue.labels.length > 0 ? ` [${issue.labels.map((l) => l.name).join(", ")}]` : "";
+            lines.push(`### #${issue.number} — ${issue.title}${labelStr}`);
+            lines.push(`*Opened by @${issue.user.login} · ${issue.updated_at.slice(0, 10)}*`);
+            lines.push(issue.html_url);
+            // Include first 300 chars of body as context
+            if (issue.body) {
+                const excerpt = issue.body
+                    .replace(/\r\n/g, "\n")
+                    .replace(/```[\s\S]*?```/g, "[code block]") // strip code blocks for brevity
+                    .trim()
+                    .slice(0, 300);
+                lines.push(`\n> ${excerpt.replace(/\n/g, "\n> ")}${issue.body.length > 300 ? "…" : ""}`);
+            }
+            lines.push("");
+        }
+    };
+    renderGroup("🐛 Bug Reports", bugs);
+    renderGroup("📋 Other Issues", others);
+    return lines.join("\n");
+}

package/dist/migration.js

@@ -0,0 +1,248 @@
+export const MIGRATION_GUIDE = `# SceneView 2.x → 3.0 Migration Guide
+
+SceneView 3.0 is a full rewrite from Android Views to **Jetpack Compose**. Nearly every public API changed. This guide covers every breaking change and how to fix it.
+
+---
+
+## 1. Gradle dependency
+
+| 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\` |
+
+---
+
+## 2. Root composable names
+
+| 2.x | 3.0 |
+|-----|-----|
+| \`SceneView(…)\` | \`Scene(…)\` |
+| \`ArSceneView(…)\` | \`ARScene(…)\` |
+
+**Before:**
+\`\`\`kotlin
+SceneView(modifier = Modifier.fillMaxSize())
+\`\`\`
+
+**After:**
+\`\`\`kotlin
+val engine = rememberEngine()
+Scene(modifier = Modifier.fillMaxSize(), engine = engine)
+\`\`\`
+
+---
+
+## 3. Engine lifecycle
+
+In 2.x the engine was managed internally. In 3.0 you own it — use \`rememberEngine()\` which ties it to the composition lifecycle.
+
+| 2.x | 3.0 |
+|-----|-----|
+| Engine implicit | \`val engine = rememberEngine()\` |
+| Never destroy manually | Never call \`engine.destroy()\` — \`rememberEngine\` does it |
+
+---
+
+## 4. Model loading
+
+| 2.x | 3.0 |
+|-----|-----|
+| \`modelLoader.loadModelAsync(path) { … }\` | \`rememberModelInstance(modelLoader, path)\` (returns \`null\` while loading) |
+| \`modelLoader.loadModel(path)\` | \`modelLoader.loadModelInstanceAsync(path)\` (imperative) |
+| \`ModelRenderable.builder()\` | Removed — use GLB/glTF assets |
+
+**Before:**
+\`\`\`kotlin
+var modelInstance by remember { mutableStateOf<ModelInstance?>(null) }
+LaunchedEffect(Unit) {
+    modelInstance = modelLoader.loadModelAsync("models/chair.glb")
+}
+\`\`\`
+
+**After:**
+\`\`\`kotlin
+Scene(engine = engine, modelLoader = modelLoader) {
+    rememberModelInstance(modelLoader, "models/chair.glb")?.let { instance ->
+        ModelNode(modelInstance = instance, scaleToUnits = 1.0f)
+    }
+}
+\`\`\`
+
+---
+
+## 5. Node hierarchy — imperative → declarative DSL
+
+In 2.x nodes were added imperatively (\`scene.addChild(node)\`). In 3.0 nodes are declared as composables inside \`Scene { }\` or \`ARScene { }\`.
+
+**Before:**
+\`\`\`kotlin
+val modelNode = ModelNode().apply {
+    loadModelGlbAsync(
+        glbFileLocation = "models/chair.glb",
+        scaleToUnits = 1f,
+    )
+}
+sceneView.addChildNode(modelNode)
+\`\`\`
+
+**After:**
+\`\`\`kotlin
+Scene(engine = engine, modelLoader = modelLoader) {
+    rememberModelInstance(modelLoader, "models/chair.glb")?.let { instance ->
+        ModelNode(modelInstance = instance, scaleToUnits = 1f)
+    }
+}
+\`\`\`
+
+---
+
+## 6. Removed nodes and replacements
+
+| 2.x | 3.0 replacement |
+|-----|-----------------|
+| \`TransformableNode\` | Set \`isEditable = true\` on \`ModelNode\` |
+| \`PlacementNode\` | \`AnchorNode(anchor = hitResult.createAnchor())\` + \`HitResultNode\` |
+| \`ViewRenderable\` | \`ViewNode\` with a \`@Composable\` content lambda |
+| \`AnchorNode()\` (no-arg) | \`AnchorNode(anchor = hitResult.createAnchor())\` |
+
+**TransformableNode:**
+\`\`\`kotlin
+// Before
+val node = TransformableNode(transformationSystem).apply {
+    setParent(anchorNode)
+}
+
+// After
+ModelNode(
+    modelInstance = instance,
+    scaleToUnits = 1f,
+    isEditable = true  // enables pinch-to-scale + drag-to-rotate
+)
+\`\`\`
+
+**ViewRenderable → ViewNode:**
+\`\`\`kotlin
+// Before
+ViewRenderable.builder()
+    .setView(context, R.layout.my_layout)
+    .build()
+    .thenAccept { renderable -> … }
+
+// After
+val windowManager = rememberViewNodeManager()
+Scene(viewNodeWindowManager = windowManager) {
+    ViewNode(windowManager = windowManager) {
+        Card { Text("Hello 3D World!") }
+    }
+}
+\`\`\`
+
+---
+
+## 7. Light configuration
+
+LightNode's \`apply\` is a **named parameter** (not a trailing lambda). This is the most common silent breakage after migrating.
+
+\`\`\`kotlin
+// WRONG — trailing lambda is silently ignored
+LightNode(engine = engine, type = LightManager.Type.DIRECTIONAL) {
+    intensity(100_000f)
+}
+
+// CORRECT
+LightNode(
+    engine = engine,
+    type = LightManager.Type.DIRECTIONAL,
+    apply = {
+        intensity(100_000f)
+        castShadows(true)
+    }
+)
+\`\`\`
+
+---
+
+## 8. Environment / IBL loading
+
+| 2.x | 3.0 |
+|-----|-----|
+| \`environmentLoader.loadEnvironment(path)\` | \`environmentLoader.createHDREnvironment(path)\` |
+
+\`\`\`kotlin
+// 3.0
+val environmentLoader = rememberEnvironmentLoader(engine)
+Scene(
+    environment = rememberEnvironment(environmentLoader) {
+        environmentLoader.createHDREnvironment("environments/sky_2k.hdr")!!
+    }
+) { … }
+\`\`\`
+
+---
+
+## 9. AR session configuration
+
+In 3.0 \`sessionConfiguration\` is a lambda parameter on \`ARScene\` (not a separate builder).
+
+\`\`\`kotlin
+ARScene(
+    engine = engine,
+    modelLoader = modelLoader,
+    sessionConfiguration = { session, config ->
+        config.depthMode =
+            if (session.isDepthModeSupported(Config.DepthMode.AUTOMATIC))
+                Config.DepthMode.AUTOMATIC else Config.DepthMode.DISABLED
+        config.instantPlacementMode = Config.InstantPlacementMode.LOCAL_Y_UP
+        config.lightEstimationMode = Config.LightEstimationMode.ENVIRONMENTAL_HDR
+    }
+) { … }
+\`\`\`
+
+---
+
+## 10. AR anchors (no more worldPosition hacks)
+
+| 2.x pattern | 3.0 |
+|-------------|-----|
+| \`node.worldPosition = hitResult.hitPose.position\` | \`AnchorNode(anchor = hitResult.createAnchor())\` |
+
+Plain nodes whose \`worldPosition\` is set manually will drift when ARCore remaps its coordinate system. \`AnchorNode\` compensates automatically.
+
+---
+
+## 11. Shadows
+
+In 3.0, \`ARScene\` has shadows enabled by default via \`createARView()\`. For \`Scene\` (3D only), shadows are disabled by default — enable with:
+
+\`\`\`kotlin
+Scene(
+    view = rememberView(engine).also { it.setShadowingEnabled(true) },
+    …
+)
+\`\`\`
+
+---
+
+## 12. Camera
+
+| 2.x | 3.0 |
+|-----|-----|
+| \`CameraManipulator\` set on the View | \`cameraManipulator = rememberCameraManipulator()\` on \`Scene\` |
+| Custom camera via \`setCameraNode\` | \`cameraNode = rememberCameraNode(engine) { … }\` on \`Scene\` |
+
+---
+
+## Checklist
+
+- [ ] Replace \`SceneView(…)\` → \`Scene(engine = rememberEngine(), …)\`
+- [ ] Replace \`ArSceneView(…)\` → \`ARScene(engine = rememberEngine(), …)\`
+- [ ] Replace \`modelLoader.loadModelAsync\` → \`rememberModelInstance\`
+- [ ] Add null-check on every \`rememberModelInstance\` result
+- [ ] Replace \`TransformableNode\` → \`isEditable = true\`
+- [ ] Replace \`PlacementNode\` → \`AnchorNode\` + \`HitResultNode\`
+- [ ] Replace \`ViewRenderable\` → \`ViewNode\` with Compose lambda
+- [ ] Fix \`LightNode { … }\` → \`LightNode(apply = { … })\`
+- [ ] Remove manual \`engine.destroy()\` calls
+- [ ] Replace manual \`worldPosition\` in AR → \`AnchorNode\`
+`;

package/dist/samples.js

@@ -3,6 +3,7 @@ export const SAMPLES = {
         id: "model-viewer",
         title: "3D Model Viewer",
         description: "Full-screen 3D scene with a GLB model, HDR environment, and orbit camera",
+        tags: ["3d", "model", "environment", "camera"],
         dependency: "io.github.sceneview:sceneview:3.0.0",
         prompt: "Create an Android Compose screen called `ModelViewerScreen` that loads a GLB file from assets/models/my_model.glb and displays it in a full-screen 3D scene with an orbit camera (drag to rotate, pinch to zoom). Add an HDR environment from assets/environments/sky_2k.hdr for realistic lighting. Use SceneView `io.github.sceneview:sceneview:3.0.0`.",
         code: `@Composable
@@ -36,6 +37,7 @@ fun ModelViewerScreen() {
         id: "geometry-scene",
         title: "3D Geometry Scene",
         description: "Procedural 3D scene using primitive geometry nodes (cube, sphere, plane) — no GLB required",
+        tags: ["3d", "geometry", "animation"],
         dependency: "io.github.sceneview:sceneview:3.0.0",
         prompt: "Create an Android Compose screen called `GeometrySceneScreen` that renders a full-screen 3D scene with a red rotating cube, a metallic blue sphere, and a green floor plane. No model files — use SceneView built-in geometry nodes. Orbit camera. Use SceneView `io.github.sceneview:sceneview:3.0.0`.",
         code: `@Composable
@@ -91,6 +93,7 @@ fun GeometrySceneScreen() {
         id: "ar-tap-to-place",
         title: "AR Tap-to-Place",
         description: "AR scene where each tap places a GLB model on a detected surface. Placed models are pinch-to-scale and drag-to-rotate.",
+        tags: ["ar", "model", "anchor", "plane-detection", "placement", "gestures"],
         dependency: "io.github.sceneview:arsceneview:3.0.0",
         prompt: "Create an Android Compose screen called `TapToPlaceScreen` that opens the camera in AR mode. Show a plane detection grid. When the user taps a detected surface, place a 3D GLB model from assets/models/chair.glb at that point. The user should be able to pinch-to-scale and drag-to-rotate after placing. Multiple taps = multiple objects. Use SceneView `io.github.sceneview:arsceneview:3.0.0`.",
         code: `@Composable
@@ -134,6 +137,7 @@ fun TapToPlaceScreen() {
         id: "ar-placement-cursor",
         title: "AR Placement Cursor",
         description: "AR scene with a reticle that follows the surface at screen center. Tap to confirm placement.",
+        tags: ["ar", "model", "anchor", "plane-detection", "placement", "camera"],
         dependency: "io.github.sceneview:arsceneview:3.0.0",
         prompt: "Create an Android Compose AR screen called `ARCursorScreen`. Show a small reticle that snaps to the nearest detected surface at the center of the screen as the user moves the camera. When the user taps, place a GLB model from assets/models/object.glb at that position and hide the reticle. Use SceneView `io.github.sceneview:arsceneview:3.0.0`.",
         code: `@Composable
@@ -180,6 +184,7 @@ fun ARCursorScreen() {
         id: "ar-augmented-image",
         title: "AR Augmented Image",
         description: "Detects a reference image in the camera feed and overlays a 3D model above it.",
+        tags: ["ar", "model", "anchor", "image-tracking"],
         dependency: "io.github.sceneview:arsceneview:3.0.0",
         prompt: "Create an Android Compose AR screen called `AugmentedImageScreen` that detects a printed reference image (from R.drawable.target_image, physical width 15 cm) and places a 3D GLB model from assets/models/overlay.glb above it, scaled to match the image width. The model should disappear when the image is lost. Use SceneView `io.github.sceneview:arsceneview:3.0.0`.",
         code: `@Composable
@@ -222,6 +227,7 @@ fun AugmentedImageScreen() {
         id: "ar-face-filter",
         title: "AR Face Filter",
         description: "Front-camera AR that detects faces and renders a 3D mesh material over them.",
+        tags: ["ar", "face-tracking", "camera"],
         dependency: "io.github.sceneview:arsceneview:3.0.0",
         prompt: "Create an Android Compose AR screen called `FaceFilterScreen` using the front camera. Detect all visible faces and apply a custom material from assets/materials/face_mask.filamat to the face mesh. Use SceneView `io.github.sceneview:arsceneview:3.0.0` with `Session.Feature.FRONT_CAMERA` and `AugmentedFaceMode.MESH3D`.",
         code: `@Composable

package/dist/validator.js

@@ -0,0 +1,251 @@
+function findLines(lines, pattern) {
+    return lines
+        .map((l, i) => (pattern.test(l) ? i + 1 : -1))
+        .filter((n) => n !== -1);
+}
+const RULES = [
+    // ─── Threading ────────────────────────────────────────────────────────────
+    {
+        id: "threading/filament-off-main-thread",
+        severity: "error",
+        check(code, lines) {
+            const issues = [];
+            if (!/Dispatchers\.(IO|Default)/.test(code))
+                return issues;
+            const filamentCallPatterns = [
+                [/modelLoader\.createModel/, "modelLoader.createModel*"],
+                [/modelLoader\.loadModel/, "modelLoader.loadModel*"],
+                [/materialLoader\./, "materialLoader.*"],
+                [/Texture\.Builder/, "Texture.Builder"],
+                [/engine\.createTexture/, "engine.createTexture"],
+            ];
+            for (const [pat, name] of filamentCallPatterns) {
+                if (pat.test(code)) {
+                    findLines(lines, pat).forEach((line) => issues.push({
+                        severity: "error",
+                        rule: "threading/filament-off-main-thread",
+                        message: `\`${name}\` detected alongside a background dispatcher. Filament JNI calls must run on the **main thread**. Use \`rememberModelInstance\` in composables, or wrap imperative code in \`withContext(Dispatchers.Main)\`.`,
+                        line,
+                    }));
+                }
+            }
+            return issues;
+        },
+    },
+    // ─── AR: plain Node worldPosition instead of AnchorNode ──────────────────
+    {
+        id: "ar/node-not-anchor",
+        severity: "warning",
+        check(code, lines) {
+            const issues = [];
+            if (!code.includes("ARScene") && !code.includes("AnchorNode"))
+                return issues;
+            if (/\.worldPosition\s*=/.test(code)) {
+                findLines(lines, /\.worldPosition\s*=/).forEach((line) => issues.push({
+                    severity: "warning",
+                    rule: "ar/node-not-anchor",
+                    message: "Manually setting `worldPosition` inside an AR scene causes drift — ARCore remaps coordinates during tracking and plain nodes don't compensate. Use `AnchorNode(anchor = hitResult.createAnchor())` instead.",
+                    line,
+                }));
+            }
+            return issues;
+        },
+    },
+    // ─── Missing null-check on rememberModelInstance ──────────────────────────
+    {
+        id: "composable/model-instance-null-check",
+        severity: "error",
+        check(code, lines) {
+            const issues = [];
+            const assignMatch = code.match(/val\s+(\w+)\s*=\s*rememberModelInstance\(/);
+            if (!assignMatch)
+                return issues;
+            const varName = assignMatch[1];
+            // Flag ModelNode uses where the variable is passed without null-guard (no ?. !! or ?: )
+            const unsafeUse = new RegExp(`ModelNode\\s*\\([^)]*modelInstance\\s*=\\s*${varName}(?![?!])`);
+            if (unsafeUse.test(code)) {
+                findLines(lines, new RegExp(`modelInstance\\s*=\\s*${varName}(?![?!])`)).forEach((line) => issues.push({
+                    severity: "error",
+                    rule: "composable/model-instance-null-check",
+                    message: `\`${varName}\` from \`rememberModelInstance\` is \`null\` while the asset loads. Guard it: \`${varName}?.let { ModelNode(modelInstance = it, ...) }\`.`,
+                    line,
+                }));
+            }
+            return issues;
+        },
+    },
+    // ─── LightNode trailing lambda instead of named `apply =` ────────────────
+    {
+        id: "api/light-node-trailing-lambda",
+        severity: "error",
+        check(code, lines) {
+            const issues = [];
+            // Matches: LightNode(...) { — trailing lambda, not apply = { inside parens
+            if (/LightNode\s*\([^)]*\)\s*\{/.test(code)) {
+                findLines(lines, /LightNode\s*\([^)]*\)\s*\{/).forEach((line) => issues.push({
+                    severity: "error",
+                    rule: "api/light-node-trailing-lambda",
+                    message: "`LightNode`'s configuration block is a **named parameter** `apply`, not a trailing lambda. Write `LightNode(engine = engine, type = ..., apply = { intensity(100_000f) })`. Without `apply =` the block is silently ignored and your light has default (zero) settings.",
+                    line,
+                }));
+            }
+            return issues;
+        },
+    },
+    // ─── Engine created manually in composable ────────────────────────────────
+    {
+        id: "lifecycle/manual-engine-create",
+        severity: "error",
+        check(code, lines) {
+            const issues = [];
+            findLines(lines, /Engine\.create\(/).forEach((line) => issues.push({
+                severity: "error",
+                rule: "lifecycle/manual-engine-create",
+                message: "`Engine.create()` called directly. In composables use `rememberEngine()` — it ties the Engine to the composition lifecycle and destroys it automatically on disposal, preventing leaks and double-destroy SIGABRTs.",
+                line,
+            }));
+            return issues;
+        },
+    },
+    // ─── Manual engine.destroy() alongside rememberEngine ────────────────────
+    {
+        id: "lifecycle/manual-engine-destroy",
+        severity: "warning",
+        check(code, lines) {
+            const issues = [];
+            if (!code.includes("rememberEngine"))
+                return issues;
+            findLines(lines, /engine\.(safeD|d)estroy\(\)/).forEach((line) => issues.push({
+                severity: "warning",
+                rule: "lifecycle/manual-engine-destroy",
+                message: "`engine.destroy()` called manually alongside `rememberEngine()`. The engine is already destroyed on composition disposal — calling it again triggers a SIGABRT. Remove the manual call.",
+                line,
+            }));
+            return issues;
+        },
+    },
+    // ─── Texture destroy order (issue #630) ──────────────────────────────────
+    {
+        id: "lifecycle/texture-destroy-order",
+        severity: "error",
+        check(code, lines) {
+            const issues = [];
+            const texIdx = code.indexOf("safeDestroyTexture");
+            const matIdx = code.indexOf("destroyMaterialInstance");
+            if (texIdx !== -1 && matIdx !== -1 && texIdx < matIdx) {
+                findLines(lines, /safeDestroyTexture|engine\.destroyTexture/).forEach((line) => issues.push({
+                    severity: "error",
+                    rule: "lifecycle/texture-destroy-order",
+                    message: "Texture destroyed **before** the MaterialInstance that references it → SIGABRT (\"Invalid texture still bound to MaterialInstance\"). Destroy the MaterialInstance first: `materialLoader.destroyMaterialInstance(instance)`, then `engine.safeDestroyTexture(texture)`.",
+                    line,
+                }));
+            }
+            return issues;
+        },
+    },
+    // ─── createModelInstance in composable (should be rememberModelInstance) ──
+    {
+        id: "composable/prefer-remember-model-instance",
+        severity: "warning",
+        check(code, lines) {
+            const issues = [];
+            findLines(lines, /modelLoader\.createModelInstance\(/).forEach((line) => issues.push({
+                severity: "warning",
+                rule: "composable/prefer-remember-model-instance",
+                message: "`modelLoader.createModelInstance()` blocks the main thread. In composables, use `rememberModelInstance(modelLoader, path)` — it loads asynchronously, returns `null` while loading, and recomposes when ready.",
+                line,
+            }));
+            return issues;
+        },
+    },
+    // ─── Empty AnchorNode() ────────────────────────────────────────────────────
+    {
+        id: "ar/anchor-node-missing-anchor",
+        severity: "error",
+        check(code, lines) {
+            const issues = [];
+            findLines(lines, /AnchorNode\s*\(\s*\)/).forEach((line) => issues.push({
+                severity: "error",
+                rule: "ar/anchor-node-missing-anchor",
+                message: "`AnchorNode()` requires an `anchor` from a hit result. Use `AnchorNode(anchor = hitResult.createAnchor())` inside `onTouchEvent` or `onSessionUpdated`.",
+                line,
+            }));
+            return issues;
+        },
+    },
+    // ─── 2.x → 3.0 renamed/removed APIs ─────────────────────────────────────
+    {
+        id: "migration/old-api",
+        severity: "error",
+        check(code, lines) {
+            const issues = [];
+            const renames = [
+                [/\bSceneView\s*\(/, "`SceneView(…)` → renamed to `Scene(…)` in 3.0"],
+                [/\bArSceneView\s*\(/, "`ArSceneView(…)` → renamed to `ARScene(…)` in 3.0"],
+                [/\bPlacementNode\b/, "`PlacementNode` removed → use `AnchorNode` + `HitResultNode` in 3.0"],
+                [/\bTransformableNode\b/, "`TransformableNode` removed → set `isEditable = true` on `ModelNode` in 3.0"],
+                [/\bViewRenderable\b/, "`ViewRenderable` removed → use `ViewNode` with a `@Composable` content lambda in 3.0"],
+                [/\bmodelLoader\.loadModelAsync\b/, "`loadModelAsync` removed → use `rememberModelInstance` in composables (3.0)"],
+                [/\bmodelLoader\.loadModel\b(?!Instance)/, "`loadModel` → use `rememberModelInstance` or `loadModelInstanceAsync` (3.0)"],
+            ];
+            for (const [pat, msg] of renames) {
+                if (pat.test(code)) {
+                    findLines(lines, pat).forEach((line) => issues.push({ severity: "error", rule: "migration/old-api", message: msg, line }));
+                }
+            }
+            return issues;
+        },
+    },
+    // ─── Scene missing engine param ───────────────────────────────────────────
+    {
+        id: "api/scene-missing-engine",
+        severity: "error",
+        check(code, lines) {
+            const issues = [];
+            // Scene( or ARScene( without engine = somewhere nearby
+            const sceneCallLines = findLines(lines, /\b(AR)?Scene\s*\(/);
+            sceneCallLines.forEach((line) => {
+                // Look at the next 10 lines for engine =
+                const block = lines.slice(line - 1, line + 10).join("\n");
+                if (!block.includes("engine")) {
+                    issues.push({
+                        severity: "error",
+                        rule: "api/scene-missing-engine",
+                        message: "`Scene` / `ARScene` requires an `engine` parameter. Create one with `val engine = rememberEngine()` and pass it: `Scene(engine = engine, …)`.",
+                        line,
+                    });
+                }
+            });
+            return issues;
+        },
+    },
+];
+export function validateCode(kotlinCode) {
+    const lines = kotlinCode.split("\n");
+    return RULES.flatMap((rule) => rule.check(kotlinCode, lines));
+}
+export function formatValidationReport(issues) {
+    if (issues.length === 0) {
+        return "✅ No issues found. The snippet follows SceneView best practices.";
+    }
+    const errors = issues.filter((i) => i.severity === "error");
+    const warnings = issues.filter((i) => i.severity === "warning");
+    const infos = issues.filter((i) => i.severity === "info");
+    const icon = {
+        error: "🔴",
+        warning: "🟡",
+        info: "🔵",
+    };
+    const header = `Found **${issues.length} issue(s)**: ${errors.length} error(s), ${warnings.length} warning(s), ${infos.length} info(s).\n`;
+    const body = issues
+        .map((issue, i) => {
+        const loc = issue.line ? ` (line ${issue.line})` : "";
+        return [
+            `### ${i + 1}. ${icon[issue.severity]} ${issue.severity.toUpperCase()}${loc}`,
+            `**Rule:** \`${issue.rule}\``,
+            issue.message,
+        ].join("\n");
+    })
+        .join("\n\n");
+    return header + "\n" + body;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sceneview-mcp",
-  "version": "3.0.1",
+  "version": "3.0.3",
   "description": "MCP server for SceneView — 3D and AR with Jetpack Compose for Android. Give Claude the full SceneView SDK so it writes correct, compilable Kotlin.",
   "keywords": [
     "mcp",
@@ -31,7 +31,11 @@
     "sceneview-mcp": "dist/index.js"
   },
   "files": [
-    "dist",
+    "dist/index.js",
+    "dist/issues.js",
+    "dist/migration.js",
+    "dist/samples.js",
+    "dist/validator.js",
     "llms.txt"
   ],
   "engines": {
@@ -41,7 +45,8 @@
     "build": "tsc",
     "prepare": "cp ../llms.txt ./llms.txt && tsc",
     "start": "node dist/index.js",
-    "dev": "tsx src/index.ts"
+    "dev": "tsx src/index.ts",
+    "test": "vitest run"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0"
@@ -49,6 +54,7 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
-    "typescript": "^5.8.0"
+    "typescript": "^5.8.0",
+    "vitest": "^4.1.0"
   }
 }