sceneview-mcp 4.0.12 → 4.0.13

package/dist/generated/version.js

@@ -4,5 +4,5 @@
 // build time so the MCP server, telemetry, and the install-snippet
 // generators all report the actually-published versions instead of
 // stale hardcoded constants. See #941.
-export const PACKAGE_VERSION = "4.0.12";
-export const LATEST_SCENEVIEW_RELEASE = "4.1.0";
+export const PACKAGE_VERSION = "4.0.13";
+export const LATEST_SCENEVIEW_RELEASE = "4.18.0";

package/dist/guides.js

@@ -33,7 +33,7 @@ KMP shares **logic**, not **rendering**. Each platform uses its native renderer.
 - **3D rendering** via Google Filament: PBR materials, HDR environments, glTF/GLB models, post-processing.
 - **AR** via ARCore: plane detection, hit testing, anchors, cloud anchors, augmented images, depth, light estimation, point cloud.
 - **Compose-native DSL**: all nodes are \`@Composable\` functions inside \`SceneView { }\` or \`ARSceneView { }\`.
-- **26+ node types**: ModelNode, LightNode, AnchorNode, CameraNode, TextNode, PathNode, ViewNode, PlaneNode, SphereNode, CylinderNode, CubeNode, DynamicSkyNode, FogNode, ReflectionProbeNode, PhysicsNode, BillboardNode, LineNode, and more.
+- **42+ node types**: ModelNode, LightNode, AnchorNode, CameraNode, TextNode, PathNode, ViewNode, PlaneNode, SphereNode, CylinderNode, CubeNode, DynamicSkyNode, FogNode, ReflectionProbeNode, PhysicsNode, BillboardNode, LineNode, and more.
 
 ## Apple — Alpha (SceneViewSwift)
 

package/dist/index.js

@@ -17,6 +17,7 @@ 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 { fetchKnownIssues } from "./issues.js";
+import { DEMO_WITH_SETTINGS_EXAMPLE, SKETCHFAB_STREAMING_EXAMPLE, } from "./examples.js";
 import { recordClientInit, recordToolCall } from "./telemetry.js";
 import { isProTool, getToolTier } from "./tiers.js";
 import { dispatchProxyToolCall, isProxyConfigured, DEFAULT_PRICING_URL, } from "./proxy.js";
@@ -66,6 +67,18 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => ({
             description: "Live list of open issues from the SceneView GitHub repository. Check this before reporting a bug or when something isn't working — there may already be a known workaround.",
             mimeType: "text/markdown",
         },
+        {
+            uri: "examples://demo-with-settings",
+            name: "Example — DemoScaffold v2 (full-screen scene + ModalBottomSheet)",
+            description: "Pattern for full-screen 3D / AR scene + Material 3 ModalBottomSheet controls. The DemoScaffold v2 contract used by every demo in samples/android-demo (issue #1154, PR #1169). Read this before adding a new demo with settings.",
+            mimeType: "text/markdown",
+        },
+        {
+            uri: "examples://sketchfab-streaming",
+            name: "Example — Stream Sketchfab CC-BY models into a SceneView demo",
+            description: "Pattern for streaming CC-BY licensed glTF models from Sketchfab on demand instead of bundling 30 MB of GLBs in the APK. Uses SketchfabAssetResolver + SampleAssets registry + per-slug bundled fallback (Stage 2 of umbrella issue #1152). Read this before adding a streamed demo.",
+            mimeType: "text/markdown",
+        },
     ],
 }));
 server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
@@ -80,6 +93,22 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
                 contents: [{ uri: "sceneview://known-issues", mimeType: "text/markdown", text: issues }],
             };
         }
+        case "examples://demo-with-settings":
+            return {
+                contents: [{
+                        uri: "examples://demo-with-settings",
+                        mimeType: "text/markdown",
+                        text: DEMO_WITH_SETTINGS_EXAMPLE,
+                    }],
+            };
+        case "examples://sketchfab-streaming":
+            return {
+                contents: [{
+                        uri: "examples://sketchfab-streaming",
+                        mimeType: "text/markdown",
+                        text: SKETCHFAB_STREAMING_EXAMPLE,
+                    }],
+            };
         default:
             throw new Error(`Unknown resource: ${request.params.uri}`);
     }

package/dist/issues.js

@@ -151,10 +151,12 @@ export async function fetchKnownIssues() {
                 fetchError = "GitHub API returned unexpected response format (expected array).";
             }
             else {
-                issues = json.filter((item) => typeof item === "object" &&
+                issues = json
+                    .filter((item) => typeof item === "object" &&
                     item !== null &&
                     typeof item.number === "number" &&
-                    typeof item.title === "string");
+                    typeof item.title === "string")
+                    .map(normalizeIssue);
             }
         }
     }
@@ -165,6 +167,51 @@ export async function fetchKnownIssues() {
     cache = { data: result, fetchedAt: now };
     return result;
 }
+/**
+ * Coerce a loosely-validated GitHub API item into a complete {@link GitHubIssue}.
+ *
+ * The upstream type guard only asserts `number` + `title`. A malformed API
+ * response — or a partial item served during a GitHub incident — can be
+ * missing `user`, `labels` or `updated_at`. Reading those unconditionally in
+ * `formatIssues` throws a `TypeError` and takes down the whole
+ * `sceneview://known-issues` resource. Default every optional field here so
+ * formatting can never crash.
+ */
+function normalizeIssue(item) {
+    const rawLabels = item.labels;
+    const labels = Array.isArray(rawLabels)
+        ? rawLabels
+            .map((l) => {
+            if (typeof l === "string")
+                return { name: l };
+            if (l !== null && typeof l === "object") {
+                const name = l.name;
+                if (typeof name === "string")
+                    return { name };
+            }
+            return null;
+        })
+            .filter((l) => l !== null)
+        : [];
+    const rawUser = item.user;
+    const login = rawUser !== null &&
+        typeof rawUser === "object" &&
+        typeof rawUser.login === "string"
+        ? rawUser.login
+        : "unknown";
+    const updatedAt = typeof item.updated_at === "string" ? item.updated_at : "";
+    const createdAt = typeof item.created_at === "string" ? item.created_at : "";
+    return {
+        number: item.number,
+        title: item.title,
+        html_url: typeof item.html_url === "string" ? item.html_url : "",
+        body: typeof item.body === "string" ? item.body : null,
+        labels,
+        created_at: createdAt,
+        updated_at: updatedAt,
+        user: { login },
+    };
+}
 function formatIssues(issues, fetchError) {
     const lines = ["# SceneView — Open GitHub Issues\n"];
     if (fetchError) {

package/dist/telemetry.js

@@ -8,16 +8,25 @@
 //   - client: MCP client name (e.g. "claude-desktop", "cursor")
 //   - clientVersion: MCP client version string reported during handshake
 //   - mcpVersion: this package's version
-//   - tier: "free" | "pro"
+//   - tier: "free" | "pro" — tier the TOOL resolved to, NOT the user's plan
 //   - tool?: tool name (only for "tool" events)
+//   - installId?: opaque random UUID per install — lets the worker count
+//     unique developers per client runtime without identifying who they are
+//   - botLikelihood?: float in [0.0, 1.0] computed at the sender side from
+//     environment signals (CI flags, no-TTY, container hints). Worker uses
+//     it to exclude bot traffic from monetization analytics by default.
 //
 // What NEVER gets sent:
 //   - IP address (the endpoint strips it server-side; we never send headers)
-//   - hostname, OS user, machine id
+//   - hostname, OS user, machine id, cwd, project path, package name
 //   - prompt content, tool arguments, tool results
 //   - API keys, billing info
 //
 // Opt out with `SCENEVIEW_TELEMETRY=0` or by running in CI (`CI=true`).
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
 // Worker implementation: telemetry-worker/ (Hono + D1 + KV rate limiting).
 // Deploy with: cd telemetry-worker && see DEPLOY.md
 const TELEMETRY_ENDPOINT = "https://sceneview-telemetry.mcp-tools-lab.workers.dev/v1/events";
@@ -31,6 +40,9 @@ let clientContext;
 // ─── Client-side batch buffer ─────────────────────────────────────────────────
 let buffer = [];
 let flushTimer;
+// Cached fingerprint values — computed once per process.
+let cachedInstallId;
+let cachedBotLikelihood;
 // Read lazily so tests that mutate env vars between runs see the latest value.
 function isEnabled() {
     if (process.env.SCENEVIEW_TELEMETRY === "0")
@@ -47,6 +59,156 @@ import { PACKAGE_VERSION } from "./generated/version.js";
 function getMcpVersion() {
     return process.env.SCENEVIEW_MCP_VERSION ?? PACKAGE_VERSION;
 }
+// ─── Install ID — anonymous per-install fingerprint ──────────────────────────
+//
+// Stored at `$XDG_CONFIG_HOME/sceneview-mcp/install.json` (default
+// `~/.config/sceneview-mcp/install.json`). Created on first run if missing.
+// Contents: `{ "installId": "<uuid v4>", "createdAt": "<ISO>" }`.
+//
+// Why a UUID and not a hash of hostname / cwd / etc.:
+//   - hostnames/cwd are personally identifying (employee laptop name,
+//     `/Users/<name>/...`) — even hashed, they're predictable enough that
+//     a determined attacker with worker-side DB access could brute-force
+//     them back. A UUID is provably non-identifying.
+//   - The point is to count unique developers per `client` runtime, not to
+//     fingerprint the host. A fresh install = a fresh identity, by design.
+//
+// Disabled when telemetry is disabled (no file is written).
+function getInstallIdConfigPath() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    const base = xdg && xdg.length > 0 ? xdg : join(homedir(), ".config");
+    return join(base, "sceneview-mcp", "install.json");
+}
+function loadOrCreateInstallId() {
+    if (cachedInstallId !== undefined)
+        return cachedInstallId;
+    let path;
+    try {
+        path = getInstallIdConfigPath();
+    }
+    catch {
+        return undefined;
+    }
+    // Try to read an existing install record.
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.installId === "string" && parsed.installId.length > 0) {
+            cachedInstallId = parsed.installId;
+            return cachedInstallId;
+        }
+    }
+    catch {
+        // File missing or unreadable — fall through to create.
+    }
+    // Create a fresh install record. All failures are swallowed: a read-only
+    // home directory (CI sandboxes, container images) should not break telemetry
+    // or the MCP server itself.
+    try {
+        const installId = randomUUID();
+        const dir = join(path, "..");
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(path, JSON.stringify({ installId, createdAt: new Date().toISOString() }, null, 2), { encoding: "utf8" });
+        cachedInstallId = installId;
+        return cachedInstallId;
+    }
+    catch {
+        // Fallback: an ephemeral per-process UUID. Better than nothing —
+        // still distinguishes parallel scripted runs from a real install.
+        cachedInstallId = randomUUID();
+        return cachedInstallId;
+    }
+}
+// ─── Bot likelihood — sender-side heuristic ──────────────────────────────────
+//
+// Returns a score in [0.0, 1.0] where 1.0 = almost certainly automation.
+// Signals (each independently bumps the score):
+//
+//   - GITHUB_ACTIONS / GITLAB_CI / CIRCLECI / BUILDKITE / TF_BUILD / JENKINS_URL
+//     are set                                              → +0.45 (strong)
+//   - CI is set to any truthy value                        → +0.30 (medium)
+//   - stdout is not a TTY                                  → +0.15 (weak)
+//   - common container/sandbox hints
+//     (KUBERNETES_SERVICE_HOST, container=docker, AWS_LAMBDA_FUNCTION_NAME)
+//                                                          → +0.20 (medium)
+//   - DEBIAN_FRONTEND=noninteractive (popular in scripts)  → +0.10 (weak)
+//
+// The score is computed ONCE per process and reused on every event. It is
+// clamped to [0.0, 1.0]. The worker uses it as an advisory exclusion filter
+// (default threshold 0.7); raw events are still stored for forensics.
+function computeBotLikelihood() {
+    if (cachedBotLikelihood !== undefined)
+        return cachedBotLikelihood;
+    let score = 0;
+    const env = process.env;
+    // Strong: a named CI provider env var.
+    const strongCiVars = [
+        "GITHUB_ACTIONS",
+        "GITLAB_CI",
+        "CIRCLECI",
+        "BUILDKITE",
+        "TF_BUILD",
+        "JENKINS_URL",
+        "BITBUCKET_BUILD_NUMBER",
+        "TEAMCITY_VERSION",
+        "TRAVIS",
+        "DRONE",
+    ];
+    if (strongCiVars.some((k) => typeof env[k] === "string" && env[k].length > 0)) {
+        score += 0.45;
+    }
+    // Medium: generic CI=truthy. We don't double-count if a strong var fired,
+    // but for cheap envs ("CI=true" alone), this captures them.
+    const ci = env.CI;
+    if (typeof ci === "string" && (ci === "true" || ci === "1")) {
+        score += 0.3;
+    }
+    // Weak: no TTY → almost always automation or piped invocation. We test
+    // stdout because the MCP protocol uses stdin/stdout, but stderr is the
+    // more reliable indicator of "is a human watching".
+    try {
+        // process.stderr is most reliable; some MCP runners pipe stdout but leave
+        // stderr attached. Both being non-TTY is a stronger bot signal.
+        const stderrTty = typeof process.stderr === "object" &&
+            typeof process.stderr.isTTY === "boolean" &&
+            process.stderr.isTTY === true;
+        if (!stderrTty)
+            score += 0.15;
+    }
+    catch {
+        // Defensive — if stderr isn't introspectable, treat as non-TTY.
+        score += 0.15;
+    }
+    // Medium: containerized environments.
+    const containerVars = [
+        "KUBERNETES_SERVICE_HOST",
+        "AWS_LAMBDA_FUNCTION_NAME",
+        "VERCEL",
+        "NETLIFY",
+        "CODESPACE_NAME",
+    ];
+    if (containerVars.some((k) => typeof env[k] === "string" && env[k].length > 0) ||
+        env.container === "docker") {
+        score += 0.2;
+    }
+    // Weak: scripted invocations frequently set this.
+    if (env.DEBIAN_FRONTEND === "noninteractive")
+        score += 0.1;
+    cachedBotLikelihood = Math.min(1, Math.max(0, score));
+    return cachedBotLikelihood;
+}
+// Build a base payload populated with the install fingerprint + bot score.
+// `installId` is omitted when telemetry is disabled or the install file
+// could not be created. `botLikelihood` is always present (default 0).
+function buildBase() {
+    const out = {
+        botLikelihood: computeBotLikelihood(),
+    };
+    const installId = loadOrCreateInstallId();
+    if (installId)
+        out.installId = installId;
+    return out;
+}
 // Fire-and-forget POST of a single payload to the individual event endpoint.
 // Used as fallback when batch delivery fails.
 function sendSingle(payload) {
@@ -148,6 +310,8 @@ function send(payload) {
 /** Exposed for tests — resets the cached client context and the batch buffer. */
 export function __resetClientContext() {
     clientContext = undefined;
+    cachedInstallId = undefined;
+    cachedBotLikelihood = undefined;
     buffer = [];
     if (flushTimer !== undefined) {
         clearTimeout(flushTimer);
@@ -175,6 +339,7 @@ export function recordClientInit(clientInfo) {
         clientVersion: clientContext.clientVersion,
         mcpVersion: getMcpVersion(),
         tier: "free",
+        ...buildBase(),
     });
 }
 /**
@@ -196,5 +361,16 @@ export function recordToolCall(toolName, tier) {
         mcpVersion: getMcpVersion(),
         tier,
         tool: toolName,
+        ...buildBase(),
     });
 }
+// ─── Test-only exports ────────────────────────────────────────────────────────
+/** Exposed for tests — bypass the cache and recompute the bot score. */
+export function __computeBotLikelihoodForTest() {
+    cachedBotLikelihood = undefined;
+    return computeBotLikelihood();
+}
+/** Exposed for tests — read the install ID without going through send(). */
+export function __getInstallIdForTest() {
+    return loadOrCreateInstallId();
+}

package/dist/tiers.js

@@ -29,6 +29,8 @@ const FREE_TOOLS = [
     "get_platform_roadmap",
     "search_models",
     "analyze_project",
+    "search_android_docs",
+    "fetch_android_doc",
     // Setup guides (moved from Pro in 4.0.5)
     "get_ios_setup",
     "get_web_setup",

package/dist/tools/definitions.js

@@ -604,4 +604,42 @@ export const TOOL_DEFINITIONS = [
             destructiveHint: false,
         },
     },
+    {
+        name: "search_android_docs",
+        description: "Searches Google's stock Android documentation knowledge base (~4 800 entries: Jetpack Compose, Camera2, ARCore SDK, Kotlin APIs, platform guides) and returns matching entries with their `kb://...` URIs. Use this to cross-reference stock Android APIs with SceneView code — e.g. \"how does LazyColumn paging work\", \"Camera2 capture session\", \"ARCore Config options\". Then call `fetch_android_doc` with a returned URI to read the full entry. Requires Google's `android` CLI on the MCP host's PATH (an optional runtime dependency — sceneview-mcp works without it); if the CLI is absent the tool returns clear install instructions instead of crashing.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Free-text search query, e.g. \"LazyColumn paging\", \"Camera2 capture session\", \"ARCore anchors\".",
+                },
+            },
+            required: ["query"],
+        },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true,
+            destructiveHint: false,
+        },
+    },
+    {
+        name: "fetch_android_doc",
+        description: "Fetches the full text of a single stock Android documentation entry by its knowledge-base URI (`kb://...`), as returned by `search_android_docs`. Use this after `search_android_docs` to read a complete guide or API reference. Requires Google's `android` CLI on the MCP host's PATH (an optional runtime dependency); if the CLI is absent the tool returns clear install instructions instead of crashing.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                uri: {
+                    type: "string",
+                    description: "The knowledge-base URI to fetch, e.g. \"kb://compose/lists/lazy-column\". A bare path with no scheme is tolerated and normalised to kb://.",
+                },
+            },
+            required: ["uri"],
+        },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true,
+            destructiveHint: false,
+        },
+    },
 ];

