sceneview-mcp 4.0.5 → 4.0.7

package/README.md

@@ -4,56 +4,28 @@
 
 [![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-2360%20passing-brightgreen)](#quality)
+[![Tests](https://img.shields.io/badge/tests-2918%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)
 [![Node](https://img.shields.io/badge/Node-%3E%3D18-brightgreen)](https://nodejs.org/)
 
-The official [Model Context Protocol](https://modelcontextprotocol.io/) server for **[SceneView](https://sceneview.github.io)** -- the cross-platform 3D & AR SDK for Android (Jetpack Compose + Filament), iOS/macOS/visionOS (SwiftUI + RealityKit), and Web (Filament.js + WebXR).
+The official [Model Context Protocol](https://modelcontextprotocol.io/) server for **[SceneView](https://sceneview.github.io)** — the cross-platform 3D & AR SDK for Android (Jetpack Compose + Filament), iOS / macOS / visionOS (SwiftUI + RealityKit), and Web (Filament.js + WebXR).
 
-Connect it to Claude, Cursor, Windsurf, or any MCP client. The assistant gets 26 specialized tools, 33 compilable code samples, a full API reference, and a code validator -- so it writes correct, working 3D/AR code on the first try.
+Connect it to Claude, Cursor, Windsurf, or any MCP client. Your AI assistant gets specialized tools, compilable code samples, the full API reference, and a code validator — so it writes correct, working 3D/AR code on the first try.
 
 > **Disclaimer:** Generated code is provided "as is" without warranty. Always review before production use. See [TERMS.md](./TERMS.md) and [PRIVACY.md](./PRIVACY.md).
 
 ---
 
-## 🚀 Hosted-first mode (v4 beta)
+## Quick start
 
-Starting with **v4.0.0-beta.1**, `sceneview-mcp` is a **lite stdio package**: free tools run locally (no network round-trip) and Pro tools are transparently forwarded to the hosted gateway at **https://sceneview-mcp.mcp-tools-lab.workers.dev/mcp**.
-
-| What | Where |
-|---|---|
-| 17 free tools (samples, guides, validator, search, analyze) | Local, zero network |
-| 36+ Pro tools (AR, multi-platform, scene gen, artifacts, packages) | Forwarded to the gateway — Bearer auth + Stripe-metered |
-| Auth, metering, Stripe webhooks, API-key provisioning | Gateway (Cloudflare Workers + D1 + KV) |
-
-**Pricing** (subscribe at https://sceneview-mcp.mcp-tools-lab.workers.dev/pricing):
-
-| Plan | Price | Use case |
-|---|---|---|
-| Free | 0 € | Samples, guides, validator — no signup |
-| Pro | 19 €/mo or 190 €/yr | Individual devs, full Pro tool access |
-| Team | 49 €/mo or 490 €/yr | Teams with higher rate limits |
-
-After subscribing, you'll receive a `sv_live_…` API key. Set it via the `SCENEVIEW_API_KEY` env var in your MCP client config (see snippets below) to unlock Pro tools.
-
-⭐ [Sponsor on GitHub](https://github.com/sponsors/sceneview) — help keep the free tier free.
-
----
-
-## Quick start (free tier)
-
-**One command -- no install required:**
+**One command — no install required:**
 
 ```bash
 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.
-
-> **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):
@@ -100,36 +72,59 @@ Same JSON config as above. The server communicates via **stdio** using the stand
 
 ## What you get
 
-### 26 tools
+Every developer tool is **free**: setup guides for every platform, code samples, the API reference, the migration tooling, the validator, model search, and the project analyzer.
+
+### Free tools
+
+#### Setup & integration
+
+| Tool | What it does |
+|---|---|
+| `get_setup` | Gradle + manifest setup for Android 3D or AR |
+| `get_ios_setup` | SPM dependency, Info.plist, SwiftUI for iOS / macOS / visionOS |
+| `get_web_setup` | Kotlin/JS + Filament.js (WASM) for browser-based 3D |
+| `get_ar_setup` | Permissions, session options, plane detection, image tracking |
+| `get_platform_setup` | Unified setup guide for any platform (Android, iOS, Web, Flutter, RN, Desktop, TV) |
+
+#### Code generation & migration
 
 | Tool | What it does |
 |---|---|
 | `get_sample` | Returns a complete, compilable code sample for any of 33 scenarios (Kotlin or Swift) |
 | `list_samples` | Browse all samples, filter by tag (`ar`, `3d`, `ios`, `animation`, `geometry`, ...) |
 | `validate_code` | Checks generated code against 15+ rules before presenting it to the user |
-| `get_node_reference` | Full API reference for any of 35+ node types -- exact signatures, defaults, examples |
-| `list_platforms` | List all supported platforms with their status, renderer, and framework |
-| `get_setup` | Gradle + manifest setup for Android 3D or AR projects |
-| `get_ios_setup` | SPM dependency, Info.plist, and SwiftUI integration for iOS/macOS/visionOS |
-| `get_web_setup` | Kotlin/JS + Filament.js (WASM) setup for browser-based 3D |
-| `get_ar_setup` | Detailed AR config: permissions, session options, plane detection, image tracking |
-| `get_best_practices` | Performance, architecture, memory, and threading guidance |
-| `get_migration_guide` | Every breaking change from SceneView 2.x to 3.0 with before/after code |
-| `get_troubleshooting` | Common crashes, build failures, AR issues, and their fixes |
-| `get_platform_roadmap` | Multi-platform status and timeline (Android, iOS, KMP, Web, Desktop) |
-| `render_3d_preview` | Generates an interactive 3D preview link the user can open in their browser |
-| `create_3d_artifact` | Generates self-contained HTML artifacts (model viewer, 3D charts, product 360) |
-| `get_platform_setup` | Unified setup guide for any platform (Android, iOS, Web, Flutter, React Native, Desktop, TV) |
-| `migrate_code` | Automatically migrates SceneView 2.x code to 3.x with detailed changelog |
-| `debug_issue` | Targeted debugging guide by category or auto-detected from problem description |
-| `generate_scene` | Generates a complete composable from natural language (e.g., "a room with a table and two chairs") |
-| `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
+| `migrate_code` | Automatically migrates SceneView 2.x / 3.x code with detailed changelog |
+| `get_migration_guide` | Every breaking change with before/after code |
+
+#### API reference
+
+| Tool | What it does |
+|---|---|
+| `get_node_reference` | Full API reference for any of 35+ node types — exact signatures, defaults, examples |
+| `list_platforms` | Supported platforms with their status, renderer, and framework |
+| `get_platform_roadmap` | Multi-platform status and timeline |
+
+#### Guides
+
+`get_best_practices` · `get_animation_guide` · `get_gesture_guide` · `get_performance_tips` · `get_material_guide` · `get_collision_guide` · `get_model_optimization_guide` · `get_web_rendering_guide` · `get_troubleshooting` · `debug_issue`
+
+#### Discovery & analysis
+
+| Tool | What it does |
+|---|---|
+| `search_models` | Searches Sketchfab for free 3D models (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 |
+
+### 2 resources
+
+| Resource URI | What it provides |
+|---|---|
+| `sceneview://api` | Complete SceneView 4.0.x API reference (the full `llms.txt`) |
+| `sceneview://known-issues` | Live open issues from GitHub (cached 10 min) |
+
+---
+
+## `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.
 
@@ -153,7 +148,7 @@ 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.
 
-#### `analyze_project` — local project scan
+## `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:
 
@@ -164,13 +159,6 @@ Because the MCP server runs on the user's machine, `analyze_project` can read th
 
 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
-
-| Resource URI | What it provides |
-|---|---|
-| `sceneview://api` | Complete SceneView 4.0.0 API reference (the full `llms.txt`) |
-| `sceneview://known-issues` | Live open issues from GitHub (cached 10 min) |
-
 ---
 
 ## Examples
@@ -185,16 +173,12 @@ The assistant calls `get_ios_setup("3d")` + `get_sample("ios-model-viewer")` and
 
 ### "What parameters does LightNode accept?"
 
-The assistant calls `get_node_reference("LightNode")` and returns the exact function signature, parameter types, defaults, and a usage example -- including the critical detail that `apply` is a named parameter, not a trailing lambda.
+The assistant calls `get_node_reference("LightNode")` and returns the exact function signature, parameter types, defaults, and a usage example — including the critical detail that `apply` is a named parameter, not a trailing lambda.
 
 ### "Validate this code before I use it"
 
 The assistant calls `validate_code` with the generated snippet and checks it against 15+ rules: threading violations, null safety, API correctness, lifecycle issues, deprecated APIs. Problems are flagged with explanations before the code reaches the user.
 
-### "Show me the model in 3D"
-
-The assistant calls `render_3d_preview` and returns an interactive link to a browser-based 3D viewer with orbit controls and optional AR mode.
-
 ---
 
 ## Why this exists
@@ -208,7 +192,7 @@ The assistant calls `render_3d_preview` and returns an interactive link to a bro
 - Have no knowledge of SceneView's iOS/Swift API at all
 
 **With** this MCP server, AI assistants:
-- Always use the current SceneView 4.0.0 API surface
+- 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 35+ node types and their exact parameters
@@ -219,21 +203,20 @@ The assistant calls `render_3d_preview` and returns an interactive link to a bro
 
 ## Quality
 
-The MCP server is tested with **2360 unit tests** across 98 test suites covering:
+The MCP server is tested with **2,918 unit tests** across 132 test suites covering:
 
 - Every tool response (correct output, error handling, edge cases)
 - All 33 code samples (compilable structure, correct imports, no deprecated APIs)
 - Code validator rules (true positives and false-positive resistance)
-- Node reference parsing (all 26+ types extracted correctly from `llms.txt`)
+- Node reference parsing (all node types extracted correctly from `llms.txt`)
 - Resource responses (API reference, GitHub issues integration)
 
 ```
- Test Files  22 passed (22)
-      Tests  2360 passed (2360)
-   Duration  624ms
+ Test Files  132 passed (132)
+      Tests  2918 passed (2918)
 ```
 
-All tools work **fully offline** except `sceneview://known-issues` (GitHub API, cached 10 min).
+All tools work **fully offline** except `sceneview://known-issues` (GitHub API, cached 10 min) and `search_models` (Sketchfab, BYOK).
 
 ---
 
@@ -242,7 +225,7 @@ All tools work **fully offline** except `sceneview://known-issues` (GitHub API,
 ### "MCP server not found" or connection errors
 
 1. Ensure Node.js 18+ is installed: `node --version`
-2. Test manually: `npx sceneview-mcp` -- should start without errors
+2. Test manually: `npx sceneview-mcp` — should start without errors
 3. Restart your AI client after changing the MCP configuration
 
 ### "npx command not found"
@@ -251,13 +234,13 @@ Install Node.js from [nodejs.org](https://nodejs.org/) (LTS recommended). npm an
 
 ### Server starts but tools are not available
 
-- **Claude Desktop:** check the MCP icon in the input bar -- it should show "sceneview" as connected
+- **Claude Desktop:** check the MCP icon in the input bar — it should show "sceneview" as connected
 - **Cursor:** check **Settings > MCP** for green status
 - Restart the AI client to force a reconnect
 
 ### Firewall or proxy issues
 
-The only network call is to the GitHub API (for known issues). All other tools work offline. For corporate proxies:
+The only network calls are to the GitHub API (for known issues) and Sketchfab (when `SKETCHFAB_API_KEY` is set). Everything else works offline.
 
 ```json
 {
@@ -275,13 +258,40 @@ The only network call is to the GitHub API (for known issues). All other tools w
 
 ---
 
+## Optional: vertical packages
+
+A small set of domain-specific tools is gated behind an optional subscription. They aren't required for general 3D/AR work — only useful if you happen to be building one of these specific verticals:
+
+- **Automotive** — car configurator, paint shader, parts catalog, HUD overlay, AR showroom
+- **Gaming** — physics, particles, level editor, character viewer, inventory 3D
+- **Healthcare** — surgical planning, dental viewer, medical imaging, anatomy, molecule viewer
+- **Interior** — room planner, lighting design, material switcher, furniture placement, room tour
+
+Plus 3 generation helpers: `render_3d_preview`, `create_3d_artifact`, `generate_scene`.
+
+If you need any of these, see the [pricing page](https://sceneview-mcp.mcp-tools-lab.workers.dev/pricing). The base SDK and every developer tool listed above stay free, always.
+
+---
+
+## Sponsor
+
+If sceneview-mcp saves you time, consider [sponsoring on GitHub Sponsors](https://github.com/sponsors/sceneview). Building this is a one-dev labor of love and donations keep the free tier covered.
+
+---
+
+## Anonymous telemetry
+
+Enabled by default 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.
+
+---
+
 ## Development
 
 ```bash
 cd mcp
 npm install
 npm run prepare  # Copy llms.txt + build TypeScript
-npm test         # 2360 tests
+npm test         # 2918 tests
 npm run dev      # Start with tsx (hot reload)
 ```
 
@@ -290,16 +300,21 @@ npm run dev      # Start with tsx (hot reload)
 ```
 mcp/
   src/
-    index.ts          # MCP server entry point (26 tools, 2 resources)
-    samples.ts         # 33 compilable code samples (Kotlin + Swift)
-    validator.ts       # Code validator (15+ rules, Kotlin + Swift)
-    node-reference.ts  # Node type parser (extracts from llms.txt)
-    guides.ts          # Best practices, AR setup, roadmap, troubleshooting
-    migration.ts       # v2 -> v3 migration guide
-    preview.ts         # 3D preview URL generator
-    artifact.ts        # HTML artifact generator (model-viewer, charts, product 360)
-    issues.ts          # GitHub issues fetcher (cached)
-  llms.txt             # Bundled API reference (copied from repo root)
+    index.ts             # MCP server entry point
+    tools/handler.ts     # Tool dispatcher (free + pro)
+    tiers.ts             # Free vs Pro tier mapping
+    samples.ts           # 33 compilable code samples (Kotlin + Swift)
+    validator.ts         # Code validator (15+ rules)
+    node-reference.ts    # Node type parser
+    guides.ts            # Best practices, AR setup, roadmap, troubleshooting
+    migration.ts         # v2 -> v3 -> v4 migration guide
+    preview.ts           # 3D preview URL generator
+    artifact.ts          # HTML artifact generator (model-viewer, charts, product 360)
+    issues.ts            # GitHub issues fetcher (cached)
+    search-models.ts     # Sketchfab BYOK search
+    analyze-project.ts   # Local project scanner
+    proxy.ts             # Pro-tool proxy to hosted gateway
+  llms.txt               # Bundled API reference (copied from repo root)
 ```
 
 ## Contributing
@@ -307,13 +322,13 @@ mcp/
 1. Fork the repository
 2. Create a feature branch
 3. Add tests for new tools or rules
-4. Run `npm test` -- all 2360+ tests must pass
+4. Run `npm test` — all 2918+ tests must pass
 5. Submit a pull request
 
 See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full guide.
 
 ## Legal
 
-- [LICENSE](./LICENSE) -- MIT License
-- [TERMS.md](./TERMS.md) -- Terms of Service
-- [PRIVACY.md](./PRIVACY.md) -- Privacy Policy (no data collected)
+- [LICENSE](./LICENSE) — MIT License
+- [TERMS.md](./TERMS.md) — Terms of Service
+- [PRIVACY.md](./PRIVACY.md) — Privacy Policy

package/dist/index.js

@@ -37,7 +37,7 @@ function logStartupBanner() {
         `[sceneview-mcp] v${PACKAGE_VERSION} — ${mode}`,
         proxied
             ? `[sceneview-mcp] Pro tool calls will be forwarded to the hosted gateway.`
-            : `[sceneview-mcp] Set SCENEVIEW_API_KEY to unlock 36+ Pro tools — ${DEFAULT_PRICING_URL}`,
+            : `[sceneview-mcp] All setup, migration & docs tools are free. Pro packages (Automotive/Gaming/Healthcare/Interior) at ${DEFAULT_PRICING_URL}`,
     ];
     for (const line of lines)
         process.stderr.write(`${line}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sceneview-mcp",
-  "version": "4.0.5",
+  "version": "4.0.7",
   "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,8 @@
     "dist/**/*.js",
     "!dist/**/*.test.js",
     "!dist/**/__fixtures__/**",
-    "llms.txt"
+    "llms.txt",
+    "README.md"
   ],
   "engines": {
     "node": ">=18"