sceneview-mcp 3.0.0 → 3.0.2

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/dist/validator.test.js

@@ -0,0 +1,246 @@
+import { describe, it, expect } from "vitest";
+import { validateCode, formatValidationReport } from "./validator.js";
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function ruleIds(code) {
+    return validateCode(code).map((i) => i.rule);
+}
+function hasRule(code, rule) {
+    return ruleIds(code).includes(rule);
+}
+// ─── threading/filament-off-main-thread ──────────────────────────────────────
+describe("threading/filament-off-main-thread", () => {
+    const RULE = "threading/filament-off-main-thread";
+    it("fires when modelLoader.createModel* used near Dispatchers.IO", () => {
+        const code = `
+      withContext(Dispatchers.IO) {
+        val model = modelLoader.createModelInstance("models/chair.glb")
+      }
+    `;
+        expect(hasRule(code, RULE)).toBe(true);
+    });
+    it("fires when Texture.Builder used near Dispatchers.Default", () => {
+        const code = `
+      launch(Dispatchers.Default) {
+        val texture = Texture.Builder().width(4).build(engine)
+      }
+    `;
+        expect(hasRule(code, RULE)).toBe(true);
+    });
+    it("does NOT fire without a background dispatcher", () => {
+        const code = `val model = modelLoader.createModelInstance("models/chair.glb")`;
+        expect(hasRule(code, RULE)).toBe(false);
+    });
+    it("does NOT fire when Dispatchers.Main is used", () => {
+        const code = `
+      withContext(Dispatchers.Main) {
+        val model = modelLoader.createModelInstance("models/chair.glb")
+      }
+    `;
+        expect(hasRule(code, RULE)).toBe(false);
+    });
+});
+// ─── ar/node-not-anchor ───────────────────────────────────────────────────────
+describe("ar/node-not-anchor", () => {
+    const RULE = "ar/node-not-anchor";
+    it("fires when worldPosition is set inside an ARScene", () => {
+        const code = `
+      ARScene(engine = engine) {
+        node.worldPosition = Position(0f, 0f, -1f)
+      }
+    `;
+        expect(hasRule(code, RULE)).toBe(true);
+    });
+    it("does NOT fire for worldPosition outside ARScene", () => {
+        const code = `node.worldPosition = Position(0f, 0f, -1f)`;
+        expect(hasRule(code, RULE)).toBe(false);
+    });
+    it("does NOT fire when AnchorNode is used correctly", () => {
+        const code = `
+      ARScene(engine = engine) {
+        AnchorNode(anchor = hitResult.createAnchor()) { }
+      }
+    `;
+        expect(hasRule(code, RULE)).toBe(false);
+    });
+});
+// ─── composable/model-instance-null-check ────────────────────────────────────
+describe("composable/model-instance-null-check", () => {
+    const RULE = "composable/model-instance-null-check";
+    it("fires when rememberModelInstance result used without null guard", () => {
+        const code = `
+      val instance = rememberModelInstance(modelLoader, "models/chair.glb")
+      ModelNode(modelInstance = instance, scaleToUnits = 1f)
+    `;
+        expect(hasRule(code, RULE)).toBe(true);
+    });
+    it("does NOT fire when guarded with ?.", () => {
+        const code = `
+      val instance = rememberModelInstance(modelLoader, "models/chair.glb")
+      instance?.let { ModelNode(modelInstance = it) }
+    `;
+        expect(hasRule(code, RULE)).toBe(false);
+    });
+    it("does NOT fire when guarded with !!", () => {
+        const code = `
+      val instance = rememberModelInstance(modelLoader, "models/chair.glb")
+      ModelNode(modelInstance = instance!!, scaleToUnits = 1f)
+    `;
+        expect(hasRule(code, RULE)).toBe(false);
+    });
+    it("does NOT fire when rememberModelInstance is not assigned to a var", () => {
+        const code = `ModelNode(modelInstance = someOtherInstance, scaleToUnits = 1f)`;
+        expect(hasRule(code, RULE)).toBe(false);
+    });
+});
+// ─── api/light-node-trailing-lambda ──────────────────────────────────────────
+describe("api/light-node-trailing-lambda", () => {
+    const RULE = "api/light-node-trailing-lambda";
+    it("fires on trailing lambda syntax", () => {
+        const code = `LightNode(engine = engine, type = LightManager.Type.SUN) { intensity(100_000f) }`;
+        expect(hasRule(code, RULE)).toBe(true);
+    });
+    it("does NOT fire when apply = { } is used correctly", () => {
+        const code = `LightNode(engine = engine, type = LightManager.Type.SUN, apply = { intensity(100_000f) })`;
+        expect(hasRule(code, RULE)).toBe(false);
+    });
+});
+// ─── lifecycle/manual-engine-create ──────────────────────────────────────────
+describe("lifecycle/manual-engine-create", () => {
+    const RULE = "lifecycle/manual-engine-create";
+    it("fires on Engine.create()", () => {
+        const code = `val engine = Engine.create(eglContext)`;
+        expect(hasRule(code, RULE)).toBe(true);
+    });
+    it("does NOT fire when rememberEngine() is used", () => {
+        const code = `val engine = rememberEngine()`;
+        expect(hasRule(code, RULE)).toBe(false);
+    });
+});
+// ─── lifecycle/manual-engine-destroy ─────────────────────────────────────────
+describe("lifecycle/manual-engine-destroy", () => {
+    const RULE = "lifecycle/manual-engine-destroy";
+    it("fires when engine.destroy() called alongside rememberEngine", () => {
+        const code = `
+      val engine = rememberEngine()
+      DisposableEffect(Unit) { onDispose { engine.destroy() } }
+    `;
+        expect(hasRule(code, RULE)).toBe(true);
+    });
+    it("does NOT fire when rememberEngine is absent (imperative code)", () => {
+        const code = `engine.destroy()`;
+        expect(hasRule(code, RULE)).toBe(false);
+    });
+});
+// ─── lifecycle/texture-destroy-order ─────────────────────────────────────────
+describe("lifecycle/texture-destroy-order", () => {
+    const RULE = "lifecycle/texture-destroy-order";
+    it("fires when texture is destroyed before material instance", () => {
+        const code = `
+      engine.safeDestroyTexture(texture)
+      materialLoader.destroyMaterialInstance(instance)
+    `;
+        expect(hasRule(code, RULE)).toBe(true);
+    });
+    it("does NOT fire when material instance destroyed first", () => {
+        const code = `
+      materialLoader.destroyMaterialInstance(instance)
+      engine.safeDestroyTexture(texture)
+    `;
+        expect(hasRule(code, RULE)).toBe(false);
+    });
+    it("does NOT fire when only one of the two is present", () => {
+        expect(hasRule(`engine.safeDestroyTexture(texture)`, RULE)).toBe(false);
+        expect(hasRule(`materialLoader.destroyMaterialInstance(instance)`, RULE)).toBe(false);
+    });
+});
+// ─── composable/prefer-remember-model-instance ────────────────────────────────
+describe("composable/prefer-remember-model-instance", () => {
+    const RULE = "composable/prefer-remember-model-instance";
+    it("fires when createModelInstance is used directly", () => {
+        const code = `val m = modelLoader.createModelInstance("models/chair.glb")`;
+        expect(hasRule(code, RULE)).toBe(true);
+    });
+    it("does NOT fire for rememberModelInstance", () => {
+        const code = `val m = rememberModelInstance(modelLoader, "models/chair.glb")`;
+        expect(hasRule(code, RULE)).toBe(false);
+    });
+});
+// ─── ar/anchor-node-missing-anchor ───────────────────────────────────────────
+describe("ar/anchor-node-missing-anchor", () => {
+    const RULE = "ar/anchor-node-missing-anchor";
+    it("fires on empty AnchorNode()", () => {
+        const code = `val node = AnchorNode()`;
+        expect(hasRule(code, RULE)).toBe(true);
+    });
+    it("does NOT fire when anchor param is provided", () => {
+        const code = `AnchorNode(anchor = hitResult.createAnchor())`;
+        expect(hasRule(code, RULE)).toBe(false);
+    });
+});
+// ─── migration/old-api ────────────────────────────────────────────────────────
+describe("migration/old-api", () => {
+    const RULE = "migration/old-api";
+    it("fires on SceneView composable", () => {
+        expect(hasRule(`SceneView(modifier = Modifier.fillMaxSize())`, RULE)).toBe(true);
+    });
+    it("fires on ArSceneView composable", () => {
+        expect(hasRule(`ArSceneView(modifier = Modifier.fillMaxSize())`, RULE)).toBe(true);
+    });
+    it("fires on TransformableNode", () => {
+        expect(hasRule(`val node = TransformableNode(system)`, RULE)).toBe(true);
+    });
+    it("fires on PlacementNode", () => {
+        expect(hasRule(`val node = PlacementNode()`, RULE)).toBe(true);
+    });
+    it("fires on ViewRenderable", () => {
+        expect(hasRule(`ViewRenderable.builder()`, RULE)).toBe(true);
+    });
+    it("fires on loadModelAsync", () => {
+        expect(hasRule(`modelLoader.loadModelAsync("models/x.glb")`, RULE)).toBe(true);
+    });
+    it("does NOT fire on modern 3.0 APIs", () => {
+        const code = `
+      val engine = rememberEngine()
+      Scene(engine = engine) {
+        rememberModelInstance(modelLoader, "models/x.glb")?.let { ModelNode(modelInstance = it) }
+      }
+    `;
+        expect(hasRule(code, RULE)).toBe(false);
+    });
+});
+// ─── api/scene-missing-engine ─────────────────────────────────────────────────
+describe("api/scene-missing-engine", () => {
+    const RULE = "api/scene-missing-engine";
+    it("fires when Scene() has no engine nearby", () => {
+        const code = `Scene(modifier = Modifier.fillMaxSize()) { }`;
+        expect(hasRule(code, RULE)).toBe(true);
+    });
+    it("does NOT fire when engine is provided", () => {
+        const code = `
+      val engine = rememberEngine()
+      Scene(modifier = Modifier.fillMaxSize(), engine = engine) { }
+    `;
+        expect(hasRule(code, RULE)).toBe(false);
+    });
+});
+// ─── formatValidationReport ───────────────────────────────────────────────────
+describe("formatValidationReport", () => {
+    it("returns success message when no issues", () => {
+        expect(formatValidationReport([])).toContain("No issues found");
+    });
+    it("includes severity counts in the header", () => {
+        const issues = validateCode(`
+      val instance = rememberModelInstance(modelLoader, "x.glb")
+      ModelNode(modelInstance = instance, scaleToUnits = 1f)
+      LightNode(engine = engine) { intensity(1f) }
+    `);
+        const report = formatValidationReport(issues);
+        expect(report).toMatch(/error/);
+        expect(report).toContain("🔴");
+    });
+    it("includes line numbers when available", () => {
+        const code = `\nval instance = rememberModelInstance(modelLoader, "x.glb")\nModelNode(modelInstance = instance, scaleToUnits = 1f)`;
+        const report = formatValidationReport(validateCode(code));
+        expect(report).toMatch(/line \d+/);
+    });
+});

