sceneview-mcp 3.4.12 → 3.4.13

package/dist/generate-scene.js

@@ -0,0 +1,325 @@
+/**
+ * generate-scene.ts
+ *
+ * Generates a complete Scene{} or ARScene{} composable from a text description.
+ * Maps common objects/concepts to SceneView node types and builds compilable code.
+ */
+const OBJECT_MAPPINGS = [
+    // Furniture
+    { keywords: ["table"], nodeType: "CubeNode", geometryType: "cube", defaultScale: 1.0, defaultPosition: [0, 0.4, 0], comment: "Table (flat cube)" },
+    { keywords: ["chair"], nodeType: "ModelNode", defaultScale: 0.8, defaultPosition: [0, 0, -1], comment: "Chair (use GLB model)" },
+    { keywords: ["desk"], nodeType: "CubeNode", geometryType: "cube", defaultScale: 1.2, defaultPosition: [0, 0.35, 0], comment: "Desk" },
+    { keywords: ["shelf", "bookshelf"], nodeType: "CubeNode", geometryType: "cube", defaultScale: 1.5, defaultPosition: [2, 0.75, 0], comment: "Shelf" },
+    { keywords: ["bed"], nodeType: "CubeNode", geometryType: "cube", defaultScale: 2.0, defaultPosition: [0, 0.25, 0], comment: "Bed" },
+    { keywords: ["sofa", "couch"], nodeType: "CubeNode", geometryType: "cube", defaultScale: 1.8, defaultPosition: [0, 0.35, 0], comment: "Sofa" },
+    // Basic shapes
+    { keywords: ["box", "cube", "crate"], nodeType: "CubeNode", geometryType: "cube", defaultScale: 0.5, defaultPosition: [0, 0.25, 0], comment: "Box" },
+    { keywords: ["sphere", "ball", "globe", "orb"], nodeType: "SphereNode", geometryType: "sphere", defaultScale: 0.5, defaultPosition: [0, 0.5, 0], comment: "Sphere" },
+    { keywords: ["cylinder", "pillar", "column"], nodeType: "CylinderNode", geometryType: "cylinder", defaultScale: 0.5, defaultPosition: [0, 0.5, 0], comment: "Cylinder" },
+    { keywords: ["plane", "floor", "ground"], nodeType: "PlaneNode", geometryType: "plane", defaultScale: 5.0, defaultPosition: [0, 0, 0], comment: "Ground plane" },
+    { keywords: ["wall"], nodeType: "CubeNode", geometryType: "cube", defaultScale: 3.0, defaultPosition: [0, 1.5, -3], comment: "Wall" },
+    // Environment
+    { keywords: ["tree", "plant"], nodeType: "ModelNode", defaultScale: 2.0, defaultPosition: [2, 0, 2], comment: "Tree (use GLB model)" },
+    { keywords: ["car", "vehicle"], nodeType: "ModelNode", defaultScale: 2.0, defaultPosition: [0, 0, 0], comment: "Car (use GLB model)" },
+    { keywords: ["house", "building"], nodeType: "ModelNode", defaultScale: 5.0, defaultPosition: [0, 0, -5], comment: "Building (use GLB model)" },
+    // People / characters
+    { keywords: ["person", "character", "human", "avatar", "robot"], nodeType: "ModelNode", defaultScale: 1.7, defaultPosition: [0, 0, 0], comment: "Character (use GLB model)" },
+];
+const LIGHT_KEYWORDS = ["sun", "sunlight", "daylight", "bright", "lit", "sunny", "well-lit"];
+const INDOOR_KEYWORDS = ["room", "indoor", "inside", "interior"];
+const OUTDOOR_KEYWORDS = ["outdoor", "outside", "garden", "park", "street"];
+const AR_KEYWORDS = ["ar", "augmented", "real world", "camera", "place in room", "place on"];
+const DARK_KEYWORDS = ["night", "dark", "dim", "mood", "candlelight"];
+function parseDescription(description) {
+    const lower = description.toLowerCase();
+    const objects = [];
+    // Parse quantity + object patterns
+    for (const mapping of OBJECT_MAPPINGS) {
+        for (const keyword of mapping.keywords) {
+            // Match "two chairs", "3 tables", "a chair", "chairs"
+            const countPatterns = [
+                new RegExp(`(\\d+)\\s+${keyword}s?`, "i"),
+                new RegExp(`(one|two|three|four|five|six|seven|eight|nine|ten)\\s+${keyword}s?`, "i"),
+                new RegExp(`(a|an)\\s+${keyword}\\b`, "i"),
+                new RegExp(`\\b${keyword}s\\b`, "i"), // plural without number = 2
+                new RegExp(`\\b${keyword}\\b`, "i"), // singular without article = 1
+            ];
+            for (const pat of countPatterns) {
+                const match = lower.match(pat);
+                if (match) {
+                    let count = 1;
+                    if (match[1]) {
+                        const numWords = {
+                            one: 1, two: 2, three: 3, four: 4, five: 5,
+                            six: 6, seven: 7, eight: 8, nine: 9, ten: 10,
+                            a: 1, an: 1,
+                        };
+                        count = numWords[match[1].toLowerCase()] || parseInt(match[1]) || 1;
+                    }
+                    if (pat.source.includes("s\\b") && !match[1])
+                        count = 2; // plural default
+                    objects.push({ mapping, count });
+                    break;
+                }
+            }
+        }
+    }
+    // Deduplicate
+    const seen = new Set();
+    const unique = objects.filter((o) => {
+        const key = o.mapping.keywords[0];
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    return {
+        objects: unique,
+        isAR: AR_KEYWORDS.some((k) => lower.includes(k)),
+        isIndoor: INDOOR_KEYWORDS.some((k) => lower.includes(k)),
+        isOutdoor: OUTDOOR_KEYWORDS.some((k) => lower.includes(k)),
+        needsSky: OUTDOOR_KEYWORDS.some((k) => lower.includes(k)) || lower.includes("sky"),
+        isDark: DARK_KEYWORDS.some((k) => lower.includes(k)),
+    };
+}
+function spreadPositions(count, basePos, spacing) {
+    if (count === 1)
+        return [basePos];
+    const positions = [];
+    const halfSpan = ((count - 1) * spacing) / 2;
+    for (let i = 0; i < count; i++) {
+        positions.push([
+            basePos[0] + i * spacing - halfSpan,
+            basePos[1],
+            basePos[2],
+        ]);
+    }
+    return positions;
+}
+export function generateScene(description) {
+    const parsed = parseDescription(description);
+    const elements = [];
+    const notes = [];
+    const dependencies = [];
+    let hasModel = false;
+    // Track geometry node counters for naming
+    let nodeCounter = 0;
+    // Generate elements for each parsed object
+    for (const obj of parsed.objects) {
+        const positions = spreadPositions(obj.count, obj.mapping.defaultPosition, 1.5);
+        for (let i = 0; i < obj.count; i++) {
+            const pos = positions[i];
+            if (obj.mapping.nodeType === "ModelNode") {
+                hasModel = true;
+                elements.push({
+                    type: "model",
+                    nodeType: "ModelNode",
+                    properties: {
+                        modelPath: `models/${obj.mapping.keywords[0]}.glb`,
+                        scaleToUnits: String(obj.mapping.defaultScale),
+                        position: `Position(${pos[0].toFixed(1)}f, ${pos[1].toFixed(1)}f, ${pos[2].toFixed(1)}f)`,
+                    },
+                    comment: obj.mapping.comment,
+                });
+            }
+            else {
+                elements.push({
+                    type: "geometry",
+                    nodeType: obj.mapping.nodeType,
+                    properties: {
+                        size: String(obj.mapping.defaultScale),
+                        position: `Position(${pos[0].toFixed(1)}f, ${pos[1].toFixed(1)}f, ${pos[2].toFixed(1)}f)`,
+                    },
+                    comment: obj.mapping.comment,
+                });
+            }
+            nodeCounter++;
+        }
+    }
+    // Add light
+    if (!parsed.isDark) {
+        elements.push({
+            type: "light",
+            nodeType: "LightNode",
+            properties: {
+                type: "LightManager.Type.DIRECTIONAL",
+                intensity: parsed.isOutdoor ? "110_000f" : "100_000f",
+                castShadows: "true",
+            },
+            comment: parsed.isOutdoor ? "Sunlight" : "Main directional light",
+        });
+    }
+    else {
+        elements.push({
+            type: "light",
+            nodeType: "LightNode",
+            properties: {
+                type: "LightManager.Type.POINT",
+                intensity: "50_000f",
+                position: "Position(0f, 2f, 0f)",
+                castShadows: "false",
+            },
+            comment: "Dim ambient light",
+        });
+    }
+    // Add ground plane if not already present
+    const hasGround = elements.some((e) => e.nodeType === "PlaneNode" || (e.comment && e.comment.toLowerCase().includes("ground")));
+    if (!hasGround && !parsed.isAR) {
+        elements.push({
+            type: "geometry",
+            nodeType: "PlaneNode",
+            properties: {
+                size: "10.0f",
+                position: "Position(0f, 0f, 0f)",
+            },
+            comment: "Ground plane",
+        });
+    }
+    // Build the code
+    const isAR = parsed.isAR;
+    dependencies.push(isAR ? "io.github.sceneview:arsceneview:3.3.0" : "io.github.sceneview:sceneview:3.3.0");
+    // Build model instance declarations
+    const modelElements = elements.filter((e) => e.type === "model");
+    const uniqueModels = new Map();
+    modelElements.forEach((e) => {
+        const path = e.properties.modelPath;
+        if (!uniqueModels.has(path)) {
+            const varName = path.replace("models/", "").replace(".glb", "").replace(/[^a-zA-Z0-9]/g, "") + "Instance";
+            uniqueModels.set(path, varName);
+        }
+    });
+    // Generate Kotlin code
+    const lines = [];
+    lines.push("@Composable");
+    lines.push(`fun GeneratedScene() {`);
+    lines.push("    val engine = rememberEngine()");
+    lines.push("    val modelLoader = rememberModelLoader(engine)");
+    if (!isAR) {
+        lines.push("    val environmentLoader = rememberEnvironmentLoader(engine)");
+    }
+    lines.push("");
+    // Model instance declarations
+    for (const [path, varName] of uniqueModels) {
+        lines.push(`    val ${varName} = rememberModelInstance(modelLoader, "${path}")`);
+    }
+    if (uniqueModels.size > 0)
+        lines.push("");
+    // Scene or ARScene
+    if (isAR) {
+        lines.push("    var anchor by remember { mutableStateOf<Anchor?>(null) }");
+        lines.push("");
+        lines.push("    ARScene(");
+        lines.push("        modifier = Modifier.fillMaxSize(),");
+        lines.push("        engine = engine,");
+        lines.push("        modelLoader = modelLoader,");
+        lines.push("        planeRenderer = true,");
+        lines.push("        onTouchEvent = { event, hitResult ->");
+        lines.push("            if (event.action == MotionEvent.ACTION_UP && hitResult != null) {");
+        lines.push("                anchor = hitResult.createAnchor()");
+        lines.push("            }");
+        lines.push("            true");
+        lines.push("        }");
+        lines.push("    ) {");
+        lines.push("        anchor?.let { a ->");
+        lines.push("            AnchorNode(anchor = a) {");
+    }
+    else {
+        lines.push("    Scene(");
+        lines.push("        modifier = Modifier.fillMaxSize(),");
+        lines.push("        engine = engine,");
+        lines.push("        modelLoader = modelLoader,");
+        if (!parsed.isDark) {
+            lines.push('        environment = rememberEnvironment(environmentLoader) {');
+            lines.push('            environmentLoader.createHDREnvironment("environments/sky_2k.hdr")');
+            lines.push('                ?: createEnvironment(environmentLoader)');
+            lines.push("        }");
+        }
+        lines.push("    ) {");
+    }
+    const indent = isAR ? "                " : "        ";
+    // Generate nodes
+    for (const elem of elements) {
+        lines.push(`${indent}// ${elem.comment}`);
+        switch (elem.type) {
+            case "model": {
+                const varName = uniqueModels.get(elem.properties.modelPath);
+                lines.push(`${indent}${varName}?.let { instance ->`);
+                lines.push(`${indent}    ModelNode(`);
+                lines.push(`${indent}        modelInstance = instance,`);
+                lines.push(`${indent}        scaleToUnits = ${elem.properties.scaleToUnits}f,`);
+                if (elem.properties.position !== "Position(0.0f, 0.0f, 0.0f)") {
+                    lines.push(`${indent}        centerOrigin = ${elem.properties.position}`);
+                }
+                lines.push(`${indent}    )`);
+                lines.push(`${indent}}`);
+                break;
+            }
+            case "geometry": {
+                const nodeType = elem.nodeType;
+                lines.push(`${indent}${nodeType}(`);
+                lines.push(`${indent}    engine = engine,`);
+                lines.push(`${indent}    size = ${elem.properties.size}`);
+                lines.push(`${indent})`);
+                break;
+            }
+            case "light": {
+                lines.push(`${indent}LightNode(`);
+                lines.push(`${indent}    engine = engine,`);
+                lines.push(`${indent}    type = ${elem.properties.type},`);
+                lines.push(`${indent}    apply = {`);
+                lines.push(`${indent}        intensity(${elem.properties.intensity})`);
+                lines.push(`${indent}        castShadows(${elem.properties.castShadows})`);
+                lines.push(`${indent}    }`);
+                lines.push(`${indent})`);
+                break;
+            }
+        }
+        lines.push("");
+    }
+    // Close braces
+    if (isAR) {
+        lines.push("            }");
+        lines.push("        }");
+    }
+    lines.push("    }");
+    lines.push("}");
+    // Notes
+    if (hasModel) {
+        notes.push("This scene references GLB model files. You need to provide actual .glb files in `src/main/assets/models/`.");
+        notes.push("Free 3D models: https://sketchfab.com/features/free-3d-models (download as GLB)");
+    }
+    if (isAR) {
+        notes.push("AR requires camera permission at runtime and ARCore on the device. See `get_platform_setup(\"android\", \"ar\")` for full setup.");
+    }
+    if (elements.length === 1) {
+        notes.push("Only a light was generated. The description didn't match any known objects. Try mentioning specific objects like 'table', 'chair', 'sphere', 'cube', etc.");
+    }
+    return {
+        code: lines.join("\n"),
+        description,
+        elements,
+        isAR,
+        dependencies,
+        notes,
+    };
+}
+export function formatGeneratedScene(result) {
+    const parts = [];
+    parts.push(`## Generated Scene\n`);
+    parts.push(`**Description:** "${result.description}"`);
+    parts.push(`**Mode:** ${result.isAR ? "AR (ARScene)" : "3D (Scene)"}`);
+    parts.push(`**Elements:** ${result.elements.length} nodes\n`);
+    parts.push(`### Dependency\n`);
+    parts.push("```kotlin");
+    result.dependencies.forEach((d) => parts.push(`implementation("${d}")`));
+    parts.push("```\n");
+    parts.push(`### Code\n`);
+    parts.push("```kotlin");
+    parts.push(result.code);
+    parts.push("```\n");
+    if (result.notes.length > 0) {
+        parts.push(`### Notes\n`);
+        result.notes.forEach((n, i) => parts.push(`${i + 1}. ${n}`));
+    }
+    return parts.join("\n");
+}

package/dist/index.js

@@ -13,6 +13,10 @@ import { parseNodeSections, findNodeSection, listNodeTypes } from "./node-refere
 import { PLATFORM_ROADMAP, BEST_PRACTICES, AR_SETUP_GUIDE, TROUBLESHOOTING_GUIDE } from "./guides.js";
 import { buildPreviewUrl, validatePreviewInput, formatPreviewResponse } from "./preview.js";
 import { validateArtifactInput, generateArtifact, formatArtifactResponse } from "./artifact.js";
+import { getPlatformSetup, PLATFORM_IDS } from "./platform-setup.js";
+import { migrateCode, formatMigrationResult } from "./migrate-code.js";
+import { getDebugGuide, autoDetectIssue, DEBUG_CATEGORIES } from "./debug-issue.js";
+import { generateScene, formatGeneratedScene } from "./generate-scene.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // ─── Legal disclaimer ─────────────────────────────────────────────────────────
 const DISCLAIMER = '\n\n---\n*Generated code suggestion. Review before use in production. See [TERMS.md](https://github.com/SceneView/sceneview/blob/main/mcp/TERMS.md).*';
@@ -33,7 +37,7 @@ catch {
     API_DOCS = "SceneView API docs not found. Run `npm run prepare` to bundle llms.txt.";
 }
 const NODE_SECTIONS = parseNodeSections(API_DOCS);
-const server = new Server({ name: "@sceneview/mcp", version: "3.4.11" }, { capabilities: { resources: {}, tools: {} } });
+const server = new Server({ name: "@sceneview/mcp", version: "3.4.13" }, { capabilities: { resources: {}, tools: {} } });
 // ─── Resources ───────────────────────────────────────────────────────────────
 server.setRequestHandler(ListResourcesRequestSchema, async () => ({
     resources: [
@@ -344,6 +348,73 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["type"],
             },
         },
+        {
+            name: "get_platform_setup",
+            description: "Returns the complete setup guide for any SceneView-supported platform: Android, iOS, Web, Flutter, React Native, Desktop, or Android TV. Includes dependencies, manifest/permissions, minimum SDK, and a working starter template. Replaces `get_setup`, `get_ios_setup`, and `get_web_setup` with a single unified tool. Use this when a user wants to set up SceneView on any platform.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    platform: {
+                        type: "string",
+                        enum: PLATFORM_IDS,
+                        description: `Target platform:\n${PLATFORM_IDS.map((p) => `- "${p}"`).join("\n")}`,
+                    },
+                    type: {
+                        type: "string",
+                        enum: ["3d", "ar"],
+                        description: '"3d" for 3D-only scenes. "ar" for augmented reality. Some platforms only support 3D.',
+                    },
+                },
+                required: ["platform", "type"],
+            },
+        },
+        {
+            name: "migrate_code",
+            description: "Automatically migrates SceneView 2.x Kotlin code to 3.x. Applies known renames (SceneView→Scene, ArSceneView→ARScene), replaces deprecated APIs (loadModelAsync→rememberModelInstance, Engine.create→rememberEngine), fixes LightNode trailing-lambda bug, removes Sceneform imports, and more. Returns the migrated code with a detailed changelog. Use this when a user has 2.x code that needs updating, or when you detect 2.x patterns in their code.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    code: {
+                        type: "string",
+                        description: "The SceneView 2.x Kotlin code to migrate. Can be a snippet, a function, or a full file.",
+                    },
+                },
+                required: ["code"],
+            },
+        },
+        {
+            name: "debug_issue",
+            description: 'Returns a targeted debugging guide for a specific SceneView issue. Categories: "model-not-showing" (invisible models), "ar-not-working" (AR camera/planes), "crash" (SIGABRT/native), "performance" (low FPS/memory), "build-error" (Gradle/dependency), "black-screen" (no rendering), "lighting" (dark/bright/shadows), "gestures" (touch/drag), "ios" (Swift/RealityKit). You can provide a category directly, or describe the problem and it will be auto-detected. Use this when a user reports something not working.',
+            inputSchema: {
+                type: "object",
+                properties: {
+                    category: {
+                        type: "string",
+                        enum: DEBUG_CATEGORIES,
+                        description: `The issue category. If omitted, provide \`description\` for auto-detection.\n${DEBUG_CATEGORIES.map((c) => `- "${c}"`).join("\n")}`,
+                    },
+                    description: {
+                        type: "string",
+                        description: 'Free-text description of the issue (e.g., "my model is not showing", "app crashes on destroy"). Used for auto-detection when category is omitted.',
+                    },
+                },
+                required: [],
+            },
+        },
+        {
+            name: "generate_scene",
+            description: 'Generates a complete, compilable Scene{} or ARScene{} Kotlin composable from a natural language description. Parses objects (table, chair, sphere, car, etc.), quantities ("two chairs", "3 spheres"), environment (indoor/outdoor/dark), and mode (3D or AR). Returns working Kotlin code with proper engine setup, model loading, lighting, and ground plane. Use this when a user says "build me a scene with..." or describes a 3D scene they want to create.',
+            inputSchema: {
+                type: "object",
+                properties: {
+                    description: {
+                        type: "string",
+                        description: 'Natural language description of the desired 3D scene. Examples: "a room with a table and two chairs", "AR scene with a robot on the floor", "outdoor scene with three trees and a car", "dark room with a sphere and a cube".',
+                    },
+                },
+                required: ["description"],
+            },
+        },
     ],
 }));
 // ─── Tool handlers ────────────────────────────────────────────────────────────
