sceneview-mcp 4.0.12 → 4.0.13

package/README.md

@@ -111,7 +111,7 @@ Every developer tool is **free**: setup guides for every platform, code samples,
 
 | Tool | What it does |
 |---|---|
-| `get_node_reference` | Full API reference for any of 35+ node types — exact signatures, defaults, examples |
+| `get_node_reference` | Full API reference for any of 42+ node types — exact signatures, defaults, examples |
 | `list_platforms` | Supported platforms with their status, renderer, and framework |
 | `get_platform_roadmap` | Multi-platform status and timeline |
 
@@ -125,6 +125,8 @@ Every developer tool is **free**: setup guides for every platform, code samples,
 |---|---|
 | `search_models` | Searches Sketchfab for free 3D models (BYOK — set `SKETCHFAB_API_KEY`) |
 | `analyze_project` | Scans a local SceneView project on disk — detects platform, extracts version, flags outdated deps and known anti-patterns |
+| `search_android_docs` | Searches Google's stock Android docs knowledge base (needs the `android` CLI on PATH) |
+| `fetch_android_doc` | Fetches a full Android docs entry by its `kb://...` URI (needs the `android` CLI on PATH) |
 
 ### 2 resources
 
@@ -206,7 +208,7 @@ The assistant calls `validate_code` with the generated snippet and checks it aga
 - Always use the current SceneView 4.0.x API surface
 - Generate correct **Compose-native** 3D/AR code for Android
 - Generate correct **SwiftUI-native** code for iOS/macOS/visionOS
-- Know about all 35+ node types and their exact parameters
+- Know about all 42+ node types and their exact parameters
 - Validate code against 15+ rules before presenting it
 - Provide working, tested sample code for 33 scenarios
 

package/dist/android-docs.js