package/dist/tools/handler.js

@@ -34,6 +34,7 @@ import { ANIMATION_GUIDE, GESTURE_GUIDE, PERFORMANCE_TIPS, } from "../advanced-g
 import { MATERIAL_GUIDE, COLLISION_GUIDE, MODEL_OPTIMIZATION_GUIDE, WEB_RENDERING_GUIDE, } from "../extra-guides.js";
 import { searchModels, formatSearchResults } from "../search-models.js";
 import { analyzeProject, formatAnalysisReport } from "../analyze-project.js";
+import { searchAndroidDocs, fetchAndroidDoc, formatAndroidDocsSearch, formatAndroidDocsFetch, } from "../android-docs.js";
 import { LLMS_TXT } from "../generated/llms-txt.js";
 import { LATEST_SCENEVIEW_RELEASE } from "../generated/version.js";
 // ─── Legal disclaimer (identical to index.ts 4.0.0) ─────────────────────
@@ -789,6 +790,38 @@ export async function dispatchTool(toolName, args, _ctx = {}) {
                 };
             }
         }
+        // ── search_android_docs ──────────────────────────────────────────────────
+        case "search_android_docs": {
+            const query = args?.query;
+            if (!query || typeof query !== "string" || query.trim().length === 0) {
+                return {
+                    content: [{ type: "text", text: "Missing required parameter: `query` must be a non-empty string." }],
+                    isError: true,
+                };
+            }
+            const docsResult = await searchAndroidDocs(query);
+            const text = formatAndroidDocsSearch(query, docsResult);
+            return {
+                content: withDisclaimer([{ type: "text", text }]),
+                isError: docsResult.ok ? undefined : true,
+            };
+        }
+        // ── fetch_android_doc ────────────────────────────────────────────────────
+        case "fetch_android_doc": {
+            const uri = args?.uri;
+            if (!uri || typeof uri !== "string" || uri.trim().length === 0) {
+                return {
+                    content: [{ type: "text", text: "Missing required parameter: `uri` must be a non-empty `kb://...` string." }],
+                    isError: true,
+                };
+            }
+            const docResult = await fetchAndroidDoc(uri);
+            const text = formatAndroidDocsFetch(uri, docResult);
+            return {
+                content: withDisclaimer([{ type: "text", text }]),
+                isError: docResult.ok ? undefined : true,
+            };
+        }
         default:
             return {
                 content: [{ type: "text", text: `Unknown tool: ${toolName}` }],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sceneview-mcp",
-  "version": "4.0.12",
+  "version": "4.0.13",
   "mcpName": "io.github.sceneview/mcp",
   "description": "MCP server for SceneView — cross-platform 3D & AR SDK for Android and iOS. Give Claude the full SceneView SDK so it writes correct, compilable code.",
   "keywords": [
@@ -64,12 +64,15 @@
     "prepare": "node scripts/generate-llms-txt.js && node scripts/generate-version.js && tsc",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
-    "test": "node scripts/generate-llms-txt.js && node scripts/generate-version.js && vitest run"
+    "test": "node scripts/generate-llms-txt.js && node scripts/generate-version.js && vitest run",
+    "biome": "cd .. && mcp/node_modules/.bin/biome check",
+    "biome:fix": "cd .. && mcp/node_modules/.bin/biome check --write"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
     "@types/node": "^25.5.0",
     "tsx": "^4.0.0",
     "typescript": "^6.0.2",