sceneview-mcp 4.0.12 → 4.0.14

package/README.md

@@ -4,7 +4,7 @@
 
 [![npm version](https://img.shields.io/npm/v/sceneview-mcp?color=6c35aa)](https://www.npmjs.com/package/sceneview-mcp)
 [![npm downloads](https://img.shields.io/npm/dm/sceneview-mcp?color=blue)](https://www.npmjs.com/package/sceneview-mcp)
-[![Tests](https://img.shields.io/badge/tests-2918%20passing-brightgreen)](#quality)
+[![Tests](https://img.shields.io/badge/tests-1898%20passing-brightgreen)](#quality)
 [![MCP](https://img.shields.io/badge/MCP-v1.12-blue)](https://modelcontextprotocol.io/)
 [![Registry](https://img.shields.io/badge/MCP%20Registry-listed-blueviolet)](https://registry.modelcontextprotocol.io)
 [![License](https://img.shields.io/badge/License-MIT-green)](./LICENSE)
@@ -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 44+ node types — exact signatures, defaults, examples |
 | `list_platforms` | Supported platforms with their status, renderer, and framework |
 | `get_platform_roadmap` | Multi-platform status and timeline |
 
@@ -124,7 +124,10 @@ Every developer tool is **free**: setup guides for every platform, code samples,
 | Tool | What it does |
 |---|---|
 | `search_models` | Searches Sketchfab for free 3D models (BYOK — set `SKETCHFAB_API_KEY`) |
+| `generate_3d_model` | Generates a brand-new GLB from a text prompt or image via Tripo AI (BYOK — set `TRIPO_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
 
@@ -159,6 +162,38 @@ Generated SceneView code is only useful if it points at an asset that actually e
 
 Call it like `search_models({ query: "red sports car", category: "cars-vehicles", maxResults: 6 })`. If the key is missing, the tool returns a clear message explaining how to get one instead of failing silently.
 
+## `generate_3d_model` — create brand-new 3D assets from the AI
+
+When no existing model fits, `generate_3d_model` closes the other half of the asset loop: it generates a fresh GLB from a **text prompt** (text→3D) or a **source image** (image→3D) via the [Tripo AI](https://www.tripo3d.ai) API, then returns a direct GLB download URL plus license/attribution metadata — ready for `rememberModelInstance(modelLoader, ...)` and AR placement.
+
+Two quality tiers:
+
+| `quality` | Tripo model | Topology | Latency | Approx. cost (July 2026) |
+|---|---|---|---|---|
+| `"fast"` (default) | P1 (`P1-20260311`) | low-poly, AR-ready | ~25–30 s | ~$0.10–0.25 of your credits |
+| `"hd"` | H3.1 (`v3.1-20260211`) | quad mesh, detailed geometry + textures | up to ~100 s | ~$0.41 of your credits |
+
+**Bring your own key (BYOK).** Exactly like `search_models`: SceneView never proxies the request or holds your key — generations are billed to **your** Tripo account. To set it up:
+
+1. Create an API key at [platform.tripo3d.ai/api-keys](https://platform.tripo3d.ai/api-keys) (new accounts get free trial credits)
+2. Set `TRIPO_API_KEY` in your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "sceneview": {
+      "command": "npx",
+      "args": ["-y", "sceneview-mcp"],
+      "env": { "TRIPO_API_KEY": "YOUR_KEY_HERE" }
+    }
+  }
+}
+```
+
+Call it like `generate_3d_model({ prompt: "a low-poly cactus in a striped pot" })` or `generate_3d_model({ imageUrl: "https://example.com/chair.jpg", quality: "hd" })`. Provide exactly one of `prompt` / `imageUrl`.
+
+**⚠️ The GLB download URL expires ~5 minutes after generation** — download the file immediately and self-host it (e.g. copy it into your app's `assets/models/`). The tool result repeats this warning. Missing key, task failures, rate limits, and poll timeouts (2 min fast / 4 min hd cap) all return clear, actionable messages instead of hanging or crashing.
+
 ## `analyze_project` — local project scan
 
 Because the MCP server runs on the user's machine, `analyze_project` can read their project files directly. Given a `path` (default: `process.cwd()`), it:
@@ -206,7 +241,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 44+ node types and their exact parameters
 - Validate code against 15+ rules before presenting it
 - Provide working, tested sample code for 33 scenarios
 
@@ -214,7 +249,7 @@ The assistant calls `validate_code` with the generated snippet and checks it aga
 
 ## Quality
 
-The MCP server is tested with **2,918 unit tests** across 132 test suites covering:
+The MCP server is tested with **1,898 unit tests** across 81 test suites covering:
 
 - Every tool response (correct output, error handling, edge cases)
 - All 33 code samples (compilable structure, correct imports, no deprecated APIs)
@@ -223,11 +258,11 @@ The MCP server is tested with **2,918 unit tests** across 132 test suites coveri
 - Resource responses (API reference, GitHub issues integration)
 
 ```
- Test Files  132 passed (132)
-      Tests  2918 passed (2918)
+ Test Files  81 passed (81)
+      Tests  1898 passed (1898)
 ```
 
-All tools work **fully offline** except `sceneview://known-issues` (GitHub API, cached 10 min) and `search_models` (Sketchfab, BYOK).
+All tools work **fully offline** except `sceneview://known-issues` (GitHub API, cached 10 min), `search_models` (Sketchfab, BYOK), and `generate_3d_model` (Tripo AI, BYOK).
 
 ---
 
@@ -251,7 +286,7 @@ Install Node.js from [nodejs.org](https://nodejs.org/) (LTS recommended). npm an
 
 ### Firewall or proxy issues
 
-The only network calls are to the GitHub API (for known issues) and Sketchfab (when `SKETCHFAB_API_KEY` is set). Everything else works offline.
+The only network calls are to the GitHub API (for known issues), Sketchfab (when `SKETCHFAB_API_KEY` is set), and Tripo AI (when `TRIPO_API_KEY` is set and `generate_3d_model` is called). Everything else works offline.
 
 ```json
 {
@@ -302,7 +337,7 @@ Enabled by default on the free tier (MCP client name/version and tool names —
 cd mcp
 npm install
 npm run prepare  # Copy llms.txt + build TypeScript
-npm test         # 2918 tests
+npm test         # 1898 tests
 npm run dev      # Start with tsx (hot reload)
 ```
 
@@ -323,6 +358,7 @@ mcp/
     artifact.ts          # HTML artifact generator (model-viewer, charts, product 360)
     issues.ts            # GitHub issues fetcher (cached)
     search-models.ts     # Sketchfab BYOK search
+    generate-model.ts    # Tripo BYOK text/image -> GLB generation
     analyze-project.ts   # Local project scanner
     proxy.ts             # Pro-tool proxy to hosted gateway
   llms.txt               # Bundled API reference (copied from repo root)
@@ -333,7 +369,7 @@ mcp/
 1. Fork the repository
 2. Create a feature branch
 3. Add tests for new tools or rules
-4. Run `npm test` — all 2918+ tests must pass
+4. Run `npm test` — all 1898+ tests must pass
 5. Submit a pull request
 
 See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full guide.

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).
+`;