sceneview-mcp 4.0.2 → 4.0.3

package/README.md

@@ -44,9 +44,7 @@ After subscribing, you'll receive a `sv_live_…` API key. Set it via the `SCENE
 
 ## Quick start (free tier)
 
-You have two ways to use SceneView MCP — pick whichever fits your client:
-
-### Option A — stdio via `npx` (Claude Desktop, Claude Code, Cursor, Windsurf)
+**One command -- no install required:**
 
 ```bash
 npx sceneview-mcp
@@ -54,26 +52,6 @@ npx sceneview-mcp
 
 On startup you'll see a `[sceneview-mcp] v4.0.1 — LITE (free tools only)` banner on stderr. Set `SCENEVIEW_API_KEY` to flip into `HOSTED` mode.
 
-### Option B — hosted HTTP MCP URL (ChatGPT, Claude Desktop "Remote MCP", Cursor URL, anything HTTP)
-
-No install, no `npx`, no config files — just point your client at:
-
-```
-https://sceneview-mcp.mcp-tools-lab.workers.dev/mcp/public
-```
-
-- Anonymous, no API key required
-- 26 free tools fully accessible
-- 35 Pro tools return a `/pricing` upgrade prompt
-- Rate limit: 60 requests / hour per IP
-
-For **Pro tier with a Bearer token** (full quota, all 35 Pro tools):
-
-```
-https://sceneview-mcp.mcp-tools-lab.workers.dev/mcp
-Authorization: Bearer sv_live_...
-```
-
 > **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

package/dist/index.js

@@ -27,7 +27,7 @@ import { API_DOCS, TOOL_DEFINITIONS, dispatchTool, } from "./tools/index.js";
 // Claude Desktop surfaces this in the server's "Logs" panel. The banner
 // tells the user which mode they're in (hosted vs free) and where to
 // upgrade, without blocking the transport handshake.
-const PACKAGE_VERSION = "4.0.2";
+const PACKAGE_VERSION = "4.0.0";
 function logStartupBanner() {
     if (process.env.SCENEVIEW_MCP_QUIET === "1")
         return;

package/dist/tiers.js

@@ -4,6 +4,7 @@
 // ─── Free tools (17) ─────────────────────────────────────────────────────────
 const FREE_TOOLS = [
     "get_started",
+    "view_3d_model",
     "list_samples",
     "get_sample",
     "get_setup",

package/dist/tools/definitions.js

@@ -11,33 +11,6 @@ import { SAMPLE_IDS, SAMPLES } from "../samples.js";
 import { PLATFORM_IDS } from "../platform-setup.js";
 import { DEBUG_CATEGORIES } from "../debug-issue.js";
 export const TOOL_DEFINITIONS = [
-    {
-        // Activation tool — designed to be called immediately after init by the
-        // host AI. Intentionally listed FIRST so it's the first tool the model
-        // notices when scanning the MCP server's tool list. Returns a short
-        // overview + 3 concrete prompt suggestions the user can run, plus the
-        // canonical install snippet for whichever platform they target.
-        //
-        // Empirical motivation: 30-day telemetry shows ~55% of MCP inits never
-        // produce a tool call. Most of those clients (cursor-vscode, codex,
-        // claude-desktop, claude.ai) install but never trigger anything because
-        // the existing tool descriptions are passive lookups ("Returns ..."), not
-        // actions. This tool gives the host AI a clear hook to surface SceneView
-        // capabilities right after install.
-        name: "get_started",
-        description: "Run this FIRST when SceneView MCP is freshly installed, or whenever the user asks 'what can SceneView do', 'how do I start with SceneView', 'show me an AR example', or any open-ended SceneView question. Returns a one-page overview with 3 concrete prompts the user can try immediately, the install snippet for their platform, and links to the playground. Always call this before any other SceneView tool when the conversation has no prior SceneView context.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                platform: {
-                    type: "string",
-                    enum: ["android", "ios", "web", "any"],
-                    description: 'Target platform — "android" (Jetpack Compose + Filament), "ios" (SwiftUI + RealityKit), "web" (Filament.js + WebXR), or "any" for an unopinionated overview. Defaults to "any" if unsure.',
-                },
-            },
-            required: [],
-        },
-    },
     {
         name: "get_sample",
         description: "Returns a complete, compilable Kotlin sample for a given SceneView scenario. Use this to get a working starting point before customising. Call `list_samples` first if you are unsure which scenario fits.",
@@ -52,6 +25,11 @@ export const TOOL_DEFINITIONS = [
             },
             required: ["scenario"],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "list_samples",
@@ -66,6 +44,11 @@ export const TOOL_DEFINITIONS = [
             },
             required: [],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "get_setup",
@@ -81,6 +64,11 @@ export const TOOL_DEFINITIONS = [
             },
             required: ["type"],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "validate_code",
@@ -95,6 +83,11 @@ export const TOOL_DEFINITIONS = [
             },
             required: ["code"],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "get_migration_guide",
@@ -104,6 +97,11 @@ export const TOOL_DEFINITIONS = [
             properties: {},
             required: [],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "get_node_reference",
@@ -118,6 +116,11 @@ export const TOOL_DEFINITIONS = [
             },
             required: ["nodeType"],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "get_platform_roadmap",
@@ -127,6 +130,11 @@ export const TOOL_DEFINITIONS = [
             properties: {},
             required: [],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "get_best_practices",
@@ -142,6 +150,11 @@ export const TOOL_DEFINITIONS = [
             },
             required: [],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "get_ar_setup",
@@ -151,6 +164,11 @@ export const TOOL_DEFINITIONS = [
             properties: {},
             required: [],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "get_troubleshooting",
@@ -160,6 +178,11 @@ export const TOOL_DEFINITIONS = [
             properties: {},
             required: [],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "get_ios_setup",
@@ -175,6 +198,11 @@ export const TOOL_DEFINITIONS = [
             },
             required: ["type"],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "get_web_setup",
@@ -183,6 +211,11 @@ export const TOOL_DEFINITIONS = [
             type: "object",
             properties: {},
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "render_3d_preview",
@@ -213,6 +246,11 @@ export const TOOL_DEFINITIONS = [
             },
             required: [],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "create_3d_artifact",
@@ -311,6 +349,11 @@ export const TOOL_DEFINITIONS = [
             },
             required: ["type"],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "get_platform_setup",
@@ -331,6 +374,11 @@ export const TOOL_DEFINITIONS = [
             },
             required: ["platform", "type"],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "migrate_code",
@@ -345,6 +393,11 @@ export const TOOL_DEFINITIONS = [
             },
             required: ["code"],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "debug_issue",
@@ -364,6 +417,11 @@ export const TOOL_DEFINITIONS = [
             },
             required: [],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "generate_scene",
@@ -378,6 +436,11 @@ export const TOOL_DEFINITIONS = [
             },
             required: ["description"],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "list_platforms",
@@ -387,6 +450,11 @@ export const TOOL_DEFINITIONS = [
             properties: {},
             required: [],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "get_animation_guide",
@@ -396,6 +464,11 @@ export const TOOL_DEFINITIONS = [
             properties: {},
             required: [],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "get_gesture_guide",
@@ -405,6 +478,11 @@ export const TOOL_DEFINITIONS = [
             properties: {},
             required: [],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "get_performance_tips",
@@ -414,6 +492,11 @@ export const TOOL_DEFINITIONS = [
             properties: {},
             required: [],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "get_material_guide",
@@ -423,6 +506,11 @@ export const TOOL_DEFINITIONS = [
             properties: {},
             required: [],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "get_collision_guide",
@@ -432,6 +520,11 @@ export const TOOL_DEFINITIONS = [
             properties: {},
             required: [],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "get_model_optimization_guide",
@@ -441,6 +534,11 @@ export const TOOL_DEFINITIONS = [
             properties: {},
             required: [],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "get_web_rendering_guide",
@@ -450,6 +548,11 @@ export const TOOL_DEFINITIONS = [
             properties: {},
             required: [],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            destructiveHint: false,
+        },
     },
     {
         name: "search_models",
@@ -476,6 +579,11 @@ export const TOOL_DEFINITIONS = [
             },
             required: ["query"],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true,
+            destructiveHint: false,
+        },
     },
     {
         name: "analyze_project",
@@ -490,5 +598,10 @@ export const TOOL_DEFINITIONS = [
             },
             required: [],
         },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true,
+            destructiveHint: false,
+        },
     },
 ];

package/dist/tools/handler.js

@@ -37,67 +37,30 @@ import { analyzeProject, formatAnalysisReport } from "../analyze-project.js";
 import { LLMS_TXT } from "../generated/llms-txt.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).*";
-// ─── Tiered Pro CTA ─────────────────────────────────────────────────────────
+// ─── Sponsor CTA (shown every N tool calls, opt-out via env var) ────────────
 //
-// Empirical motivation (30-day telemetry, April 2026):
-// - 0 paying customers despite 140 inits / 77 tool calls
-// - The previous CTA (every 10 calls, dual sponsor + upgrade link) was seen
-//   ~2× by the heaviest user and 0× by everyone else (most users never hit
-//   10 calls). The dual link also split attention: a free sponsor link
-//   always wins against a paid upgrade link.
-//
-// New strategy:
-// - Fire EARLIER (call #3 — first nudge) so users actually see the pitch
-// - Single CTA (no sponsor competition) pointing to /pricing
-// - Tiered wording: tease → ask → final push, each more specific than the last
-// - Same opt-out env var (`SCENEVIEW_SPONSOR_CTA=0`) for backwards compat,
-//   plus a new `SCENEVIEW_CTA=0` alias for clarity going forward
-//
-// The counter is module-scoped (per MCP process lifetime), not persisted.
-const PRICING_URL = "https://sceneview-mcp.mcp-tools-lab.workers.dev/pricing";
-const CTA_STAGES = [
-    {
-        at: 3,
-        message: `\n\n💎 *Tip: SceneView Pro unlocks \`generate_scene\` — describe an AR app in plain English, get working Kotlin/Swift in one shot. [Try it free for 7 days](${PRICING_URL}).*`,
-    },
-    {
-        at: 10,
-        message: `\n\n🚀 *You've used 10 free SceneView tools. Ready to GENERATE a full AR app in one call? Pro unlocks 35+ tools (scene gen, multi-platform, vertical packages) for €19/mo — [start your free trial](${PRICING_URL}).*`,
-    },
-    {
-        at: 25,
-        message: `\n\n⭐ *Heavy SceneView user — save €38 / year with the annual plan (€190/yr instead of €19×12). [Lock it in](${PRICING_URL}).*`,
-    },
-];
-/** After all explicit stages, recurring nudge cadence (call #25, #35, #45…). */
-const POST_STAGE_INTERVAL = 10;
+// Non-intrusive monetization: append a one-line sponsor call-to-action after
+// every `SPONSOR_CTA_INTERVAL` tool calls. Disabled by setting
+// `SCENEVIEW_SPONSOR_CTA=0`. The counter is module-scoped (per MCP process
+// lifetime), not persisted.
+const SPONSOR_CTA_INTERVAL = 10;
+const SPONSOR_CTA = "\n\n💙 *Building SceneView is a one-dev labor of love. If this tool saved you time, consider [sponsoring on GitHub](https://github.com/sponsors/sceneview) or [upgrading to Pro](https://sceneview-mcp.mcp-tools-lab.workers.dev/pricing) for unlimited access.*";
 let toolCallCount = 0;
 /** Test-only: reset the module-scoped counter between test cases. */
 export function __resetSponsorCounter() {
     toolCallCount = 0;
 }