@@ -0,0 +1,206 @@
+/**
+ * android-docs — `search_android_docs` / `fetch_android_doc` MCP tools.
+ *
+ * Google's `android` CLI (https://developer.android.com/tools/agents/android-cli)
+ * ships a `docs` subcommand backed by a knowledge base of ~4 800 stock Android
+ * documentation entries: Jetpack Compose, Camera2, ARCore SDK, Kotlin APIs,
+ * platform guides, and more. Wrapping it as MCP tools lets any MCP-aware
+ * assistant cross-reference stock Android docs with SceneView code without
+ * leaving the SceneView chat (issue #1083).
+ *
+ *   - `search_android_docs(query)`  → `android docs search <query>`
+ *   - `fetch_android_doc(uri)`      → `android docs fetch kb://<path>`
+ *
+ * Runtime dependency: the `android` CLI must be on the consumer's PATH. It is
+ * NOT a hard dependency of `sceneview-mcp` — most MCP hosts won't have it
+ * installed. Every code path here detects the binary up front and returns a
+ * structured, friendly error (never throws / crashes the MCP server) when it
+ * is absent.
+ *
+ * Hygiene ported from `.claude/scripts/lib/android-cli.sh`:
+ *   - `--no-metrics` is passed on every invocation (keeps telemetry off and
+ *     output clean).
+ *   - The CLI prints a one-time terms-of-service blurb to stderr on its first
+ *     invocation; we run a throwaway `--version` once per process to consume
+ *     it so the real `docs` call returns clean stdout.
+ */
+import { execFile } from "node:child_process";
+// ─── Configuration ──────────────────────────────────────────────────────────
+/** Global flags applied to every `android` invocation (telemetry off). */
+const ANDROID_CLI_GLOBAL_FLAGS = ["--no-metrics"];
+/** Hard cap on a single `android docs` call so a hung CLI can't wedge MCP. */
+const ANDROID_CLI_TIMEOUT_MS = 20_000;
+/** Cap the captured stdout/stderr so a pathological response can't blow memory. */
+const ANDROID_CLI_MAX_BUFFER = 4 * 1024 * 1024; // 4 MB
+const INSTALL_URL = "https://developer.android.com/tools/agents/android-cli";
+// ─── CLI detection ───────────────────────────────────────────────────────────
+/**
+ * Whether the first-run ToS blurb has already been consumed for this process.
+ * The `android` CLI prints its terms-of-service notice to stderr exactly once
+ * per host; running any command absorbs it. We do it lazily, once.
+ */
+let tosConsumed = false;
+/** Cached binary-presence result for the lifetime of the MCP process. */
+let cliPresenceCache;
+/**
+ * Promisified `execFile` returning stdout + stderr, never rejecting.
+ * `error` is non-null when the process exits non-zero, is killed, or cannot
+ * be spawned (`ENOENT` when the binary is absent).
+ */
+function run(file, args) {
+    return new Promise((resolve) => {
+        execFile(file, args, { timeout: ANDROID_CLI_TIMEOUT_MS, maxBuffer: ANDROID_CLI_MAX_BUFFER, encoding: "utf8" }, (error, stdout, stderr) => {
+            resolve({
+                error: error ?? null,
+                stdout: stdout ?? "",
+                stderr: stderr ?? "",
+            });
+        });
+    });
+}
+/**
+ * Detect the `android` CLI on PATH. Result is cached for the process lifetime
+ * and also consumes the one-time ToS blurb on first success.
+ *
+ * Exported for tests; production callers go through `runAndroidDocs`.
+ */
+export async function isAndroidCliAvailable() {
+    if (cliPresenceCache !== undefined)
+        return cliPresenceCache;
+    const { error } = await run("android", [...ANDROID_CLI_GLOBAL_FLAGS, "--version"]);
+    // ENOENT (binary not found) ⇒ unavailable. Any other exit still means the
+    // binary spawned, so it IS present — and that --version run has now consumed
+    // the first-run ToS notice.
+    const spawnFailed = error?.code === "ENOENT";
+    cliPresenceCache = !spawnFailed;
+    if (cliPresenceCache)
+        tosConsumed = true;
+    return cliPresenceCache;
+}
+/** Test-only: reset the process-scoped CLI detection / ToS caches. */
+export function __resetAndroidCliCache() {
+    cliPresenceCache = undefined;
+    tosConsumed = false;
+}
+function cliMissingError() {
+    return {
+        ok: false,
+        code: "cli_missing",
+        message: [
+            "This tool needs Google's `android` CLI, which is not installed on this MCP host.",
+            "",
+            "`android docs` is an optional runtime dependency — `sceneview-mcp` works fine without it,",
+            "but `search_android_docs` / `fetch_android_doc` cannot run until the CLI is on PATH.",
+            "",
+            `Install it from ${INSTALL_URL} (or run \`bash .claude/scripts/android-env-check.sh --fix\``,
+            "from a SceneView checkout), then retry.",
+        ].join("\n"),
+    };
+}
+// ─── Core runner ─────────────────────────────────────────────────────────────
+/**
+ * Run an `android docs <subcommand> <arg>` invocation and return its stdout
+ * as a structured result. Never throws.
+ */
+async function runAndroidDocs(subcommand, arg) {
+    if (!(await isAndroidCliAvailable())) {
+        return cliMissingError();
+    }
+    // Belt-and-braces: ensure the first-run ToS notice is consumed. Normally
+    // `isAndroidCliAvailable()` already did this via its `--version` probe, but
+    // a caller could have populated `cliPresenceCache` some other way.
+    if (!tosConsumed) {
+        await run("android", [...ANDROID_CLI_GLOBAL_FLAGS, "--version"]);
+        tosConsumed = true;
+    }
+    const { error, stdout, stderr } = await run("android", [
+        ...ANDROID_CLI_GLOBAL_FLAGS,
+        "docs",
+        subcommand,
+        arg,
+    ]);
+    if (error) {
+        // `execFile` sets `killed` + `signal` on a timeout kill.
+        const killedByTimeout = error.killed === true ||
+            error.signal === "SIGTERM";
+        if (killedByTimeout) {
+            return {
+                ok: false,
+                code: "timeout",
+                message: `\`android docs ${subcommand}\` did not finish within ${ANDROID_CLI_TIMEOUT_MS / 1000}s.`,
+            };
+        }
+        const detail = (stderr || stdout || error.message).trim();
+        return {
+            ok: false,
+            code: "cli_error",
+            message: `\`android docs ${subcommand}\` failed: ${detail}`,
+        };
+    }
+    return { ok: true, output: stdout.trim() };
+}
+// ─── Public API: search ──────────────────────────────────────────────────────
+/**
+ * Search the stock Android documentation knowledge base.
+ *
+ * @param query Free-text query, e.g. `"LazyColumn paging"`.
+ */
+export async function searchAndroidDocs(query) {
+    if (typeof query !== "string" || query.trim().length === 0) {
+        return {
+            ok: false,
+            code: "invalid_input",
+            message: "Missing required parameter: `query` must be a non-empty string.",
+        };
+    }
+    return runAndroidDocs("search", query.trim());
+}
+// ─── Public API: fetch ───────────────────────────────────────────────────────
+/**
+ * Fetch a single Android documentation entry by its knowledge-base URI.
+ *
+ * @param uri A `kb://...` URI as returned by `search_android_docs`. A bare
+ *            path (no scheme) is tolerated and normalised to `kb://`.
+ */
+export async function fetchAndroidDoc(uri) {
+    if (typeof uri !== "string" || uri.trim().length === 0) {
+        return {
+            ok: false,
+            code: "invalid_input",
+            message: "Missing required parameter: `uri` must be a non-empty `kb://...` string.",
+        };
+    }
+    let normalised = uri.trim();
+    if (!normalised.startsWith("kb://")) {
+        // Tolerate a bare path or a leading slash — normalise to a kb:// URI so an
+        // assistant that drops the scheme still gets a result.
+        normalised = `kb://${normalised.replace(/^\/+/, "")}`;
+    }
+    return runAndroidDocs("fetch", normalised);
+}
+// ─── Formatting ──────────────────────────────────────────────────────────────
+/** Render a search result as the markdown text block the MCP dispatcher returns. */
+export function formatAndroidDocsSearch(query, result) {
+    if (!result.ok)
+        return result.message;
+    if (result.output.length === 0) {
+        return `No Android documentation entries found for "${query}". Try a broader query.`;
+    }
+    return [
+        `## Android docs — search results for "${query}"`,
+        "",
+        result.output,
+        "",
+        "---",
+        "Use `fetch_android_doc` with a `kb://...` URI above to read a full entry.",
+    ].join("\n");
+}
+/** Render a fetch result as the markdown text block the MCP dispatcher returns. */
+export function formatAndroidDocsFetch(uri, result) {
+    if (!result.ok)
+        return result.message;
+    if (result.output.length === 0) {
+        return `No Android documentation entry found at \`${uri}\`.`;
+    }
+    return [`## Android docs — \`${uri}\``, "", result.output].join("\n");
+}

