sceneview-mcp 4.0.11 → 4.0.13

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,7 +34,9 @@ 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) ─────────────────────
 const DISCLAIMER = "\n\n---\n*Generated code suggestion. Review before use in production. See [TERMS.md](https://github.com/sceneview/sceneview/blob/main/mcp/TERMS.md).*";
 // ─── Sponsor CTA (shown every N tool calls, opt-out via env var) ────────────
@@ -111,7 +113,7 @@ export async function dispatchTool(toolName, args, _ctx = {}) {
                 ? [
                     `**SPM dependency:**`,
                     `\`\`\`swift`,
-                    `.package(url: "${sample.spmDependency ?? sample.dependency}", from: "4.0.0")`,
+                    `.package(url: "${sample.spmDependency ?? sample.dependency}", from: "${LATEST_SCENEVIEW_RELEASE}")`,
                     `\`\`\``,
                 ]
                 : [
@@ -184,7 +186,7 @@ export async function dispatchTool(toolName, args, _ctx = {}) {
                                 `### build.gradle.kts`,
                                 `\`\`\`kotlin`,
                                 `dependencies {`,
-                                `    implementation("io.github.sceneview:sceneview:4.0.0")`,
+                                `    implementation("io.github.sceneview:sceneview:${LATEST_SCENEVIEW_RELEASE}")`,
                                 `}`,
                                 `\`\`\``,
                                 ``,
@@ -205,7 +207,7 @@ export async function dispatchTool(toolName, args, _ctx = {}) {
                                 `### build.gradle.kts`,
                                 `\`\`\`kotlin`,
                                 `dependencies {`,
-                                `    implementation("io.github.sceneview:arsceneview:4.0.0")`,
+                                `    implementation("io.github.sceneview:arsceneview:${LATEST_SCENEVIEW_RELEASE}")`,
                                 `}`,
                                 `\`\`\``,
                                 ``,
@@ -318,7 +320,7 @@ export async function dispatchTool(toolName, args, _ctx = {}) {
                                 `\`\`\``,
                                 `https://github.com/sceneview/sceneview`,
                                 `\`\`\``,
-                                `Set version rule to **"from: 4.0.0"**.`,
+                                `Set version rule to **"from: ${LATEST_SCENEVIEW_RELEASE}"**.`,
                                 ``,
                                 `Or in Package.swift:`,
                                 `\`\`\`swift`,
@@ -329,7 +331,7 @@ export async function dispatchTool(toolName, args, _ctx = {}) {
                                 `    name: "MyApp",`,
                                 `    platforms: [.iOS(.v17), .macOS(.v14), .visionOS(.v1)],`,
                                 `    dependencies: [`,
-                                `        .package(url: "https://github.com/sceneview/sceneview", from: "4.0.0")`,
+                                `        .package(url: "https://github.com/sceneview/sceneview", from: "${LATEST_SCENEVIEW_RELEASE}")`,
                                 `    ],`,
                                 `    targets: [`,
                                 `        .executableTarget(`,
@@ -400,7 +402,7 @@ export async function dispatchTool(toolName, args, _ctx = {}) {
                                 `### 1. Add SPM Dependency`,
                                 ``,
                                 `\`\`\`swift`,
-                                `.package(url: "https://github.com/sceneview/sceneview", from: "4.0.0")`,
+                                `.package(url: "https://github.com/sceneview/sceneview", from: "${LATEST_SCENEVIEW_RELEASE}")`,
                                 `\`\`\``,
                                 ``,
                                 `### 2. Minimum Platform`,
@@ -679,16 +681,22 @@ export async function dispatchTool(toolName, args, _ctx = {}) {
         }
         // ── list_platforms ────────────────────────────────────────────────────────
         case "list_platforms": {
+            // All `version:` and `dependency:` fields use `LATEST_SCENEVIEW_RELEASE`
+            // explicitly so each platform row renders the actually-current SDK
+            // version. Pre-fix these were double-quoted strings with a literal
+            // `${LATEST_SCENEVIEW_RELEASE}` substring that never interpolated —
+            // users following list_platforms output saw the unresolved template
+            // text. Backticks throughout = real interpolation. See #941 follow-up.
             const platforms = [
-                { platform: "Android", renderer: "Filament", framework: "Jetpack Compose", status: "Stable", version: "4.0.0", dependency: "io.github.sceneview:sceneview:4.0.0", features: ["3D", "AR (ARCore)", "Model loading (GLB/glTF)", "Geometry nodes", "Physics", "Gestures"] },
-                { platform: "Android TV", renderer: "Filament", framework: "Compose TV", status: "Alpha", version: "4.0.0", dependency: "io.github.sceneview:sceneview:4.0.0", features: ["3D", "D-pad controls", "Auto-rotation", "Model loading"] },
+                { platform: "Android", renderer: "Filament", framework: "Jetpack Compose", status: "Stable", version: LATEST_SCENEVIEW_RELEASE, dependency: `io.github.sceneview:sceneview:${LATEST_SCENEVIEW_RELEASE}`, features: ["3D", "AR (ARCore)", "Model loading (GLB/glTF)", "Geometry nodes", "Physics", "Gestures"] },
+                { platform: "Android TV", renderer: "Filament", framework: "Compose TV", status: "Alpha", version: LATEST_SCENEVIEW_RELEASE, dependency: `io.github.sceneview:sceneview:${LATEST_SCENEVIEW_RELEASE}`, features: ["3D", "D-pad controls", "Auto-rotation", "Model loading"] },
                 { platform: "Android XR", renderer: "Jetpack XR SceneCore", framework: "Compose XR", status: "Planned", version: "-", dependency: "-", features: ["Spatial computing", "Hand tracking", "Passthrough"] },
-                { platform: "iOS", renderer: "RealityKit", framework: "SwiftUI", status: "Alpha", version: "4.0.0", dependency: "SceneViewSwift (SPM)", features: ["3D", "AR (ARKit)", "16 node types", "USDZ models"] },
-                { platform: "macOS", renderer: "RealityKit", framework: "SwiftUI", status: "Alpha", version: "4.0.0", dependency: "SceneViewSwift (SPM)", features: ["3D", "Orbit camera", "USDZ models"] },
-                { platform: "visionOS", renderer: "RealityKit", framework: "SwiftUI", status: "Alpha", version: "4.0.0", dependency: "SceneViewSwift (SPM)", features: ["3D", "Immersive spaces", "Hand tracking (planned)"] },
-                { platform: "Web", renderer: "Filament.js (WASM)", framework: "Kotlin/JS", status: "Alpha", version: "4.0.0", dependency: "@sceneview/sceneview-web", features: ["3D", "WebXR AR/VR", "GLB models", "WebGL2"] },
-                { platform: "Desktop", renderer: "Software / Filament JNI", framework: "Compose Desktop", status: "Alpha", version: "4.0.0", dependency: "sceneview-desktop (local)", features: ["3D", "Software renderer", "Wireframe"] },
-                { platform: "Flutter", renderer: "Filament / RealityKit", framework: "PlatformView", status: "Alpha", version: "4.0.0", dependency: "flutter pub: sceneview", features: ["3D", "AR", "Android + iOS bridge"] },
+                { platform: "iOS", renderer: "RealityKit", framework: "SwiftUI", status: "Alpha", version: LATEST_SCENEVIEW_RELEASE, dependency: "SceneViewSwift (SPM)", features: ["3D", "AR (ARKit)", "16 node types", "USDZ models"] },
+                { platform: "macOS", renderer: "RealityKit", framework: "SwiftUI", status: "Alpha", version: LATEST_SCENEVIEW_RELEASE, dependency: "SceneViewSwift (SPM)", features: ["3D", "Orbit camera", "USDZ models"] },
+                { platform: "visionOS", renderer: "RealityKit", framework: "SwiftUI", status: "Alpha", version: LATEST_SCENEVIEW_RELEASE, dependency: "SceneViewSwift (SPM)", features: ["3D", "Immersive spaces", "Hand tracking (planned)"] },
+                { platform: "Web", renderer: "Filament.js (WASM)", framework: "Kotlin/JS", status: "Alpha", version: LATEST_SCENEVIEW_RELEASE, dependency: "sceneview-web (npm)", features: ["3D", "WebXR AR/VR", "GLB models", "WebGL2"] },
+                { platform: "Desktop", renderer: "Software / Filament JNI", framework: "Compose Desktop", status: "Alpha", version: LATEST_SCENEVIEW_RELEASE, dependency: "sceneview-desktop (local)", features: ["3D", "Software renderer", "Wireframe"] },
+                { platform: "Flutter", renderer: "Filament / RealityKit", framework: "PlatformView", status: "Alpha", version: LATEST_SCENEVIEW_RELEASE, dependency: "flutter pub: sceneview_flutter (git ref)", features: ["3D", "AR", "Android + iOS bridge"] },
             ];
             const lines = [
                 "## SceneView Supported Platforms\n",
@@ -782,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/dist/validator.js

@@ -180,6 +180,15 @@ const RULES = [
         check(code, lines) {
             const issues = [];
             const renames = [
+                // The headline 4.0 rename — `Scene { }` / `ARScene { }` became
+                // `SceneView { }` / `ARSceneView { }`. Pre-#939 this was missing
+                // from the validator so legacy snippets passed as "no issues".
+                // The regex requires a word boundary + the opening `{` of the
+                // trailing-lambda call, so we don't false-positive on Filament's
+                // own `Scene` class (which is referenced with `()` or `.`, never
+                // followed by `{`).
+                [/\bScene\s*\{/, "`Scene { }` → renamed to `SceneView { }` in 4.0"],
+                [/\bARScene\s*\{/, "`ARScene { }` → renamed to `ARSceneView { }` in 4.0"],
                 [/\bArSceneView\s*\(/, "`ArSceneView(…)` → renamed to `ARSceneView(…)` in 3.0"],
                 [/\bPlacementNode\b/, "`PlacementNode` removed → use `AnchorNode` + `HitResultNode` in 3.0"],
                 [/\bTransformableNode\b/, "`TransformableNode` removed → set `isEditable = true` on `ModelNode` in 3.0"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sceneview-mcp",
-  "version": "4.0.11",
+  "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": [
@@ -44,7 +44,15 @@
     "dist/**/*.js",
     "!dist/**/*.test.js",
     "!dist/**/__fixtures__/**",
-    "llms.txt",
+    "!dist/auth.js",
+    "!dist/billing.js",
+    "!dist/convert-platform.js",
+    "!dist/optimize-scene.js",
+    "!dist/explain-api.js",
+    "!dist/generate-animation.js",
+    "!dist/generate-environment.js",
+    "!dist/generate-gesture.js",
+    "!dist/generate-physics.js",
     "README.md"
   ],
   "engines": {
@@ -53,15 +61,18 @@
   "scripts": {
     "prebuild": "node scripts/generate-llms-txt.js && node scripts/generate-version.js",
     "build": "tsc",
-    "prepare": "cp ../llms.txt ./llms.txt && node scripts/generate-llms-txt.js && node scripts/generate-version.js && tsc",
+    "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",

package/dist/auth.js

@@ -1,84 +0,0 @@
-/**
- * Authentication middleware for the SceneView MCP server.
- *
- * Provides tool-level access control based on free/pro tiers,
- * API key validation, and MCP-formatted denial responses.
- */
-import { isProTool, PRO_UPGRADE_MESSAGE } from "./tiers.js";
-import { getConfiguredApiKey, validateApiKey } from "./billing.js";
-// ─── Main middleware ─────────────────────────────────────────────────────────
-/**
- * Checks whether the current user is allowed to invoke the given tool.
- *
- * - Free-tier tools are always allowed.
- * - Pro-tier tools require a valid API key with an active subscription.
- */
-export async function checkToolAccess(toolName) {
-    // Free-tier tools are always accessible
-    if (!isProTool(toolName)) {
-        return { allowed: true, tier: "free" };
-    }
-    // Pro tool — check for API key
-    const apiKey = getConfiguredApiKey();
-    if (!apiKey) {
-        return {
-            allowed: false,
-            tier: "free",
-            message: PRO_UPGRADE_MESSAGE,
-        };
-    }
-    // Validate the key against the billing service
-    const validation = await validateApiKey(apiKey);
-    if (validation.valid) {
-        return { allowed: true, tier: "pro" };
-    }
-    // Key exists but is invalid or subscription expired
-    return {
-        allowed: false,
-        tier: "free",
-        message: validation.error ?? "Your API key is invalid or your Pro subscription has expired.",
-    };
-}
-// ─── Tool list filtering ─────────────────────────────────────────────────────
-/**
- * Annotates the tool list based on the caller's tier.
- *
- * - Free users see every tool, but pro-only tools get a "[PRO]" prefix on
- *   their description so the AI (and the human) know an upgrade is needed.
- * - Pro users see the list unmodified.
- */
-export async function filterToolsForTier(tools) {
-    const apiKey = getConfiguredApiKey();
-    let isPro = false;
-    if (apiKey) {
-        const validation = await validateApiKey(apiKey);
-        isPro = validation.valid;
-    }
-    if (isPro) {
-        return tools;
-    }
-    // Free tier — prefix pro tool descriptions so users can discover them
-    return tools.map((tool) => {
-        if (!isProTool(tool.name)) {
-            return tool;
-        }
-        const description = typeof tool.description === "string" ? tool.description : "";
-        return {
-            ...tool,
-            description: `[PRO] ${description}`,
-        };
-    });
-}
-// ─── MCP response helpers ────────────────────────────────────────────────────
-/**
- * Builds an MCP-formatted error response for access-denied scenarios.
- *
- * The returned object can be used directly as the handler return value
- * for a `CallToolRequestSchema` handler.
- */
-export function createAccessDeniedResponse(toolName, message) {
-    return {
-        content: [{ type: "text", text: message }],
-        isError: true,
-    };
-}

package/dist/billing.js

@@ -1,137 +0,0 @@
-// ─── Stripe Billing Validation for SceneView MCP Pro ─────────────────────────
-//
-// Validates API keys against Stripe subscriptions to determine tier access.
-// Uses native fetch() — no external Stripe SDK dependency.
-// MCP servers log to stderr (stdout is reserved for the JSON-RPC protocol).
-const cache = new Map();
-const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
-function getCached(apiKey) {
-    const entry = cache.get(apiKey);
-    if (!entry)
-        return undefined;
-    if (Date.now() - entry.cachedAt > CACHE_TTL_MS) {
-        cache.delete(apiKey);
-        return undefined;
-    }
-    return entry.status;
-}
-function setCache(apiKey, status) {
-    cache.set(apiKey, { status, cachedAt: Date.now() });
-}
-/** Clears the validation cache. Useful for testing. */
-export function clearCache() {
-    cache.clear();
-}
-// ─── Development Allowlist ───────────────────────────────────────────────────
-const DEV_ALLOWLIST = new Set([
-    "dev_test_key",
-    "sceneview_dev",
-]);
-function checkDevAllowlist(apiKey) {
-    if (DEV_ALLOWLIST.has(apiKey)) {
-        return { valid: true, tier: "pro" };
-    }
-    return { valid: false, tier: "free", error: "Invalid API key (dev mode — no Stripe configured)" };
-}
-async function fetchStripeSubscription(subscriptionId, stripeSecretKey) {
-    const url = `https://api.stripe.com/v1/subscriptions/${encodeURIComponent(subscriptionId)}`;
-    let response;
-    try {
-        response = await fetch(url, {
-            method: "GET",
-            headers: {
-                Authorization: `Bearer ${stripeSecretKey}`,
-                "Content-Type": "application/x-www-form-urlencoded",
-            },
-        });
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return { valid: false, tier: "free", error: `Stripe API request failed: ${message}` };
-    }
-    if (!response.ok) {
-        const body = await response.text().catch(() => "unknown error");
-        if (response.status === 404) {
-            return { valid: false, tier: "free", error: "Subscription not found" };
-        }
-        return {
-            valid: false,
-            tier: "free",
-            error: `Stripe API error (${response.status}): ${body}`,
-        };
-    }
-    let subscription;
-    try {
-        subscription = (await response.json());
-    }
-    catch {
-        return { valid: false, tier: "free", error: "Failed to parse Stripe response" };
-    }
-    const isActive = subscription.status === "active" || subscription.status === "trialing";
-    const expiresAt = new Date(subscription.current_period_end * 1000).toISOString();
-    if (isActive) {
-        return {
-            valid: true,
-            tier: "pro",
-            customerId: subscription.customer,
-            expiresAt,
-        };
-    }
-    return {
-        valid: false,
-        tier: "free",
-        customerId: subscription.customer,
-        expiresAt,
-        error: `Subscription status is "${subscription.status}" (expected "active" or "trialing")`,
-    };
-}
-// ─── Public API ──────────────────────────────────────────────────────────────
-/**
- * Validates an API key by checking it against Stripe subscriptions.
- *
- * - Results are cached in memory for 5 minutes to avoid excessive Stripe calls.
- * - If `STRIPE_SECRET_KEY` is not set, falls back to a development allowlist.
- * - The API key is treated as a Stripe subscription ID for the lookup.
- */
-export async function validateApiKey(apiKey) {
-    // Check cache first
-    const cached = getCached(apiKey);
-    if (cached)
-        return cached;
-    let result;
-    if (isDevMode()) {
-        // No Stripe key configured — use allowlist for development/testing
-        result = checkDevAllowlist(apiKey);
-    }
-    else {
-        const stripeKey = process.env.STRIPE_SECRET_KEY;
-        result = await fetchStripeSubscription(apiKey, stripeKey);
-    }
-    setCache(apiKey, result);
-    return result;
-}
-/**
- * Returns the configured SceneView API key from the environment, or undefined
- * if the user is on the free tier (no key set).
- */
-export function getConfiguredApiKey() {
-    return process.env.SCENEVIEW_API_KEY;
-}
-/**
- * Returns true when `STRIPE_SECRET_KEY` is not set in the environment.
- * In dev mode, API key validation falls back to a simple allowlist instead
- * of calling the Stripe API.
- */
-export function isDevMode() {
-    return !process.env.STRIPE_SECRET_KEY;
-}
-/**
- * Records usage of an MCP tool for a given API key.
- *
- * Stub for future billing/metering integration. Currently logs to stderr
- * (MCP servers must not write to stdout — it carries the JSON-RPC protocol).
- */
-export async function recordUsage(apiKey, toolName) {
-    const timestamp = new Date().toISOString();
-    process.stderr.write(`[billing] ${timestamp} usage: key=${apiKey.slice(0, 8)}… tool=${toolName}\n`);
-}