sceneview-mcp 4.0.13 → 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 42+ 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,6 +124,7 @@ 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) |
@@ -161,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:
@@ -208,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 42+ 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
 
@@ -216,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)
@@ -225,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).
 
 ---
 
@@ -253,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
 {
@@ -304,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)
 ```
 
@@ -325,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)
@@ -335,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/generate-model.js

@@ -0,0 +1,402 @@
+/**
+ * generate_3d_model — Tripo BYOK text/image→GLB generation tool.
+ *
+ * `search_models` finds assets that already exist; this tool closes the other
+ * half of the agentic asset loop: when no existing model fits, the assistant
+ * generates a brand-new GLB from a text prompt or a source image using the
+ * Tripo AI API (api.tripo3d.ai), then loads it with
+ * `rememberModelInstance(modelLoader, ...)` and places it in AR.
+ *
+ * The tool is BYOK — users bring their own `TRIPO_API_KEY` (create one at
+ * platform.tripo3d.ai/api-keys). We never ship or proxy a key, so there is no
+ * server-side key custody, no cost to us, and no rate-limit sharing across
+ * users — exactly the `SKETCHFAB_API_KEY` pattern used by `search_models`.
+ *
+ * Quality tiers (July 2026 Tripo model catalog):
+ *   - "fast" (default) → P1 low-poly (`P1-20260311`) — AR-ready meshes,
+ *     ~25–30 s, roughly $0.10–0.25 of Tripo credits per generation.
+ *   - "hd" → H3.1 (`v3.1-20260211`) with quad topology + detailed geometry
+ *     and textures — up to ~100 s, roughly $0.41 of Tripo credits.
+ *
+ * API contract (grounded against docs.tripo3d.ai, July 2026):
+ *   1. POST https://api.tripo3d.ai/v2/openapi/task
+ *      Authorization: Bearer <key>
+ *      { "type": "text_to_model", "prompt": "...", "model_version": "..." }
+ *      or
+ *      { "type": "image_to_model", "file": { "type": "jpg|png|...", "url": "..." }, ... }
+ *      → { "code": 0, "data": { "task_id": "..." } }
+ *   2. GET https://api.tripo3d.ai/v2/openapi/task/{task_id} — poll until the
+ *      status is finalized. Status enum: queued | running (ongoing) and
+ *      success | failed | banned | expired | cancelled | unknown (finalized).
+ *      On success, `data.output` carries the model URLs (`pbr_model`,
+ *      `model`, `base_model`) plus `rendered_image`. Download URLs expire
+ *      after ~5 minutes — the caller must download the GLB immediately.
+ *
+ * All network errors, missing keys, task failures, and poll timeouts are
+ * translated to a structured `GenerateModelError` so the MCP handler can
+ * render a clear message without crashing the server.
+ */
+// ─── Configuration ──────────────────────────────────────────────────────────
+const TRIPO_TASK_ENDPOINT = "https://api.tripo3d.ai/v2/openapi/task";
+const API_KEYS_URL = "https://platform.tripo3d.ai/api-keys";
+const MAX_PROMPT_LENGTH = 1024; // Tripo's documented prompt limit.
+/** How often to re-poll the task while it is queued/running. */
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+/**
+ * Bounded polling caps. "fast" (P1) typically finishes in ~25–30 s; "hd"
+ * (H3.1) can take ~100 s, so it gets a 4-minute ceiling. Beyond the cap the
+ * tool returns a `timeout` error instead of hanging the MCP call forever.
+ */
+const QUALITY_TIERS = {
+    fast: {
+        modelVersion: "P1-20260311",
+        label: "fast (Tripo P1 — low-poly, AR-ready)",
+        timeoutMs: 120_000,
+    },
+    hd: {
+        modelVersion: "v3.1-20260211",
+        label: "hd (Tripo H3.1 — quad topology, detailed geometry & textures)",
+        timeoutMs: 240_000,
+    },
+};
+const LICENSE_NOTE = 'Generated with your own Tripo API key — usage rights follow your Tripo plan\'s terms (https://www.tripo3d.ai/api). No third-party author attribution is required, but crediting "Made with Tripo AI" is appreciated.';
+const ATTRIBUTION = "Tripo AI (https://www.tripo3d.ai)";
+/** Finalized-but-not-successful Tripo task statuses. */
+const FAILED_STATUSES = new Set(["failed", "banned", "expired", "cancelled", "unknown"]);
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function missingKeyError() {
+    return {
+        ok: false,
+        code: "missing_key",
+        message: [
+            "generate_3d_model needs a Tripo API key (BYOK — generations are billed to YOUR Tripo account, nothing is charged by SceneView).",
+            "",
+            `1. Create an API key at ${API_KEYS_URL} (new accounts get free trial credits)`,
+            "2. Set the TRIPO_API_KEY environment variable in your MCP client config:",
+            "",
+            "   Claude Desktop / Cursor / Windsurf:",
+            "   {",
+            '     "mcpServers": {',
+            '       "sceneview": {',
+            '         "command": "npx",',
+            '         "args": ["-y", "sceneview-mcp"],',
+            '         "env": { "TRIPO_API_KEY": "YOUR_KEY_HERE" }',
+            "       }",
+            "     }",
+            "   }",
+        ].join("\n"),
+    };
+}
+/**
+ * Derive the Tripo `file.type` hint from the image URL extension. Tripo
+ * documents the field as advisory ("currently not validated") — JPEG and PNG
+ * are the officially supported input formats.
+ */
+function imageTypeFromUrl(url) {
+    const path = url.split(/[?#]/)[0]?.toLowerCase() ?? "";
+    if (path.endsWith(".png"))
+        return "png";
+    if (path.endsWith(".webp"))
+        return "webp";
+    if (path.endsWith(".jpeg"))
+        return "jpeg";
+    return "jpg";
+}
+function isHttpUrl(value) {
+    return /^https?:\/\//i.test(value.trim());
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Build the task-submission body for the requested mode + quality tier.
+ * Exported for tests only.
+ */
+export function buildTaskBody(options) {
+    const tier = QUALITY_TIERS[options.quality];
+    const body = {
+        model_version: tier.modelVersion,
+        texture: true,
+        pbr: true,
+    };
+    if (options.quality === "hd") {
+        // H3.1 add-ons: quad-mesh topology + detailed geometry & textures.
+        body.quad = true;
+        body.geometry_quality = "detailed";
+        body.texture_quality = "detailed";
+    }
+    if (options.prompt !== undefined) {
+        body.type = "text_to_model";
+        body.prompt = options.prompt;
+    }
+    else {
+        body.type = "image_to_model";
+        body.file = {
+            type: imageTypeFromUrl(options.imageUrl ?? ""),
+            url: options.imageUrl,
+        };
+    }
+    return body;
+}
+/** Map a non-OK Tripo HTTP response to a structured error. */
+function httpError(status, statusText) {
+    if (status === 401 || status === 403) {
+        return {
+            ok: false,
+            code: "unauthorized",
+            message: [
+                `Tripo rejected the API key (HTTP ${status}).`,
+                `Double-check the key at ${API_KEYS_URL}, or create a new one — keys look like "tsk_...".`,
+            ].join(" "),
+        };
+    }
+    if (status === 429) {
+        return {
+            ok: false,
+            code: "rate_limited",
+            message: "Tripo rate limit reached (HTTP 429). Wait a minute and retry, or check your plan's concurrency limits at https://platform.tripo3d.ai.",
+        };
+    }
+    return {
+        ok: false,
+        code: "bad_response",
+        message: `Tripo returned HTTP ${status} ${statusText || ""}`.trim(),
+    };
+}
+// ─── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Generate a 3D model (GLB) from a text prompt or a source image via the
+ * Tripo API: submit a task, then poll until it finalizes or the bounded
+ * deadline expires.
+ *
+ * Reads `TRIPO_API_KEY` from the environment. All error paths return a
+ * `GenerateModelError` rather than throwing, so the MCP dispatcher can render
+ * a friendly message without wrapping the call in a try/catch.
+ */
+export async function generateModel(options) {
+    // ── Input validation (no network before this passes) ──────────────────────
+    const prompt = typeof options?.prompt === "string" ? options.prompt.trim() : undefined;
+    const imageUrl = typeof options?.imageUrl === "string" ? options.imageUrl.trim() : undefined;
+    const hasPrompt = prompt !== undefined && prompt.length > 0;
+    const hasImage = imageUrl !== undefined && imageUrl.length > 0;
+    if (!hasPrompt && !hasImage) {
+        return {
+            ok: false,
+            code: "invalid_input",
+            message: "Provide exactly one of `prompt` (text→3D) or `imageUrl` (image→3D). Both are currently empty.",
+        };
+    }
+    if (hasPrompt && hasImage) {
+        return {
+            ok: false,
+            code: "invalid_input",
+            message: "Provide exactly one of `prompt` or `imageUrl`, not both. Use `prompt` for text→3D or `imageUrl` for image→3D.",
+        };
+    }
+    if (hasPrompt && prompt.length > MAX_PROMPT_LENGTH) {
+        return {
+            ok: false,
+            code: "invalid_input",
+            message: `\`prompt\` is too long (${prompt.length} chars). Tripo accepts at most ${MAX_PROMPT_LENGTH} characters.`,
+        };
+    }
+    if (hasImage && !isHttpUrl(imageUrl)) {
+        return {
+            ok: false,
+            code: "invalid_input",
+            message: "`imageUrl` must be a public http(s) URL to a JPEG or PNG image (max 20 MB).",
+        };
+    }
+    const quality = options.quality === "hd" ? "hd" : "fast"; // default + unknown values → fast
+    const tier = QUALITY_TIERS[quality];
+    const apiKey = process.env.TRIPO_API_KEY;
+    if (!apiKey || apiKey.trim().length === 0) {
+        return missingKeyError();
+    }
+    const headers = {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+    };
+    // ── 1. Submit the generation task ──────────────────────────────────────────
+    const body = buildTaskBody({
+        prompt: hasPrompt ? prompt : undefined,
+        imageUrl: hasImage ? imageUrl : undefined,
+        quality,
+    });
+    let submitResponse;
+    try {
+        submitResponse = await fetch(TRIPO_TASK_ENDPOINT, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        const cause = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            code: "network",
+            message: `Could not reach Tripo (${cause}). Check your internet connection and try again.`,
+        };
+    }
+    if (!submitResponse.ok) {
+        return httpError(submitResponse.status, submitResponse.statusText);
+    }
+    let submitPayload;
+    try {
+        submitPayload = (await submitResponse.json());
+    }
+    catch (err) {
+        const cause = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            code: "bad_response",
+            message: `Tripo returned invalid JSON: ${cause}`,
+        };
+    }
+    if (typeof submitPayload.code === "number" && submitPayload.code !== 0) {
+        const detail = [submitPayload.message, submitPayload.suggestion].filter(Boolean).join(" — ");
+        return {
+            ok: false,
+            code: "bad_response",
+            message: `Tripo rejected the task (code ${submitPayload.code})${detail ? `: ${detail}` : "."}`,
+        };
+    }
+    const taskId = submitPayload.data?.task_id;
+    if (!taskId || typeof taskId !== "string") {
+        return {
+            ok: false,
+            code: "bad_response",
+            message: "Tripo accepted the request but returned no task_id.",
+        };
+    }
+    // ── 2. Poll until the task finalizes (bounded) ─────────────────────────────
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const timeoutMs = options.timeoutMs ?? tier.timeoutMs;
+    const deadline = Date.now() + timeoutMs;
+    let lastStatus = "queued";
+    let lastProgress = 0;
+    for (;;) {
+        let pollResponse;
+        try {
+            pollResponse = await fetch(`${TRIPO_TASK_ENDPOINT}/${taskId}`, { headers });
+        }
+        catch (err) {
+            const cause = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false,
+                code: "network",
+                message: `Lost connection to Tripo while polling task ${taskId} (${cause}). The generation may still complete — retry later or check https://platform.tripo3d.ai.`,
+            };
+        }
+        if (pollResponse.status === 401 || pollResponse.status === 403) {
+            return httpError(pollResponse.status, pollResponse.statusText);
+        }
+        // Transient poll hiccups (429 burst, 5xx, malformed JSON) are tolerated:
+        // keep polling until the bounded deadline instead of failing the task.
+        if (pollResponse.ok) {
+            let pollPayload;
+            try {
+                pollPayload = (await pollResponse.json());
+            }
+            catch {
+                pollPayload = undefined;
+            }
+            const task = pollPayload?.data;
+            const status = task?.status;
+            if (typeof status === "string") {
+                lastStatus = status;
+                if (typeof task?.progress === "number")
+                    lastProgress = task.progress;
+                if (status === "success") {
+                    const output = task?.output ?? {};
+                    const modelUrl = output.pbr_model || output.model || output.base_model || "";
+                    if (!modelUrl) {
+                        return {
+                            ok: false,
+                            code: "bad_response",
+                            message: `Tripo task ${taskId} succeeded but returned no model URL.`,
+                        };
+                    }
+                    return {
+                        ok: true,
+                        model: {
+                            taskId,
+                            modelUrl,
+                            previewImageUrl: output.rendered_image ?? "",
+                            quality,
+                            modelVersion: tier.modelVersion,
+                            mode: hasPrompt ? "text" : "image",
+                            input: hasPrompt ? prompt : imageUrl,
+                            creditsConsumed: typeof task?.consumed_credit === "number" ? task.consumed_credit : null,
+                            license: LICENSE_NOTE,
+                            attribution: ATTRIBUTION,
+                        },
+                    };
+                }
+                if (FAILED_STATUSES.has(status)) {
+                    return {
+                        ok: false,
+                        code: "task_failed",
+                        message: [
+                            `Tripo task ${taskId} finalized with status "${status}".`,
+                            status === "failed"
+                                ? "Try rephrasing the prompt (or a clearer source image) and generate again."
+                                : "Check the task on https://platform.tripo3d.ai for details.",
+                        ].join(" "),
+                    };
+                }
+                // queued / running → keep polling.
+            }
+        }
+        if (Date.now() >= deadline) {
+            return {
+                ok: false,
+                code: "timeout",
+                message: [
+                    `Tripo task ${taskId} did not finish within ${Math.round(timeoutMs / 1000)}s`,
+                    `(last status: "${lastStatus}", progress ${lastProgress}%).`,
+                    "The generation may still complete on Tripo's side — credits may be consumed.",
+                    "Retry, or check the task on https://platform.tripo3d.ai.",
+                ].join(" "),
+            };
+        }
+        await sleep(pollIntervalMs);
+    }
+}
+/**
+ * Render a `GenerateModelResult` as the markdown text block the MCP
+ * dispatcher returns to the client. Kept here (not in handler.ts) so unit
+ * tests can verify formatting without touching the dispatch layer.
+ */
+export function formatGenerateResult(result) {
+    if (!result.ok) {
+        return result.message;
+    }
+    const m = result.model;
+    const sourceLabel = m.mode === "text" ? "Prompt" : "Source image";
+    const lines = [
+        `## Generated 3D model (${QUALITY_TIERS[m.quality].label})`,
+        "",
+        `- **GLB download:** ${m.modelUrl}`,
+        `- **⚠️ URL expiry:** the download link expires ~5 minutes after generation — download the file NOW and self-host it (e.g. copy it into your app's \`assets/models/\`).`,
+        ...(m.previewImageUrl ? [`- **Preview:** ${m.previewImageUrl}`] : []),
+        `- **${sourceLabel}:** ${m.input}`,
+        `- **Model version:** ${m.modelVersion}`,
+        `- **Task ID:** \`${m.taskId}\``,
+        ...(m.creditsConsumed !== null ? [`- **Tripo credits consumed:** ${m.creditsConsumed}`] : []),
+        `- **License:** ${m.license}`,
+        `- **Generator:** ${m.attribution}`,
+        "",
+        "### Load it in SceneView",
+        "",
+        "```kotlin",
+        "// After downloading the GLB into your app's assets:",
+        'val model = rememberModelInstance(modelLoader, "models/generated.glb")',
+        "```",
+        "",
+        'Place it in AR with `AnchorNode` + `ModelNode` — see the llms.txt recipe "Generate a 3D model with AI (Tripo) and place it in AR".',
+    ];
+    return lines.join("\n");
+}