@@ -874,6 +945,67 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const text = formatArtifactResponse(result);
             return { content: withDisclaimer([{ type: "text", text }]) };
         }
+        // ── get_platform_setup ─────────────────────────────────────────────────
+        case "get_platform_setup": {
+            const platform = request.params.arguments?.platform;
+            const setupType = request.params.arguments?.type;
+            if (!platform || !setupType) {
+                return {
+                    content: [{ type: "text", text: "Missing required parameters: `platform` and `type`." }],
+                    isError: true,
+                };
+            }
+            const guide = getPlatformSetup(platform, setupType);
+            return { content: withDisclaimer([{ type: "text", text: guide }]) };
+        }
+        // ── migrate_code ─────────────────────────────────────────────────────────
+        case "migrate_code": {
+            const code = request.params.arguments?.code;
+            if (!code || typeof code !== "string") {
+                return {
+                    content: [{ type: "text", text: "Missing required parameter: `code`." }],
+                    isError: true,
+                };
+            }
+            const migrationResult = migrateCode(code);
+            const migrationReport = formatMigrationResult(migrationResult);
+            return { content: withDisclaimer([{ type: "text", text: migrationReport }]) };
+        }
+        // ── debug_issue ──────────────────────────────────────────────────────────
+        case "debug_issue": {
+            let category = request.params.arguments?.category;
+            const desc = request.params.arguments?.description;
+            if (!category && desc) {
+                category = autoDetectIssue(desc) ?? undefined;
+            }
+            if (!category) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Please provide a \`category\` or \`description\`.\n\nAvailable categories: ${DEBUG_CATEGORIES.join(", ")}`,
+                        }],
+                    isError: true,
+                };
+            }
+            const debugGuide = getDebugGuide(category);
+            const prefix = desc && autoDetectIssue(desc) === category
+                ? `> Auto-detected category: **${category}** from your description.\n\n`
+                : "";
+            return { content: withDisclaimer([{ type: "text", text: prefix + debugGuide }]) };
+        }
+        // ── generate_scene ───────────────────────────────────────────────────────
+        case "generate_scene": {
+            const sceneDesc = request.params.arguments?.description;
+            if (!sceneDesc || typeof sceneDesc !== "string") {
+                return {
+                    content: [{ type: "text", text: "Missing required parameter: `description`." }],
+                    isError: true,
+                };
+            }
+            const sceneResult = generateScene(sceneDesc);
+            const sceneReport = formatGeneratedScene(sceneResult);
+            return { content: withDisclaimer([{ type: "text", text: sceneReport }]) };
+        }
         default:
             return {
                 content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],