sceneview-mcp 3.0.0

package/README.md

@@ -0,0 +1,171 @@
+# sceneview-mcp
+
+MCP server for [SceneView](https://github.com/SceneView/sceneview-android) — 3D and AR with Jetpack Compose for Android.
+
+Install this once and Claude always knows how to use SceneView. No copy-pasting docs. No hallucinated APIs.
+
+---
+
+## What it provides
+
+**Resource — `sceneview://api`**
+The complete SceneView 3.0.0 API reference (llms.txt): composable signatures, node types, AR scope, resource loading, threading rules, common patterns.
+
+**Tool — `get_sample`**
+
+| Scenario | What you get |
+|---|---|
+| `model-viewer` | Full-screen 3D scene, HDR environment, orbit camera |
+| `ar-tap-to-place` | AR tap-to-place with pinch-to-scale and drag-to-rotate |
+| `ar-placement-cursor` | AR reticle that snaps to surfaces, tap to confirm |
+| `ar-augmented-image` | Detect a reference image, overlay a 3D model |
+| `ar-face-filter` | Front-camera face mesh with a custom material |
+
+**Tool — `get_setup`**
+Gradle dependency + AndroidManifest for `"3d"` or `"ar"` projects.
+
+---
+
+## Installation
+
+### Project-level (recommended)
+
+Add `.claude/mcp.json` at your Android project root:
+
+```json
+{
+  "mcpServers": {
+    "sceneview": {
+      "command": "npx",
+      "args": ["-y", "sceneview-mcp"]
+    }
+  }
+}
+```
+
+Run `/mcp` in Claude Code to confirm the server is connected.
+
+### Global (all projects)
+
+Add to `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "sceneview": {
+      "command": "npx",
+      "args": ["-y", "sceneview-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "sceneview": {
+      "command": "npx",
+      "args": ["-y", "sceneview-mcp"]
+    }
+  }
+}
+```
+
+---
+
+## How it works
+
+```
+Developer: "add AR placement to my app"
+         │
+         ▼
+Claude reads sceneview://api  ←  full llms.txt, always current
+         │
+         ▼
+Claude calls get_sample("ar-tap-to-place")  ←  working Kotlin boilerplate
+         │
+         ▼
+Correct, compilable SceneView 3.0.0 code — first try, zero hallucination
+```
+
+---
+
+## Sample prompts
+
+### 3D model viewer
+```
+Create an Android Compose screen called ModelViewerScreen that loads
+assets/models/my_model.glb in a full-screen 3D scene with orbit camera and HDR
+environment from assets/environments/sky_2k.hdr.
+Use SceneView io.github.sceneview:sceneview:3.0.0.
+```
+
+### AR tap-to-place
+```
+Create an Android Compose AR screen called TapToPlaceScreen. Show a plane
+detection grid. Tapping places assets/models/chair.glb on the surface with
+pinch-to-scale and drag-to-rotate. Multiple taps = multiple objects.
+Use SceneView io.github.sceneview:arsceneview:3.0.0.
+```
+
+### AR placement cursor
+```
+Create an AR screen called ARCursorScreen with a reticle that snaps to surfaces
+at screen center. Tap to place assets/models/object.glb and hide the reticle.
+Use SceneView io.github.sceneview:arsceneview:3.0.0.
+```
+
+### AR augmented image
+```
+Create an AR screen called AugmentedImageScreen that detects R.drawable.target_image
+(15 cm wide) and places assets/models/overlay.glb above it scaled to image width.
+Model disappears when tracking is lost.
+Use SceneView io.github.sceneview:arsceneview:3.0.0.
+```
+
+### AR face filter
+```
+Create an AR screen called FaceFilterScreen using the front camera that detects
+faces and applies assets/materials/face_mask.filamat to the face mesh.
+Use SceneView io.github.sceneview:arsceneview:3.0.0.
+```
+
+### 3D product configurator
+```
+Create a 3D product configurator screen with Red/Blue/Green color buttons.
+Apply the selected color as a solid material on assets/models/product.glb.
+Add orbit camera and pinch-to-zoom.
+Use SceneView io.github.sceneview:sceneview:3.0.0.
+```
+
+### AR multi-object scene
+```
+Create an AR screen where a bottom sheet lets users choose between chair, table,
+and lamp GLBs in assets/models/. Tapping places the selected model. Each object
+is independently pinch-to-scale and drag-to-rotate. A "Clear all" button removes
+everything. Use SceneView io.github.sceneview:arsceneview:3.0.0.
+```
+
+---
+
+## Development
+
+```bash
+cd mcp
+npm install
+npm run prepare   # copies ../llms.txt and compiles TypeScript
+npm start         # run over stdio
+npx @modelcontextprotocol/inspector node dist/index.js  # test with inspector
+```
+
+## Publishing
+
+```bash
+cd mcp
+npm run prepare
+npm publish --access public
+```

package/dist/index.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+import { getSample, SAMPLE_IDS, SAMPLES } from "./samples.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let API_DOCS;
+try {
+    API_DOCS = readFileSync(resolve(__dirname, "../llms.txt"), "utf-8");
+}
+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.0" }, { capabilities: { resources: {}, tools: {} } });
+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.",
+            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 }],
+        };
+    }
+    throw new Error(`Unknown resource: ${request.params.uri}`);
+});
+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.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    scenario: {
+                        type: "string",
+                        enum: SAMPLE_IDS,
+                        description: `The scenario to fetch:\n${SAMPLE_IDS.map((id) => `- "${id}": ${SAMPLES[id].description}`).join("\n")}`,
+                    },
+                },
+                required: ["scenario"],
+            },
+        },
+        {
+            name: "get_setup",
+            description: "Returns the Gradle dependency and AndroidManifest snippet required to use SceneView in an Android project.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    type: {
+                        type: "string",
+                        enum: ["3d", "ar"],
+                        description: '"3d" for 3D-only scenes. "ar" for augmented reality (includes 3D).',
+                    },
+                },
+                required: ["type"],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    switch (request.params.name) {
+        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(", ")}` }],
+                    isError: true,
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `## ${sample.title}`,
+                            ``,
+                            `**Gradle dependency:**`,
+                            `\`\`\`kotlin`,
+                            `implementation("${sample.dependency}")`,
+                            `\`\`\``,
+                            ``,
+                            `**Kotlin (Jetpack Compose):**`,
+                            `\`\`\`kotlin`,
+                            sample.code,
+                            `\`\`\``,
+                            ``,
+                            `**Prompt that generates this:**`,
+                            `> ${sample.prompt}`,
+                        ].join("\n"),
+                    },
+                ],
+            };
+        }
+        case "get_setup": {
+            const type = request.params.arguments?.type;
+            if (type === "3d") {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                `## SceneView — 3D setup`,
+                                ``,
+                                `### build.gradle.kts`,
+                                `\`\`\`kotlin`,
+                                `dependencies {`,
+                                `    implementation("io.github.sceneview:sceneview:3.0.0")`,
+                                `}`,
+                                `\`\`\``,
+                                ``,
+                                `No manifest changes required for 3D-only scenes.`,
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            if (type === "ar") {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                `## SceneView — AR setup`,
+                                ``,
+                                `### build.gradle.kts`,
+                                `\`\`\`kotlin`,
+                                `dependencies {`,
+                                `    implementation("io.github.sceneview:arsceneview:3.0.0")`,
+                                `}`,
+                                `\`\`\``,
+                                ``,
+                                `### AndroidManifest.xml`,
+                                `\`\`\`xml`,
+                                `<uses-permission android:name="android.permission.CAMERA" />`,
+                                `<uses-feature android:name="android.hardware.camera.ar" android:required="true" />`,
+                                `<application>`,
+                                `    <meta-data android:name="com.google.ar.core" android:value="required" />`,
+                                `</application>`,
+                                `\`\`\``,
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [{ type: "text", text: `Unknown type "${type}". Use "3d" or "ar".` }],
+                isError: true,
+            };
+        }
+        default:
+            return {
+                content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],
+                isError: true,
+            };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/samples.js