package/package.json

@@ -1,9 +1,31 @@
 {
   "name": "sceneview-mcp",
-  "version": "3.0.0",
-  "description": "MCP server for SceneView — 3D and AR with Jetpack Compose for Android",
-  "keywords": ["mcp", "sceneview", "android", "ar", "3d", "compose", "filament", "arcore"],
+  "version": "3.0.2",
+  "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",
+    "model-context-protocol",
+    "sceneview",
+    "android",
+    "ar",
+    "arcore",
+    "3d",
+    "filament",
+    "jetpack-compose",
+    "claude",
+    "ai"
+  ],
   "license": "MIT",
+  "author": "SceneView (https://github.com/SceneView)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SceneView/sceneview-android.git",
+    "directory": "mcp"
+  },
+  "homepage": "https://github.com/SceneView/sceneview-android/tree/main/mcp#readme",
+  "bugs": {
+    "url": "https://github.com/SceneView/sceneview-android/issues"
+  },
   "type": "module",
   "bin": {
     "sceneview-mcp": "dist/index.js"
@@ -12,11 +34,15 @@
     "dist",
     "llms.txt"
   ],
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "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"
@@ -24,6 +50,7 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsx": "^4.0.0",
-    "typescript": "^5.8.0"
+    "typescript": "^5.8.0",
+    "vitest": "^4.1.0"
   }
 }