sceneview-mcp 3.6.2 → 3.6.5

package/README.md

@@ -38,6 +38,8 @@ Connect it to Claude, Cursor, Windsurf, or any MCP client. The assistant gets 26
 npx sceneview-mcp
 ```
 
+> **Anonymous telemetry** is enabled on the free tier (MCP client name/version and tool names — no personal data, no prompt content). Opt out with `SCENEVIEW_TELEMETRY=0`. See [PRIVACY.md](./PRIVACY.md#telemetry-free-tier) for the full payload shape.
+
 ### Claude Desktop
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
@@ -110,6 +112,43 @@ Same JSON config as above. The server communicates via **stdio** using the stand
 | `get_animation_guide` | Guide for model animations, Spring physics, Compose property animations, SmoothTransform |
 | `get_gesture_guide` | Guide for gestures: isEditable, onTouchEvent, tap-to-place, drag-to-rotate, pinch-to-scale |
 | `get_performance_tips` | Performance optimization: LOD, texture compression, instancing, profiling with Systrace/AGI |
+| `search_models` | Searches Sketchfab for free 3D models matching a query (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 (threading, LightNode bug, 2.x APIs) |
+
+#### `search_models` — find real 3D assets from the AI
+
+Generated SceneView code is only useful if it points at an asset that actually exists. `search_models` queries Sketchfab's public search API and returns a shortlist with names, authors, licenses, thumbnails, triangle counts, and viewer/embed URLs that the assistant can drop straight into `rememberModelInstance(modelLoader, ...)` or embed as a live preview.
+
+**Bring your own key (BYOK).** SceneView never proxies the request — you keep the rate limit and the cost stays at zero. To set it up:
+
+1. Create a free account at [sketchfab.com/register](https://sketchfab.com/register)
+2. Copy your API token from [sketchfab.com/settings/password](https://sketchfab.com/settings/password)
+3. Set `SKETCHFAB_API_KEY` in your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "sceneview": {
+      "command": "npx",
+      "args": ["-y", "sceneview-mcp"],
+      "env": { "SKETCHFAB_API_KEY": "YOUR_TOKEN_HERE" }
+    }
+  }
+}
+```
+
+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.
+
+#### `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:
+
+- Detects the project type by looking for `build.gradle(.kts)` with `io.github.sceneview:sceneview` (Android), `Package.swift` with `SceneViewSwift` (iOS), or `package.json` with `sceneview-web` (Web).
+- Extracts the SceneView dependency version and compares it against the latest release known to this MCP build, flagging outdated projects.
+- Walks up to **30** source files (`.kt`, `.kts`, `.swift`, `.js`, `.ts`) and up to **500 KB** total, scanning for well-known anti-patterns: Filament/ModelLoader calls inside background coroutines, the `LightNode(...) { ... }` trailing-lambda bug, deprecated 2.x APIs (`ArSceneView`, `TransformableNode`, `PlacementNode`, `ViewRenderable`, `loadModelAsync`), and `com.google.ar.sceneform.*` imports.
+- Returns a structured `{ projectType, sceneViewVersion, latestVersion, isOutdated, warnings, suggestions }` report, plus a Markdown summary.
+
+The tool is read-only, never writes to disk, and gracefully handles missing directories. Use it when the user asks "is my project up to date?" or as a quick sanity check before generating new code for an existing codebase.
 
 ### 2 resources
 

package/dist/analyze-project.js