@@ -0,0 +1,206 @@
+export const SAMPLES = {
+    "model-viewer": {
+        id: "model-viewer",
+        title: "3D Model Viewer",
+        description: "Full-screen 3D scene with a GLB model, HDR environment, and orbit 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
+fun ModelViewerScreen() {
+    val engine = rememberEngine()
+    val modelLoader = rememberModelLoader(engine)
+    val environmentLoader = rememberEnvironmentLoader(engine)
+
+    Scene(
+        modifier = Modifier.fillMaxSize(),
+        engine = engine,
+        modelLoader = modelLoader,
+        environment = rememberEnvironment(environmentLoader) {
+            environmentLoader.createHDREnvironment("environments/sky_2k.hdr")!!
+        },
+        mainLightNode = rememberMainLightNode(engine) { intensity = 100_000f },
+        cameraManipulator = rememberCameraManipulator()
+    ) {
+        rememberModelInstance(modelLoader, "models/my_model.glb")?.let { instance ->
+            ModelNode(
+                modelInstance = instance,
+                scaleToUnits = 1.0f,
+                autoAnimate = true,
+                isEditable = true
+            )
+        }
+    }
+}`,
+    },
+    "ar-tap-to-place": {
+        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.",
+        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
+fun TapToPlaceScreen() {
+    val engine = rememberEngine()
+    val modelLoader = rememberModelLoader(engine)
+    val modelInstance = rememberModelInstance(modelLoader, "models/chair.glb")
+    var placedAnchors by remember { mutableStateOf(listOf<Anchor>()) }
+
+    ARScene(
+        modifier = Modifier.fillMaxSize(),
+        engine = engine,
+        modelLoader = modelLoader,
+        planeRenderer = true,
+        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
+        },
+        onTouchEvent = { event, hitResult ->
+            if (event.action == MotionEvent.ACTION_UP && hitResult != null)
+                placedAnchors = placedAnchors + hitResult.createAnchor()
+            true
+        }
+    ) {
+        placedAnchors.forEach { anchor ->
+            AnchorNode(anchor = anchor) {
+                ModelNode(
+                    modelInstance = modelInstance ?: return@AnchorNode,
+                    scaleToUnits = 0.5f,
+                    isEditable = true
+                )
+            }
+        }
+    }
+}`,
+    },
+    "ar-placement-cursor": {
+        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.",
+        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
+fun ARCursorScreen() {
+    val engine = rememberEngine()
+    val modelLoader = rememberModelLoader(engine)
+    val modelInstance = rememberModelInstance(modelLoader, "models/object.glb")
+    var anchor by remember { mutableStateOf<Anchor?>(null) }
+    val view = LocalView.current
+
+    ARScene(
+        modifier = Modifier.fillMaxSize(),
+        engine = engine,
+        modelLoader = modelLoader,
+        planeRenderer = true,
+        sessionConfiguration = { _, config ->
+            config.instantPlacementMode = Config.InstantPlacementMode.LOCAL_Y_UP
+            config.lightEstimationMode = Config.LightEstimationMode.ENVIRONMENTAL_HDR
+        },
+        onTouchEvent = { event, hitResult ->
+            if (event.action == MotionEvent.ACTION_UP && hitResult != null)
+                anchor = hitResult.createAnchor()
+            true
+        }
+    ) {
+        if (anchor == null) {
+            HitResultNode(xPx = view.width / 2f, yPx = view.height / 2f) {
+                SphereNode(radius = 0.02f)
+            }
+        }
+        anchor?.let { a ->
+            AnchorNode(anchor = a) {
+                ModelNode(
+                    modelInstance = modelInstance ?: return@AnchorNode,
+                    scaleToUnits = 0.5f,
+                    isEditable = true
+                )
+            }
+        }
+    }
+}`,
+    },
+    "ar-augmented-image": {
+        id: "ar-augmented-image",
+        title: "AR Augmented Image",
+        description: "Detects a reference image in the camera feed and overlays a 3D model above it.",
+        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
+fun AugmentedImageScreen() {
+    val engine = rememberEngine()
+    val modelLoader = rememberModelLoader(engine)
+    val context = LocalContext.current
+    var trackedImages by remember { mutableStateOf(listOf<AugmentedImage>()) }
+
+    ARScene(
+        modifier = Modifier.fillMaxSize(),
+        engine = engine,
+        modelLoader = modelLoader,
+        sessionConfiguration = { session, config ->
+            config.augmentedImageDatabase = AugmentedImageDatabase(session).also { db ->
+                db.addImage(
+                    "target",
+                    BitmapFactory.decodeResource(context.resources, R.drawable.target_image),
+                    0.15f
+                )
+            }
+        },
+        onSessionUpdated = { _, frame ->
+            trackedImages = frame
+                .getUpdatedTrackables(AugmentedImage::class.java)
+                .filter { it.trackingState == TrackingState.TRACKING }
+        }
+    ) {
+        trackedImages.forEach { image ->
+            AugmentedImageNode(augmentedImage = image) {
+                rememberModelInstance(modelLoader, "models/overlay.glb")?.let { instance ->
+                    ModelNode(modelInstance = instance, scaleToUnits = image.extentX)
+                }
+            }
+        }
+    }
+}`,
+    },
+    "ar-face-filter": {
+        id: "ar-face-filter",
+        title: "AR Face Filter",
+        description: "Front-camera AR that detects faces and renders a 3D mesh material over them.",
+        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
+fun FaceFilterScreen() {
+    val engine = rememberEngine()
+    val modelLoader = rememberModelLoader(engine)
+    val materialLoader = rememberMaterialLoader(engine)
+    var trackedFaces by remember { mutableStateOf(listOf<AugmentedFace>()) }
+    val faceMaterial = remember(materialLoader) {
+        materialLoader.createInstance("materials/face_mask.filamat")
+    }
+
+    ARScene(
+        modifier = Modifier.fillMaxSize(),
+        engine = engine,
+        modelLoader = modelLoader,
+        sessionFeatures = setOf(Session.Feature.FRONT_CAMERA),
+        sessionConfiguration = { _, config ->
+            config.augmentedFaceMode = Config.AugmentedFaceMode.MESH3D
+        },
+        onSessionUpdated = { session, _ ->
+            trackedFaces = session
+                .getAllTrackables(AugmentedFace::class.java)
+                .filter { it.trackingState == TrackingState.TRACKING }
+        }
+    ) {
+        trackedFaces.forEach { face ->
+            AugmentedFaceNode(augmentedFace = face, meshMaterialInstance = faceMaterial)
+        }
+    }
+}`,
+    },
+};
+export const SAMPLE_IDS = Object.keys(SAMPLES);
+export function getSample(id) {
+    return SAMPLES[id];
+}

package/llms.txt

@@ -0,0 +1,388 @@
+# SceneView for Android
+
+SceneView is a Compose-first 3D and AR SDK for Android, built on Filament (Google's real-time rendering engine) and ARCore. It provides declarative composables for rendering interactive 3D scenes, loading glTF/GLB models, and building AR experiences.
+
+**Maven artifacts (version 3.0.0):**
+- 3D only: `io.github.sceneview:sceneview:3.0.0`
+- AR + 3D: `io.github.sceneview:arsceneview:3.0.0`
+
+**Min SDK:** 24 | **Target SDK:** 36 | **Kotlin:** 2.3.10 | **Compose BOM compatible**
+
+---
+
+## Setup
+
+### build.gradle (app module)
+```kotlin
+dependencies {
+    implementation("io.github.sceneview:sceneview:3.0.0")   // 3D only
+    implementation("io.github.sceneview:arsceneview:3.0.0") // AR (includes sceneview)
+}
+```
+
+### AndroidManifest.xml (AR apps)
+```xml
+<uses-permission android:name="android.permission.CAMERA" />
+<uses-feature android:name="android.hardware.camera.ar" android:required="true" />
+<application>
+    <meta-data android:name="com.google.ar.core" android:value="required" />
+</application>
+```
+
+---
+
+## Core Composables
+
+### Scene — 3D viewport
+```kotlin
+@Composable
+fun My3DScreen() {
+    val engine = rememberEngine()
+    val modelLoader = rememberModelLoader(engine)
+    val environmentLoader = rememberEnvironmentLoader(engine)
+
+    Scene(
+        modifier = Modifier.fillMaxSize(),
+        engine = engine,
+        modelLoader = modelLoader,
+        cameraManipulator = rememberCameraManipulator(),
+        environment = rememberEnvironment(environmentLoader) {
+            environmentLoader.createHDREnvironment("environments/sky_2k.hdr")!!
+        },
+        mainLightNode = rememberMainLightNode(engine) { intensity = 100_000f }
+    ) {
+        rememberModelInstance(modelLoader, "models/helmet.glb")?.let { instance ->
+            ModelNode(modelInstance = instance, scaleToUnits = 1.0f)
+        }
+    }
+}
+```
+
+### ARScene — AR viewport
+```kotlin
+@Composable
+fun MyARScreen() {
+    val engine = rememberEngine()
+    val modelLoader = rememberModelLoader(engine)
+
+    ARScene(
+        modifier = Modifier.fillMaxSize(),
+        engine = engine,
+        modelLoader = modelLoader,
+        planeRenderer = true,
+        sessionConfiguration = { session, config ->
+            config.depthMode = Config.DepthMode.AUTOMATIC
+            config.instantPlacementMode = Config.InstantPlacementMode.LOCAL_Y_UP
+            config.lightEstimationMode = Config.LightEstimationMode.ENVIRONMENTAL_HDR
+        },
+        onSessionUpdated = { session, frame -> /* per-frame logic */ }
+    ) {
+        // ARSceneScope DSL here
+    }
+}
+```
+
+---
+
+## SceneScope — Node DSL
+
+All content inside `Scene { }` or `ARScene { }` is a `SceneScope`.
+
+### ModelNode
+```kotlin
+Scene(...) {
+    val instance = rememberModelInstance(modelLoader, "models/my_model.glb")
+    if (instance != null) {
+        ModelNode(
+            modelInstance = instance,
+            scaleToUnits = 1.0f,
+            centerOrigin = Position(y = -1f),
+            position = Position(x = 0f, y = 0f, z = -2f),
+            rotation = Rotation(y = 45f),
+            isEditable = true,
+            autoAnimate = true
+        )
+    }
+}
+```
+
+### Primitive geometry nodes
+```kotlin
+Scene(...) {
+    CubeNode(size = Size(0.5f, 0.5f, 0.5f), materialInstance = redMaterial)
+    SphereNode(radius = 0.3f, materialInstance = blueMaterial)
+    CylinderNode(radius = 0.2f, height = 1.0f, materialInstance = greenMaterial)
+    PlaneNode(size = Size(5f, 5f), materialInstance = greyMaterial)
+}
+```
+
+### LightNode
+`apply` is `LightManager.Builder.() -> Unit` — must use the named parameter, NOT a trailing lambda.
+```kotlin
+Scene(...) {
+    LightNode(
+        type = LightManager.Type.SUN,
+        apply = {
+            color(1.0f, 1.0f, 1.0f)
+            intensity(100_000f)
+            castShadows(true)
+        }
+    )
+    LightNode(
+        type = LightManager.Type.POINT,
+        apply = { intensity(50_000f); falloff(5.0f) }
+    )
+}
+```
+
+### ImageNode
+```kotlin
+Scene(...) {
+    ImageNode(imageFileLocation = "images/logo.png", size = Size(1f, 1f))
+    ImageNode(imageResId = R.drawable.my_image)
+    ImageNode(bitmap = myBitmap, size = Size(2f, 1f))
+}
+```
+
+### ViewNode — Compose UI in 3D
+```kotlin
+val windowManager = rememberViewNodeManager()
+Scene(viewNodeWindowManager = windowManager) {
+    ViewNode(windowManager = windowManager) {
+        Card { Text("Hello 3D World!") }
+    }
+}
+```
+
+### Node hierarchy
+```kotlin
+Scene(...) {
+    Node(position = Position(y = 1f)) {
+        ModelNode(modelInstance = instance, position = Position(x = -1f))
+        CubeNode(size = Size(0.1f), position = Position(x = 1f))
+    }
+}
+```
+
+---
+
+## ARSceneScope — AR Node DSL
+
+### HitResultNode — surface cursor
+```kotlin
+val view = LocalView.current
+ARScene(...) {
+    HitResultNode(xPx = view.width / 2f, yPx = view.height / 2f) {
+        SphereNode(radius = 0.02f)  // reticle
+    }
+}
+```
+
+### AnchorNode — pin to real world
+```kotlin
+ARScene(
+    onTouchEvent = { event, hitResult ->
+        if (event.action == MotionEvent.ACTION_UP && hitResult != null)
+            anchor = hitResult.createAnchor()
+        true
+    }
+) {
+    anchor?.let { a ->
+        AnchorNode(anchor = a) {
+            ModelNode(modelInstance = instance!!, scaleToUnits = 0.5f, isEditable = true)
+        }
+    }
+}
+```
+
+### AugmentedImageNode
+```kotlin
+ARScene(
+    sessionConfiguration = { session, config ->
+        config.augmentedImageDatabase = AugmentedImageDatabase(session).also { db ->
+            db.addImage("target", bitmap, 0.15f)
+        }
+    },
+    onSessionUpdated = { _, frame ->
+        trackedImages = frame.getUpdatedTrackables(AugmentedImage::class.java)
+            .filter { it.trackingState == TrackingState.TRACKING }
+    }
+) {
+    trackedImages.forEach { image ->
+        AugmentedImageNode(augmentedImage = image) {
+            ModelNode(modelInstance = instance!!, scaleToUnits = image.extentX)
+        }
+    }
+}
+```
+
+### AugmentedFaceNode
+```kotlin
+ARScene(
+    sessionFeatures = setOf(Session.Feature.FRONT_CAMERA),
+    sessionConfiguration = { _, config ->
+        config.augmentedFaceMode = Config.AugmentedFaceMode.MESH3D
+    },
+    onSessionUpdated = { session, _ ->
+        trackedFaces = session.getAllTrackables(AugmentedFace::class.java)
+            .filter { it.trackingState == TrackingState.TRACKING }
+    }
+) {
+    trackedFaces.forEach { face ->
+        AugmentedFaceNode(augmentedFace = face, meshMaterialInstance = faceMaterial)
+    }
+}
+```
+
+### CloudAnchorNode
+```kotlin
+ARScene(...) {
+    CloudAnchorNode(
+        anchor = localAnchor,
+        cloudAnchorId = savedCloudId,
+        onHosted = { cloudId, state ->
+            if (state == CloudAnchorState.SUCCESS) save(cloudId!!)
+        }
+    ) {
+        ModelNode(modelInstance = instance!!)
+    }
+}
+```
+
+---
+
+## Node Properties & Interaction
+
+```kotlin
+node.position = Position(x = 1f, y = 0f, z = -2f)  // meters
+node.rotation = Rotation(x = 0f, y = 45f, z = 0f)   // degrees
+node.scale    = Scale(x = 1f, y = 1f, z = 1f)
+node.isVisible   = true
+node.isEditable  = true   // pinch-scale, drag-move, two-finger-rotate
+node.isTouchable = true
+
+node.onSingleTapConfirmed = { event -> true }
+node.onFrame = { frameTimeNanos -> }
+
+node.transform(position = Position(x = 2f), smooth = true, smoothSpeed = 5f)
+node.lookAt(targetNode)
+
+node.animateRotations(Rotation(0f), Rotation(y = 360f)).also {
+    it.duration = 2000
+    it.repeatCount = ValueAnimator.INFINITE
+}.start()
+
+val hit: Node? = node.overlapTest()
+```
+
+---
+
+## Resource Loading
+
+```kotlin
+// Composable (preferred) — null while loading, recomposes when ready
+val instance: ModelInstance? = rememberModelInstance(modelLoader, "models/file.glb")
+
+// Imperative — call from LaunchedEffect or ViewModel
+val instance = modelLoader.loadModelInstance("models/file.glb")
+modelLoader.loadModelInstanceAsync("models/file.glb") { instance -> }
+
+// HDR environment
+val env = environmentLoader.createHDREnvironment("environments/sky_2k.hdr")
+val env = environmentLoader.createKtxEnvironment("environments/studio.ktx")
+```
+
+---
+
+## Camera
+
+```kotlin
+// Orbit / pan / zoom
+Scene(cameraManipulator = rememberCameraManipulator(
+    orbitHomePosition = Position(x = 0f, y = 2f, z = 4f),
+    targetPosition = Position(x = 0f, y = 0f, z = 0f)
+))
+
+// Custom camera
+Scene(cameraNode = rememberCameraNode(engine) {
+    position = Position(x = 0f, y = 2f, z = 5f)
+    lookAt(Position(0f, 0f, 0f))
+})
+
+// Main light shortcut (apply block is LightNode.() -> Unit — set properties directly)
+Scene(mainLightNode = rememberMainLightNode(engine) { intensity = 100_000f })
+```
+
+---
+
+## Gestures
+
+```kotlin
+Scene(
+    onGestureListener = rememberOnGestureListener(
+        onSingleTapConfirmed = { event, node -> },
+        onDoubleTap = { event, node -> node?.let { it.scale = Scale(2f) } },
+        onLongPress = { event, node -> }
+    ),
+    onTouchEvent = { event, hitResult -> false }
+)
+```
+
+---
+
+## Math Types
+
+```kotlin
+import io.github.sceneview.math.Position   // Float3, meters
+import io.github.sceneview.math.Rotation   // Float3, degrees
+import io.github.sceneview.math.Scale      // Float3
+import io.github.sceneview.math.Direction  // Float3, unit vector
+import io.github.sceneview.math.Size       // Float2
+
+Position(x = 0f, y = 1f, z = -2f)
+Rotation(y = 90f)
+Scale(1.5f)          // uniform
+Scale(x = 2f, y = 1f, z = 2f)
+```
+
+---
+
+## Surface Types
+
+```kotlin
+Scene(surfaceType = SurfaceType.Surface)          // SurfaceView, best perf (default)
+Scene(surfaceType = SurfaceType.TextureSurface, isOpaque = false)  // TextureView, alpha
+```
+
+---
+
+## Threading Rules
+
+- Filament JNI calls must run on the **main thread**.
+- `rememberModelInstance` is safe — reads bytes on IO, creates Filament objects on Main.
+- Never call `modelLoader.createModel*` or `materialLoader.*` from background coroutines.
+- Use `modelLoader.loadModelInstanceAsync` for imperative code.
+
+---
+
+## Samples
+
+| Sample | Demonstrates |
+|--------|-------------|
+| `model-viewer` | Orbit camera, HDR env, glTF animation |
+| `ar-model-viewer` | Tap-to-place, pinch/drag/rotate |
+| `gltf-camera` | Cameras from glTF file |
+| `camera-manipulator` | Orbit/pan/zoom |
+| `ar-augmented-image` | Image detection, overlay, video |
+| `ar-cloud-anchor` | Cross-device persistent anchors |
+| `ar-point-cloud` | ARCore feature point cloud |
+| `autopilot-demo` | Autonomous AR demo |
+
+---
+
+## AI Integration
+
+MCP server: `@sceneview/mcp`. Add to `.claude/mcp.json`:
+```json
+{ "mcpServers": { "sceneview": { "command": "npx", "args": ["-y", "@sceneview/mcp"] } } }
+```

package/package.json

@@ -0,0 +1,29 @@
+{
+  "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"],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "sceneview-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "llms.txt"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "cp ../llms.txt ./llms.txt && tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.8.0"
+  }
+}