package/dist/examples.js

@@ -0,0 +1,136 @@
+/**
+ * Inline example resources exposed via MCP `examples://` URIs.
+ *
+ * Two resources, intentionally inline (no fs reads / no fetches) so the
+ * `sceneview-mcp` package stays a pure code dependency:
+ *
+ *  - `examples://demo-with-settings` — DemoScaffold v2 pattern (PR #1169 under
+ *    issue #1154). Full-screen 3D / AR scene + ModalBottomSheet controls
+ *    + horizontal FilterChip picker row.
+ *
+ *  - `examples://sketchfab-streaming` — `SketchfabAssetResolver` pattern
+ *    (Stage 2 of umbrella issue #1152). Stream CC-BY models from Sketchfab
+ *    with per-slug bundled fallback + LRU cache + bounds sanity check.
+ *
+ * These strings deliberately stay small (≤ 4 KB each) so the resource list
+ * doesn't bloat the client's context window. The full recipes live at
+ * `docs/docs/recipes/sketchfab-streaming.md` and
+ * `docs/docs/recipes/demo-settings-sheet.md`.
+ */
+export const DEMO_WITH_SETTINGS_EXAMPLE = `# Example — DemoScaffold v2 (full-screen scene + ModalBottomSheet controls)
+
+\`DemoScaffold\` v2 is the shared scaffold every SceneView sample-app demo uses. It renders the 3D / AR scene **full-screen** under the top bar, with a \`Tune\` FAB pinned bottom-right that opens a Material 3 ModalBottomSheet containing the controls.
+
+\`\`\`kotlin
+@Composable
+fun MyDemo(onBack: () -> Unit) {
+    var iblIntensity by remember { mutableFloatStateOf(5_000f) }
+    var spinScene by remember { mutableStateOf(true) }
+    val engine = rememberEngine()
+    val modelLoader = rememberModelLoader(engine)
+
+    DemoScaffold(
+        title = "My Demo",
+        onBack = onBack,
+        controls = {
+            // Same Column scope you'd use in any settings sheet.
+            Text(
+                "IBL intensity: \${iblIntensity.toInt()} lux",
+                style = MaterialTheme.typography.labelLarge,
+            )
+            Slider(
+                value = iblIntensity,
+                onValueChange = { iblIntensity = it },
+                valueRange = 0f..10_000f,
+            )
+            Spacer(modifier = Modifier.height(8.dp))
+            Row(
+                modifier = Modifier.fillMaxWidth(),
+                horizontalArrangement = Arrangement.SpaceBetween,
+                verticalAlignment = Alignment.CenterVertically,
+            ) {
+                Text("Spin scene", style = MaterialTheme.typography.bodyMedium)
+                Switch(checked = spinScene, onCheckedChange = { spinScene = it })
+            }
+        },
+    ) {
+        // BoxScope — full-screen scene.
+        SceneView(
+            modifier = Modifier.fillMaxSize(),
+            engine = engine,
+            modelLoader = modelLoader,
+        ) {
+            // … nodes go here.
+        }
+    }
+}
+\`\`\`
+
+**Gestures.** Tap FAB → opens the sheet. Tap peek chip ("Settings", above the FAB) → opens the sheet (discoverability — added under issue #951). Long-press peek chip → toggles \`DemoSettings.qaMode\` for deterministic screenshot captures. Drag handle / outside tap / back → dismiss. AR sessions keep tracking underneath.
+
+**Picker pattern.** Combine with the FilterChip horizontal row for bundled-vs-streamed asset selection — see \`examples://sketchfab-streaming\`.
+
+**Full doc:** \`docs/docs/recipes/demo-settings-sheet.md\` (PR #1169, issue #1154).
+`;
+export const SKETCHFAB_STREAMING_EXAMPLE = `# Example — Stream Sketchfab CC-BY models into a SceneView demo
+
+The sample app (\`samples/android-demo\`) streams CC-BY licensed glTF models from Sketchfab on demand instead of bundling 30 MB of GLBs in the APK. The same pattern works in any SceneView consumer.
+
+\`\`\`kotlin
+@Composable
+fun MyStreamedDemo(onBack: () -> Unit) {
+    val context = LocalContext.current
+    val resolver = remember { SketchfabAssetResolver.getInstance(context) }
+    val engine = rememberEngine()
+    val modelLoader = rememberModelLoader(engine)
+
+    // Warm the cache so the first frame doesn't pop in. Concurrent calls for
+    // the same slug deduplicate at the service layer.
+    LaunchedEffect(Unit) {
+        runCatching { resolver.prefetchAll("animation") }
+    }
+
+    // Pick a slug from the curated registry — categories: solar, gallery,
+    // animation, park, ar_placement, physics, materials.
+    val slug = remember { SampleAssets.byCategory["animation"].orEmpty().first() }
+
+    // Resolve to a local file (null while downloading / staging the fallback).
+    val file: File? by produceState<File?>(initialValue = null, key1 = slug.uid) {
+        value = runCatching { resolver.resolve(slug) }.getOrNull()
+    }
+
+    val instance = file?.let {
+        rememberModelInstance(modelLoader, "file://\${it.absolutePath}")
+    }
+
+    DemoScaffold(title = slug.displayName, onBack = onBack) {
+        SceneView(
+            modifier = Modifier.fillMaxSize(),
+            engine = engine,
+            modelLoader = modelLoader,
+        ) {
+            instance?.let {
+                ModelNode(
+                    modelInstance = it,
+                    scaleToUnits = slug.scaleToUnits,
+                    autoAnimate = slug.hasBakedAnimation,
+                )
+            }
+        }
+    }
+}
+\`\`\`
+
+**Hard rules.**
+
+- **CC-BY 4.0 only.** \`SketchfabSlug\`'s constructor rejects non-CC-BY models so the registry can't silently regress.
+- **No Sketchfab WebView / external link.** All loading is in-process; Sketchfab is an invisible CDN, not a UX surface.
+- **Never ship a build that needs the network to render something.** The resolver returns a bundled fallback when \`SketchfabConfig.apiKey == null\` or the download fails.
+- **Attribute the author.** Every streamed model surfaced in the UI must show \`slug.author\` — CC-BY 4.0 attribution requirement.
+
+**LRU cache.** \`Context.cacheDir/sketchfab/\` (250 MB samples-side cap, evicted oldest-first by \`lastModified\`).
+
+**Bounds sanity check.** The resolver verifies the \`glTF\` magic header + size ≥ 12 B before returning a streamed file. Truncated downloads / wrong-format payloads fall back to the bundled asset.
+
+**Full doc:** \`docs/docs/recipes/sketchfab-streaming.md\` (umbrella issue #1152, Stage 1 PR #1168).
+`;