@@ -0,0 +1,500 @@
+/**
+ * analyze-project — local filesystem scan of a SceneView project.
+ *
+ * Because the SceneView MCP server runs on the user's machine, we can read
+ * their project files directly: detect the platform (Android / iOS / Web),
+ * extract the SceneView dependency version, compare against the latest known
+ * release, and scan source files for well-known anti-patterns (threading
+ * violations, LightNode trailing-lambda bug, deprecated 2.x APIs, …).
+ *
+ * This is the first real *agentic* tool in the MCP — previous tools were
+ * static getters, this one actually inspects the caller's filesystem to
+ * produce a tailored report.
+ *
+ * Hard safety limits:
+ *   - at most {@link MAX_FILES_SCANNED} source files read
+ *   - at most {@link MAX_BYTES_SCANNED} bytes read in total
+ *   - at most {@link MAX_DIR_DEPTH} directory levels traversed
+ *
+ * When any limit is hit we stop walking and return a warning so the caller
+ * knows the scan was truncated — we never throw.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+// ─── Constants ───────────────────────────────────────────────────────────────
+/** The latest SceneView release known to this build of the MCP. */
+export const LATEST_SCENEVIEW_VERSION = "3.6.2";
+/** Hard cap on the number of source files inspected per call. */
+export const MAX_FILES_SCANNED = 30;
+/** Hard cap on total bytes read across all source files per call (500 KB). */
+export const MAX_BYTES_SCANNED = 500 * 1024;
+/** Max directory tree depth traversed from the project root. */
+export const MAX_DIR_DEPTH = 12;
+/** Directories we never recurse into (build outputs, caches, vendored deps). */
+const SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "build",
+    "dist",
+    ".gradle",
+    ".idea",
+    ".vscode",
+    ".claude",
+    "Pods",
+    "DerivedData",
+    ".build",
+    "out",
+    "target",
+]);
+/** File extensions we consider "source" for anti-pattern scanning. */
+const SOURCE_EXTENSIONS = new Set([".kt", ".kts", ".swift", ".js", ".mjs", ".ts", ".tsx"]);
+/**
+ * The curated list of anti-patterns we scan for. This is a deliberately
+ * smaller subset of the full `validator.ts` rules — the goal here is "fast
+ * sanity check of an entire project", not a per-file lint pass.
+ *
+ * Covered:
+ *   - threading: Filament/ModelLoader calls inside a background launch block
+ *   - API misuse: LightNode trailing-lambda bug
+ *   - 2.x deprecated APIs: ArSceneView, TransformableNode, PlacementNode,
+ *     ViewRenderable, loadModelAsync, Sceneform imports
+ */
+const ANTI_PATTERNS = [
+    // ─── Threading: modelLoader.createModel* inside a non-main launch ──────────
+    {
+        id: "threading/filament-off-main-thread",
+        languages: new Set(["kotlin"]),
+        pattern: /modelLoader\s*\.\s*createModel\w*\s*\(/,
+        message: "`modelLoader.createModel*` is called in a file that also uses a background coroutine " +
+            "(`launch {` / `Dispatchers.IO` / `Dispatchers.Default`). Filament JNI calls must run on " +
+            "the main thread. Use `rememberModelInstance(modelLoader, path)` in composables, or " +
+            "`withContext(Dispatchers.Main)` in imperative code.",
+        fileGuard: (contents) => /\blaunch\s*\(?\s*Dispatchers\.(IO|Default)\b/.test(contents) ||
+            /\blaunch\s*\{/.test(contents) ||
+            /\bwithContext\s*\(\s*Dispatchers\.(IO|Default)\b/.test(contents),
+    },
+    // ─── API: LightNode(...) { ... } trailing-lambda bug ───────────────────────
+    {
+        id: "api/light-node-trailing-lambda",
+        languages: new Set(["kotlin"]),
+        pattern: /\bLightNode\s*\([^)]*\)\s*\{/,
+        message: "`LightNode`'s configuration block is a **named parameter** `apply`, not a trailing " +
+            "lambda. Write `LightNode(engine = engine, type = ..., apply = { intensity(100_000f) })`. " +
+            "Without `apply =` the block is silently ignored.",
+    },
+    // ─── Deprecated 2.x APIs ───────────────────────────────────────────────────
+    {
+        id: "migration/ar-scene-view-rename",
+        languages: new Set(["kotlin"]),
+        pattern: /\bArSceneView\s*\(/,
+        message: "`ArSceneView` was renamed to `ARSceneView` in SceneView 3.0. Update the call site " +
+            "(capital R). Run `migrate_code` for an automatic rewrite.",
+    },
+    {
+        id: "migration/transformable-node-removed",
+        languages: new Set(["kotlin"]),
+        pattern: /\bTransformableNode\b/,
+        message: "`TransformableNode` was removed in SceneView 3.0. Set `isEditable = true` on a " +
+            "`ModelNode` or `GeometryNode` instead.",
+    },
+    {
+        id: "migration/placement-node-removed",
+        languages: new Set(["kotlin"]),
+        pattern: /\bPlacementNode\b/,
+        message: "`PlacementNode` was removed in SceneView 3.0. Use `AnchorNode` + `HitResultNode` " +
+            "inside an `ARSceneView` instead.",
+    },
+    {
+        id: "migration/view-renderable-removed",
+        languages: new Set(["kotlin"]),
+        pattern: /\bViewRenderable\b/,
+        message: "`ViewRenderable` was removed in SceneView 3.0. Use `ViewNode` with a `@Composable` " +
+            "content lambda instead.",
+    },
+    {
+        id: "migration/load-model-async",
+        languages: new Set(["kotlin"]),
+        pattern: /\bmodelLoader\s*\.\s*loadModelAsync\s*\(/,
+        message: "`modelLoader.loadModelAsync` was removed in SceneView 3.0. Use " +
+            "`rememberModelInstance(modelLoader, path)` in composables, or " +
+            "`modelLoader.loadModelInstanceAsync(path)` in imperative code.",
+    },
+    {
+        id: "migration/sceneform-import",
+        languages: new Set(["kotlin"]),
+        pattern: /\bimport\s+com\.google\.ar\.sceneform\b/,
+        message: "`com.google.ar.sceneform.*` was deprecated by Google in 2021. Replace with " +
+            "`io.github.sceneview.*` imports — SceneView is the official successor.",
+    },
+    {
+        id: "migration/scene-view-renamed",
+        languages: new Set(["kotlin"]),
+        pattern: /\bimport\s+com\.google\.ar\.sceneform\.ux\.ArFragment\b/,
+        message: "`ArFragment` (Sceneform) removed. Replace with `ARSceneView { … }` composable from " +
+            "`io.github.sceneview.ar`.",
+    },
+];
+function languageOf(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === ".kt" || ext === ".kts")
+        return "kotlin";
+    if (ext === ".swift")
+        return "swift";
+    if (ext === ".js" || ext === ".mjs" || ext === ".ts" || ext === ".tsx")
+        return "js";
+    return null;
+}
+/** Walk `dir` depth-first and collect source files, respecting skip-dirs and depth. */
+async function collectSourceFiles(rootDir, dir, depth, out) {
+    if (depth > MAX_DIR_DEPTH)
+        return;
+    if (out.length >= MAX_FILES_SCANNED)
+        return;
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    // Deterministic order for reproducible tests.
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        if (out.length >= MAX_FILES_SCANNED)
+            return;
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (SKIP_DIRS.has(entry.name) || entry.name.startsWith("."))
+                continue;
+            await collectSourceFiles(rootDir, abs, depth + 1, out);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        if (SOURCE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+            out.push(abs);
+        }
+    }
+}
+async function readFileSafe(filePath) {
+    try {
+        return await fs.readFile(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+async function tryRead(dir, ...relativeCandidates) {
+    for (const rel of relativeCandidates) {
+        const abs = path.join(dir, rel);
+        const contents = await readFileSafe(abs);
+        if (contents != null)
+            return { path: abs, contents };
+    }
+    return null;
+}
+/** Extract `X.Y.Z` from a Gradle-style `io.github.sceneview:sceneview:X.Y.Z` reference. */
+function extractGradleVersion(contents) {
+    const match = contents.match(/io\.github\.sceneview:(?:sceneview|arsceneview|sceneview-core)[:"']?\s*[:"']?\s*(?:version\s*=\s*["'])?(\d+\.\d+\.\d+(?:-[\w.]+)?)/);
+    if (match)
+        return match[1];
+    return null;
+}
+/** Extract `X.Y.Z` from a `Package.swift` `SceneViewSwift` dependency. */
+function extractSwiftVersion(contents) {
+    // Matches `.package(url: ".../sceneview"..., from: "3.6.2")` or `.upToNextMajor(from: "3.6.0")`.
+    const fromMatch = contents.match(/sceneview[^"]*"[^)]*from:\s*"(\d+\.\d+\.\d+(?:-[\w.]+)?)"/i);
+    if (fromMatch)
+        return fromMatch[1];
+    const exactMatch = contents.match(/sceneview[^"]*"[^)]*exact:\s*"(\d+\.\d+\.\d+(?:-[\w.]+)?)"/i);
+    if (exactMatch)
+        return exactMatch[1];
+    const branchOrVersion = contents.match(/\.package\([^)]*sceneview[^)]*"(\d+\.\d+\.\d+)"/i);
+    if (branchOrVersion)
+        return branchOrVersion[1];
+    return null;
+}
+/** Extract the `sceneview-web` version from a `package.json`. */
+function extractNpmVersion(contents) {
+    try {
+        const pkg = JSON.parse(contents);
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        for (const [name, spec] of Object.entries(deps)) {
+            if (name === "sceneview-web" || name === "@sceneview/sceneview-web") {
+                // Strip leading ^ / ~ / >= etc.
+                const cleaned = spec.replace(/^[^\d]*/, "");
+                const match = cleaned.match(/\d+\.\d+\.\d+(?:-[\w.]+)?/);
+                if (match)
+                    return match[0];
+            }
+        }
+    }
+    catch {
+        // Not JSON — fall through.
+    }
+    return null;
+}
+async function detectProject(rootDir) {
+    // Android: build.gradle or build.gradle.kts anywhere reachable from root.
+    // We first check the root for speed, then one level down for typical module layouts.
+    const androidCandidates = [
+        "build.gradle.kts",
+        "build.gradle",
+        "app/build.gradle.kts",
+        "app/build.gradle",
+        "sample/build.gradle.kts",
+        "sample/build.gradle",
+    ];
+    for (const rel of androidCandidates) {
+        const read = await tryRead(rootDir, rel);
+        if (read && /io\.github\.sceneview:(sceneview|arsceneview|sceneview-core)/.test(read.contents)) {
+            return {
+                projectType: "android",
+                sceneViewVersion: extractGradleVersion(read.contents),
+                sourceFile: read.path,
+            };
+        }
+    }
+    // iOS: Package.swift at root mentioning SceneViewSwift.
+    const packageSwift = await tryRead(rootDir, "Package.swift");
+    if (packageSwift && /SceneViewSwift|sceneview\/sceneview/i.test(packageSwift.contents)) {
+        return {
+            projectType: "ios",
+            sceneViewVersion: extractSwiftVersion(packageSwift.contents),
+            sourceFile: packageSwift.path,
+        };
+    }
+    // Web: package.json referencing sceneview-web.
+    const packageJson = await tryRead(rootDir, "package.json");
+    if (packageJson && /"(?:@sceneview\/)?sceneview-web"/.test(packageJson.contents)) {
+        return {
+            projectType: "web",
+            sceneViewVersion: extractNpmVersion(packageJson.contents),
+            sourceFile: packageJson.path,
+        };
+    }
+    return { projectType: "unknown", sceneViewVersion: null, sourceFile: null };
+}
+// ─── Semver comparison (simple X.Y.Z) ────────────────────────────────────────
+/**
+ * Returns `true` when `version` is strictly older than `LATEST_SCENEVIEW_VERSION`.
+ * Falls back to `false` (don't flag) if either side fails to parse cleanly —
+ * we'd rather underreport than harass a user with a pre-release build.
+ */
+function isVersionOutdated(version) {
+    if (!version)
+        return false;
+    const parse = (v) => {
+        const m = v.match(/^(\d+)\.(\d+)\.(\d+)/);
+        if (!m)
+            return null;
+        return [parseInt(m[1], 10), parseInt(m[2], 10), parseInt(m[3], 10)];
+    };
+    const a = parse(version);
+    const b = parse(LATEST_SCENEVIEW_VERSION);
+    if (!a || !b)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] < b[i])
+            return true;
+        if (a[i] > b[i])
+            return false;
+    }
+    return false;
+}
+// ─── Public entrypoint ───────────────────────────────────────────────────────
+/**
+ * Scan a local SceneView project and return a structured analysis.
+ *
+ * Never throws for filesystem errors — missing directory, permission denied,
+ * broken file: all surface as a warning in the returned result.
+ */
+export async function analyzeProject(input = {}) {
+    const rawPath = input.path ?? process.cwd();
+    const scannedPath = path.resolve(rawPath);
+    const result = {
+        projectType: "unknown",
+        sceneViewVersion: null,
+        latestVersion: LATEST_SCENEVIEW_VERSION,
+        isOutdated: false,
+        warnings: [],
+        suggestions: [],
+        scannedPath,
+        filesScanned: 0,
+        bytesScanned: 0,
+        truncated: false,
+    };
+    // Verify the path exists and is a directory.
+    let stat;
+    try {
+        stat = await fs.stat(scannedPath);
+    }
+    catch (err) {
+        result.warnings.push({
+            file: scannedPath,
+            type: "scan/path-not-found",
+            message: `Could not stat project path: ${err.message}. ` +
+                "Pass an existing directory in the `path` argument, or run the tool from inside your project.",
+        });
+        return result;
+    }
+    if (!stat.isDirectory()) {
+        result.warnings.push({
+            file: scannedPath,
+            type: "scan/not-a-directory",
+            message: `Project path exists but is not a directory: ${scannedPath}.`,
+        });
+        return result;
+    }
+    // Step 1: project type + version.
+    const detection = await detectProject(scannedPath);
+    result.projectType = detection.projectType;
+    result.sceneViewVersion = detection.sceneViewVersion;
+    result.isOutdated = isVersionOutdated(detection.sceneViewVersion);
+    if (detection.projectType === "unknown") {
+        result.warnings.push({
+            file: scannedPath,
+            type: "scan/no-sceneview-dependency",
+            message: "No SceneView dependency was detected. Looked for `io.github.sceneview:sceneview` in " +
+                "Gradle files, `SceneViewSwift` in `Package.swift`, and `sceneview-web` in `package.json`.",
+        });
+    }
+    else if (!detection.sceneViewVersion) {
+        result.warnings.push({
+            file: detection.sourceFile ?? scannedPath,
+            type: "scan/version-unresolved",
+            message: "SceneView dependency was found but the version could not be extracted. This usually " +
+                "means the version is declared through a variable or a version catalog — check your " +
+                "`libs.versions.toml` or a shared `ext.sceneview_version` definition.",
+        });
+    }
+    if (result.isOutdated && detection.sceneViewVersion) {
+        result.suggestions.push({
+            type: "suggestion/upgrade-sceneview",
+            message: `You are on SceneView ${detection.sceneViewVersion}. The latest known release is ` +
+                `${LATEST_SCENEVIEW_VERSION}. Consider upgrading — run \`get_migration_guide\` for ` +
+                "the 2.x → 3.x migration notes, or `migrate_code` for automatic Kotlin rewrites.",
+        });
+    }
+    // Step 2: anti-pattern scan (only if we have a known project type).
+    if (detection.projectType !== "unknown") {
+        const sourceFiles = [];
+        await collectSourceFiles(scannedPath, scannedPath, 0, sourceFiles);
+        const truncatedByFileCount = sourceFiles.length >= MAX_FILES_SCANNED;
+        let totalBytes = 0;
+        for (const file of sourceFiles) {
+            if (result.filesScanned >= MAX_FILES_SCANNED) {
+                result.truncated = true;
+                break;
+            }
+            if (totalBytes >= MAX_BYTES_SCANNED) {
+                result.truncated = true;
+                break;
+            }
+            const contents = await readFileSafe(file);
+            if (contents == null)
+                continue;
+            const byteLen = Buffer.byteLength(contents, "utf-8");
+            // Would this file push us over the byte cap? If yes, still scan once
+            // (a single giant file shouldn't silently fail) then stop the loop.
+            totalBytes += byteLen;
+            result.filesScanned += 1;
+            result.bytesScanned = totalBytes;
+            const lang = languageOf(file);
+            if (!lang)
+                continue;
+            scanFileForAntiPatterns(file, lang, contents, result.warnings);
+            if (totalBytes >= MAX_BYTES_SCANNED) {
+                result.truncated = true;
+                break;
+            }
+        }
+        if (truncatedByFileCount) {
+            result.truncated = true;
+        }
+        if (result.truncated) {
+            result.warnings.push({
+                file: scannedPath,
+                type: "scan/truncated",
+                message: `Scan truncated at ${result.filesScanned} files / ${result.bytesScanned} bytes ` +
+                    `(limits: ${MAX_FILES_SCANNED} files, ${MAX_BYTES_SCANNED} bytes). Some files may ` +
+                    "not have been inspected — run `validate_code` on specific snippets for a deeper check.",
+            });
+        }
+    }
+    // Step 3: tailored suggestions.
+    if (result.warnings.some((w) => w.type.startsWith("migration/"))) {
+        result.suggestions.push({
+            type: "suggestion/run-migrate-code",
+            message: "Deprecated 2.x APIs were detected. Run the `migrate_code` tool on the offending " +
+                "files for an automatic rewrite to 3.x.",
+        });
+    }
+    if (result.warnings.some((w) => w.type === "threading/filament-off-main-thread")) {
+        result.suggestions.push({
+            type: "suggestion/fix-threading",
+            message: "Filament JNI calls were detected alongside background coroutines. Switch to " +
+                "`rememberModelInstance` in composables, or wrap imperative loads in " +
+                "`withContext(Dispatchers.Main)`.",
+        });
+    }
+    if (result.projectType !== "unknown" && result.warnings.filter((w) => !w.type.startsWith("scan/")).length === 0) {
+        result.suggestions.push({
+            type: "suggestion/no-issues",
+            message: "No known anti-patterns detected in the scanned files. Call `validate_code` on " +
+                "individual snippets for a deeper per-file check.",
+        });
+    }
+    return result;
+}
+/** Run every registered detector on one file and append findings in place. */
+function scanFileForAntiPatterns(file, language, contents, warnings) {
+    const lines = contents.split("\n");
+    for (const detector of ANTI_PATTERNS) {
+        if (!detector.languages.has(language))
+            continue;
+        if (detector.fileGuard && !detector.fileGuard(contents))
+            continue;
+        for (let i = 0; i < lines.length; i++) {
+            if (detector.pattern.test(lines[i])) {
+                warnings.push({
+                    file,
+                    line: i + 1,
+                    type: detector.id,
+                    message: detector.message,
+                });
+            }
+        }
+    }
+}
+// ─── Formatting helper (used by the MCP handler) ────────────────────────────
+/** Render an {@link AnalysisResult} as a Markdown report for MCP clients. */
+export function formatAnalysisReport(result) {
+    const lines = [];
+    lines.push(`## SceneView project analysis`);
+    lines.push(``);
+    lines.push(`**Path:** \`${result.scannedPath}\``);
+    lines.push(`**Project type:** ${result.projectType}`);
+    lines.push(`**SceneView version:** ${result.sceneViewVersion ?? "(not detected)"} — latest: ${result.latestVersion}${result.isOutdated ? " ⚠️ outdated" : ""}`);
+    lines.push(`**Scan:** ${result.filesScanned} file(s), ${result.bytesScanned} byte(s)${result.truncated ? " (truncated)" : ""}`);
+    lines.push(``);
+    if (result.warnings.length === 0) {
+        lines.push(`### Warnings`);
+        lines.push(`No anti-patterns detected.`);
+    }
+    else {
+        lines.push(`### Warnings (${result.warnings.length})`);
+        for (const w of result.warnings) {
+            const loc = w.line ? `${w.file}:${w.line}` : w.file;
+            lines.push(`- **${w.type}** — \`${loc}\`: ${w.message}`);
+        }
+    }
+    lines.push(``);
+    if (result.suggestions.length > 0) {
+        lines.push(`### Suggestions`);
+        for (const s of result.suggestions) {
+            lines.push(`- **${s.type}** — ${s.message}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/auth.js

@@ -0,0 +1,84 @@
+/**
+ * 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,
+    };
+}