-/** Returns the CTA suffix to append on this call, or `""` if none. */
-function nextCtaSuffix() {
-    // Two opt-out env vars: keep the legacy name for backwards compatibility.
-    if (process.env.SCENEVIEW_SPONSOR_CTA === "0" ||
-        process.env.SCENEVIEW_CTA === "0") {
-        return "";
-    }
+function shouldShowSponsorCta() {
+    if (process.env.SCENEVIEW_SPONSOR_CTA === "0")
+        return false;
     toolCallCount += 1;
-    const stage = CTA_STAGES.find((s) => s.at === toolCallCount);
-    if (stage)
-        return stage.message;
-    const last = CTA_STAGES[CTA_STAGES.length - 1];
-    if (toolCallCount > last.at && (toolCallCount - last.at) % POST_STAGE_INTERVAL === 0) {
-        return last.message;
-    }
-    return "";
+    return toolCallCount % SPONSOR_CTA_INTERVAL === 0;
 }
 function withDisclaimer(content) {
     if (content.length === 0)
         return content;
     const last = content[content.length - 1];
-    const suffix = DISCLAIMER + nextCtaSuffix();
+    const suffix = DISCLAIMER + (shouldShowSponsorCta() ? SPONSOR_CTA : "");
     return [
         ...content.slice(0, -1),
         { ...last, text: last.text + suffix },
@@ -128,55 +91,6 @@ const NODE_SECTIONS = parseNodeSections(API_DOCS);
  */
 export async function dispatchTool(toolName, args, _ctx = {}) {
     switch (toolName) {
-        // ── get_started ───────────────────────────────────────────────────────────
-        // Activation entry point — see definition in `definitions.ts` for context.
-        // Pure markdown response, no I/O, deliberately concise so the host AI can
-        // forward the bullets straight into chat without summarising.
-        case "get_started": {
-            const platformArg = args?.platform ?? "any";
-            const platform = platformArg === "android" || platformArg === "ios" || platformArg === "web"
-                ? platformArg
-                : "any";
-            const installSnippets = {
-                android: "**Android (Jetpack Compose + Filament):**\n```kotlin\n// app/build.gradle.kts\nimplementation(\"io.github.sceneview:sceneview:4.0.1\")     // 3D only\nimplementation(\"io.github.sceneview:arsceneview:4.0.1\")   // AR\n```",
-                ios: "**iOS / macOS / visionOS (SwiftUI + RealityKit):**\n```swift\n// Package.swift\n.package(url: \"https://github.com/sceneview/SceneViewSwift\", from: \"4.0.1\")\n```",
-                web: "**Web (Filament.js + WebXR):**\n```bash\nnpm install sceneview-web@4.0.1\n```",
-                any: "**Pick your platform** (call `get_started` again with `platform`):\n- `android` — Jetpack Compose + Filament\n- `ios` — SwiftUI + RealityKit (iOS / macOS / visionOS)\n- `web` — Filament.js + WebXR",
-            };
-            const promptIdeas = [
-                "💬 *\"Show me a working AR sample I can run today.\"* → I'll call `get_sample` with an AR scenario.",
-                "💬 *\"Generate a 3D scene with a rotating model and ambient light.\"* → triggers `generate_scene` (Pro).",
-                "💬 *\"Validate this Kotlin SceneView snippet.\"* → triggers `validate_code`.",
-            ];
-            const text = [
-                "# 🎬 SceneView MCP — quick start",
-                "",
-                "**SceneView** = native 3D & AR for **Android** (Compose + Filament), **iOS / macOS / visionOS** (SwiftUI + RealityKit) and **Web** (Filament.js + WebXR).",
-                "",
-                "## Try one of these prompts now",
-                ...promptIdeas.map((p) => `- ${p}`),
-                "",
-                "## Install snippet",
-                installSnippets[platform],
-                "",
-                "## Useful next tools",
-                "- `list_samples` — see all 33 ready-to-paste examples",
-                "- `get_node_reference` — full API for a specific composable / node",
-                "- `validate_code` — catch threading / API mistakes before you ship",
-                "- `analyze_project` — inspect an existing project for SceneView readiness",
-                "",
-                "## Pro tools (€19/mo · [free trial](https://sceneview-mcp.mcp-tools-lab.workers.dev/pricing))",
-                "Unlocks `generate_scene`, `create_3d_artifact`, `render_3d_preview`, multi-platform setup, and the four vertical packages (Automotive · Gaming · Healthcare · Interior).",
-                "",
-                "## Resources",
-                "- 🌐 Playground: <https://sceneview.github.io>",
-                "- 📚 Full API: read the `sceneview://api` MCP resource",
-                "- 🐛 Issues: <https://github.com/sceneview/sceneview/issues>",
-            ].join("\n");
-            return {
-                content: [{ type: "text", text }],
-            };
-        }
         // ── get_sample ────────────────────────────────────────────────────────────
         case "get_sample": {
             const scenario = args?.scenario;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sceneview-mcp",
-  "version": "4.0.2",
+  "version": "4.0.3",
   "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,7 +64,7 @@
     "@types/node": "^25.5.0",
     "tsx": "^4.0.0",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.5"
   },
   "overrides": {
     "picomatch": ">=4.0.4"