# sceneview-mcp

**Give any AI assistant expert-level knowledge of 3D and AR development.**

[![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-2015%20passing-brightgreen)](#quality)
[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-v1.29-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).

Connect it to Claude Code, Cline, Codex, Cursor, GitHub Copilot, JetBrains AI Assistant — or any other MCP client — locally over stdio, or remotely over Streamable HTTP at **`https://mcp.sceneview.dev/mcp`** (see [Remote server](#remote-server-streamable-http)). Your AI assistant gets specialized tools, compilable code samples, the full API reference, a code validator, and an inline 3D viewer widget — 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).

---

## Quick start

**One command — no install required:**

```bash
npx sceneview-mcp
```

Every client below runs that same server. Three config shapes exist across the ecosystem —
`mcpServers` (most clients), `servers` (VS Code) and `[mcp_servers.*]` (Codex TOML) — but the
command and arguments are identical in all three.

### Any MCP client

```json
{
  "mcpServers": {
    "sceneview": {
      "command": "npx",
      "args": ["-y", "sceneview-mcp"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add sceneview -- npx -y sceneview-mcp
```

Or commit `.mcp.json` at the repository root so the whole team gets it:

```json
{ "mcpServers": { "sceneview": { "type": "stdio", "command": "npx", "args": ["-y", "sceneview-mcp"] } } }
```

Optionally, the [SceneView Claude Code plugin](https://github.com/sceneview/claude-marketplace)
bundles this server with the three SceneView skills (Compose, SwiftUI, web), the same ones the
Codex plugin carries:

```bash
/plugin marketplace add sceneview/claude-marketplace
/plugin install sceneview@sceneview
```

### Claude Desktop

Settings → Developer → Edit Config, then add the standard `mcpServers` block above to
`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
`%APPDATA%\Claude\claude_desktop_config.json` (Windows). Restart after saving.

### Cline

MCP Servers icon → Configure → Configure MCP Servers, or `~/.cline/mcp.json`:

```json
{ "mcpServers": { "sceneview": { "command": "npx", "args": ["-y", "sceneview-mcp"], "disabled": false, "autoApprove": [] } } }
```

### Codex

```bash
codex mcp add sceneview -- npx -y sceneview-mcp
```

Or `~/.codex/config.toml` — TOML, and the table is `mcp_servers`, not `mcpServers`:

```toml
[mcp_servers.sceneview]
command = "npx"
args = ["-y", "sceneview-mcp"]
```

The same config serves the Codex CLI, the IDE extension and the app.

Optionally, the SceneView repository is itself a Codex plugin that bundles this server with the
three SceneView skills. From a checkout (the path must be absolute):

```bash
codex plugin marketplace add "$PWD"
codex plugin add sceneview@sceneview-local
```

### Cursor

Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global) — the standard
`mcpServers` block above. Cursor also accepts an install link:

```
cursor://anysphere.cursor-deeplink/mcp/install?name=sceneview&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNjZW5ldmlldy1tY3AiXX0=
```

### Gemini CLI

The repository root carries a [`gemini-extension.json`](../gemini-extension.json), so the CLI
installs the server straight from GitHub — no JSON to paste:

```bash
gemini extensions install https://github.com/sceneview/sceneview
```

**This clones the whole monorepo** — over 2 GB of history — because the CLI installs an
extension by cloning the repository that declares it, and SceneView's manifest sits in a
repository that also carries the Android, Apple, Web, Flutter and React Native sources. If you
want the server and not the clone, paste the standard `mcpServers` block into
`~/.gemini/settings.json` instead; it is the same command, `npx -y sceneview-mcp`, and it costs
a download of the npm package.

Either way, `npx` resolves `sceneview-mcp` to the **latest version published on npm**, which is
not necessarily the version this manifest declares — the manifest's `version` describes the
extension, and the server it launches updates on npm's cadence.

The extension declares nothing but the server: `npx -y sceneview-mcp` over stdio, no context
file and no tool exclusions, so it adds the SceneView tools to a session and changes nothing
else about it.

### Gemini in Android Studio

Android Studio's MCP integration **does not support stdio** — it connects over HTTP only, so
point it at the hosted endpoint. Settings → Tools → AI → MCP Servers:

```json
{ "mcpServers": { "sceneview": { "httpUrl": "https://mcp.sceneview.dev/mcp", "enabled": true } } }
```

### GitHub Copilot

In VS Code, `.vscode/mcp.json` — note the `servers` key, not `mcpServers`:

```json
{ "servers": { "sceneview": { "type": "stdio", "command": "npx", "args": ["-y", "sceneview-mcp"] } } }
```

VS Code also accepts an install link:

```
vscode:mcp/install?%7B%22name%22%3A%22sceneview%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22sceneview-mcp%22%5D%7D
```

In Copilot CLI:

```bash
copilot mcp add sceneview -- npx -y sceneview-mcp
```

### JetBrains AI Assistant / Junie

Settings → Tools → AI Assistant → Model Context Protocol (MCP) → Add, then paste the standard
`mcpServers` block above.

### MCP Bundle (`.mcpb`)

[`mcp/manifest.json`](manifest.json) describes this server in the [MCP Bundle
format](https://github.com/modelcontextprotocol/mcpb) (spec 0.3), for desktop apps that install
a local server from a bundle rather than a command line. It runs the built `dist/index.js` with
the host's Node — the host provides the runtime and **nothing else**, so the bundle has to carry
its own `node_modules`. Zipping this directory after `npm run build` alone produces a bundle
that fails at launch with `Cannot find package '@modelcontextprotocol/sdk'`:

```bash
npm ci                                # dev dependencies — the build needs them
npm run build                         # writes dist/
npm ci --omit=dev --ignore-scripts    # drop the dev tree, keep dist/
zip -r sceneview-mcp.mcpb manifest.json package.json dist node_modules
```

`--ignore-scripts` is not optional: this package's `prepare` script ends in `tsc`, and the same
command that omits the dev dependencies omits TypeScript, so without it npm runs `prepare`,
fails to find `tsc` and exits 127. Reinstall with a plain `npm ci` afterwards to get the dev
tree back.

The manifest is not published as a `.mcpb` artefact by CI: it is the descriptor, and packing it
stays a manual step for whoever needs a bundle. `mcp/src/packaging.test.ts` keeps its name,
version, licence, entry point and Node range equal to `package.json`'s — and does the same for
[`server.json`](server.json) and the root `gemini-extension.json` — because nothing else would
notice them drifting.

### Use as a remote connector

No install, nothing to run: SceneView is hosted as a remote MCP server at

```
https://mcp.sceneview.dev/mcp
```

Any client that accepts a Streamable HTTP MCP URL can use it. In claude.ai, that is
**Settings → Connectors → Add custom connector**.

**Authless and read-only.** There is no sign-in, no API key and no account: every tool is a pure
function of the SDK's own documentation, samples and API surface, so there is nothing to
authenticate and nothing of yours stored. All tools are annotated `readOnlyHint` except
`generate_3d_model`, which calls an external generation service and is therefore marked
open-world rather than read-only.

**Prefer it local?** `npx -y sceneview-mcp` runs the exact same server over stdio. The local
route is the one that reads your project from disk (`analyze_project`) and the one that accepts
your own `SKETCHFAB_API_KEY` / `TRIPO_API_KEY`; the hosted connector, being shared and anonymous,
cannot.

### Remote server (Streamable HTTP)

Some hosts cannot spawn a local process: they need MCP's **Streamable HTTP** transport at a public URL. The same package serves it:

```bash
npx sceneview-mcp --http
# [sceneview-mcp] v4.x — HTTP (remote tool surface)
# [sceneview-mcp] MCP endpoint: http://127.0.0.1:3333/mcp
```

| Route | What it does |
|---|---|
| `POST /mcp` | MCP JSON-RPC (Streamable HTTP, stateless — no sessions, safe behind any load balancer) |
| `GET` / `DELETE /mcp` | `405` (no standalone SSE stream, no session to delete) |
| `GET /health` | `{"status":"ok","version":"4.x.y"}` |
| `GET /.well-known/openai-apps-challenge` | OpenAI domain verification — returns `OPENAI_APPS_CHALLENGE_TOKEN` as `text/plain`, `404` when unset |
| anything else | `404` |

Configuration: `PORT` (default `3333`), `HOST` (default `127.0.0.1` — set `HOST=0.0.0.0` to expose it, and put HTTPS in front), `OPENAI_APPS_CHALLENGE_TOKEN` (the value OpenAI gives you when you submit the domain). CORS allows any origin. The usual `SKETCHFAB_API_KEY` / `TRIPO_API_KEY` / `SCENEVIEW_TELEMETRY=0` knobs apply.

**Everything is free, but not everything is remote.** Three generation tools (`render_3d_preview`, `create_3d_artifact`, `generate_scene`) need your own third-party credentials, which a shared anonymous endpoint cannot hold, so the remote surface omits them and refuses those names at call time with a clear `isError` message pointing at the local `npx sceneview-mcp` path. stdio lists and runs all 32.

**Inline 3D viewer.** `view_3d_model` returns `structuredContent` plus `_meta.ui.resourceUri = ui://widget/3d-viewer.html`; the widget (SceneView.js + Filament.js, served by `resources/read` with the `text/html;profile=mcp-app` mime type and its `_meta.ui.csp`) renders the model inline in ChatGPT and any MCP Apps host.

Smoke test with curl (the `Accept` header is required by the spec):

```bash
curl -s http://127.0.0.1:3333/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
# {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25","capabilities":{"resources":{},"tools":{}},"serverInfo":{"name":"sceneview-mcp","version":"4.x.y"}}}
```

Point the ChatGPT connector / OpenAI `mcp` tool at `https://<your-host>/mcp`.

**Already hosted.** You do not have to run it yourself to get a public URL: the same code is
deployed at `https://mcp.sceneview.dev/mcp` (`GET /health` answers `{"status":"ok"}`), which is
what the [remote connector](#use-as-a-remote-connector) above points at. Self-host when you want
your own keys, your own rate limits, or `analyze_project` against a local checkout.

---

## What you get

Every tool is free and there is no API key. The three generation tools that talk to a
third-party service use *your* credentials; everything else works the moment the server starts.

### Start here

Six tools carry most of what assistants actually do with SceneView. If you read nothing else:

| Tool | What it does | Ask your assistant |
|---|---|---|
| `validate_code` | Compile-checks generated Kotlin or Swift against the real public API — symbol existence, 30+ rules, did-you-mean suggestions — before it reaches you | *"Check that this SceneView code actually compiles"* |
| `get_node_reference` | The exact signature, defaults and example for any of 48+ node types, instead of an invented one | *"What are the parameters of ModelNode?"* |
| `list_samples` | Browse 38 scenarios by tag (`ar`, `3d`, `ios`, `animation`, `geometry`, …) | *"What SceneView samples involve AR planes?"* |
| `get_sample` | Returns one of them complete and compilable, in Kotlin or Swift | *"Give me the AR plane-placement sample in Kotlin"* |
| `get_setup` | Gradle and manifest setup for Android 3D or AR | *"Set up SceneView in my Android app"* |
| `get_ar_setup` | Permissions, session options, plane detection, image tracking | *"Add ARCore plane detection to this screen"* |

### Full tool reference

#### 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 38 scenarios (Kotlin or Swift) |
| `list_samples` | Browse all samples, filter by tag (`ar`, `3d`, `ios`, `animation`, `geometry`, ...) |
| `validate_code` | Checks generated code against 30+ rules — including symbol existence against the real public API, with did-you-mean suggestions — before presenting it to the user |
| `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 48+ 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`) |
| `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) |

#### Inline 3D viewer (MCP Apps widget)

| Tool | What it does |
|---|---|
| `view_3d_model` | Renders a public GLB / glTF URL in an interactive SceneView.js + Filament.js viewer inline in ChatGPT and any MCP Apps host (orbit, auto-rotate). For an https model it adds an "Open in AR on your phone" action (an `ar.sceneview.dev/open` link to the 3D AR Model Viewer app, with a QR code on desktop). Returns `structuredContent` + `_meta.ui.resourceUri` |

### 5 resources

| Resource URI | What it provides |
|---|---|
| `sceneview://api` | Complete SceneView 4.x API reference (the full `llms.txt`) |
| `sceneview://known-issues` | Live open issues from GitHub (cached 10 min) |
| `examples://demo-with-settings` | DemoScaffold v2 pattern — full-screen scene + Material 3 bottom sheet |
| `examples://sketchfab-streaming` | Streaming Sketchfab CC-BY models into a demo instead of bundling GLBs |
| `ui://widget/3d-viewer.html` | The 3D viewer widget (`text/html;profile=mcp-app`) that `view_3d_model` renders into |

---

## `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.

## `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:

- 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.

---

## Examples

### "Build me an AR app"

The assistant calls `get_ar_setup` + `get_sample("ar-model-viewer")` and returns a complete, compilable Kotlin composable with all imports, Gradle dependencies, and manifest entries. Ready to paste into Android Studio.

### "Create a 3D model viewer for iOS"

The assistant calls `get_ios_setup("3d")` + `get_sample("ios-model-viewer")` and returns Swift code with the SPM dependency, Info.plist entries, and a working SwiftUI view.

### "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.

### "Validate this code before I use it"

The assistant calls `validate_code` with the generated snippet and checks it against 30+ rules: symbol existence against the real public API (unknown imports, made-up node types, nonexistent loader methods — each with did-you-mean suggestions), threading violations, null safety, API correctness, lifecycle issues, deprecated APIs. Problems are flagged with explanations before the code reaches the user.

---

## Why this exists

**Without** this MCP server, AI assistants regularly:
- Recommend deprecated **Sceneform** (abandoned 2021) instead of SceneView
- Generate imperative **View-based** code instead of Jetpack Compose
- Use **wrong API signatures** or outdated parameter names
- Miss the `LightNode` named-parameter gotcha (`apply =` not trailing lambda)
- Forget null-checks on `rememberModelInstance` (it returns `null` while loading)
- Have no knowledge of SceneView's iOS/Swift API at all

**With** this MCP server, AI assistants:
- Always use the current SceneView 4.x API surface
- Generate correct **Compose-native** 3D/AR code for Android
- Generate correct **SwiftUI-native** code for iOS/macOS/visionOS
- Know about all 48+ node types and their exact parameters
- Validate code against 30+ rules before presenting it
- Provide working, tested sample code for 38 scenarios

---

## Quality

The MCP server is tested with **2,015 unit tests** across 91 test files covering:

- Every tool response (correct output, error handling, edge cases)
- All 38 code samples (compilable structure, correct imports, no deprecated APIs)
- Code validator rules (true positives and false-positive resistance)
- Node reference parsing (all node types extracted correctly from `llms.txt`)
- Resource responses (API reference, GitHub issues integration, the 3D viewer widget)
- The Streamable HTTP surface end to end (initialize, the remote tools/list, widget resource, health, OpenAI challenge)

```
 Test Files  91 passed (91)
      Tests  2015 passed (2015)
```

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). Anonymous telemetry also makes a network call unless `SCENEVIEW_TELEMETRY=0` (see [below](#anonymous-telemetry)).

---

## Troubleshooting

### "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
3. Restart your AI client after changing the MCP configuration

### "npx command not found"

Install Node.js from [nodejs.org](https://nodejs.org/) (LTS recommended). npm and npx are included.

### Server starts but tools are not available

- **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 calls are to the GitHub API (for known issues), Sketchfab (when `SKETCHFAB_API_KEY` is set), Tripo AI (when `TRIPO_API_KEY` is set and `generate_3d_model` is called), and the anonymous telemetry endpoint (off with `SCENEVIEW_TELEMETRY=0`). Everything else works offline.

```json
{
  "mcpServers": {
    "sceneview": {
      "command": "npx",
      "args": ["-y", "sceneview-mcp"],
      "env": {
        "HTTPS_PROXY": "http://proxy.example.com:8080"
      }
    }
  }
}
```

---

## Sponsor

If sceneview-mcp saves you time, consider [donating on Open Collective](https://opencollective.com/sceneview), or [GitHub Sponsors](https://github.com/sponsors/sceneview) if you prefer. SceneView is free and open source, funded by the people and companies who use it; every tool is free with or without a donation.

---

## Anonymous telemetry

Enabled by default (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) for the full payload shape.

---

## Development

```bash
cd mcp
npm install
npm run prepare  # Copy llms.txt + build TypeScript
npm test         # vitest suite
npm run lint     # Biome (repo-root biome.json) — lint + format + import assists
npm run lint:fix # same, applying the safe fixes
npm run dev      # Start with tsx (hot reload)
```

### Project structure

```
mcp/
  src/
    index.ts             # CLI entry point — stdio, or Streamable HTTP with --http
    server.ts            # The MCP Server (resources + tools), shared by both transports
    http.ts              # Streamable HTTP entrypoint (/mcp, /health, OpenAI challenge)
    widgets.ts           # MCP Apps widget: ui://widget/3d-viewer.html (SceneView.js + Filament.js)
    tools/handler.ts     # Tool dispatcher
    surfaces.ts          # Which tools the anonymous remote surface serves
    samples.ts           # 38 compilable code samples (Kotlin + Swift)
    validator.ts         # Code validator (30+ 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
    generate-model.ts    # Tripo BYOK text/image -> GLB generation
    analyze-project.ts   # Local project scanner
  llms.txt               # Bundled API reference (copied from repo root)
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new tools or rules
4. Run `npm test` — all 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