Skip to content

Commit f0342c6

Browse files
claudeclaude
committed
feat: enhance MCP server, README, and AI discoverability
- Enhanced MCP README with installation guides for Claude, Cursor, Windsurf - Added get_best_practices and get_ar_setup tools to MCP server - Expanded package.json keywords for npm discoverability - Enhanced README with better getting started guide - Improved llms.txt in MCP package https://claude.ai/code/session_01Jf51Xrp1Fs4ByDmchZfGQ5
1 parent 6d6cdd4 commit f0342c6

10 files changed

Lines changed: 1332 additions & 308 deletions

File tree

‎README.md‎

Lines changed: 273 additions & 281 deletions
Large diffs are not rendered by default.

‎mcp/README.md‎

Lines changed: 190 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,110 @@
11
# sceneview-mcp — SceneView MCP Server
22

33
[![npm version](https://img.shields.io/npm/v/sceneview-mcp?color=6c35aa)](https://www.npmjs.com/package/sceneview-mcp)
4+
[![npm downloads](https://img.shields.io/npm/dm/sceneview-mcp?color=blue)](https://www.npmjs.com/package/sceneview-mcp)
45
[![MCP](https://img.shields.io/badge/MCP-v1.12-blue)](https://modelcontextprotocol.io/)
56
[![License](https://img.shields.io/badge/License-Apache%202.0-green)](https://www.apache.org/licenses/LICENSE-2.0)
7+
[![Node](https://img.shields.io/badge/Node-%3E%3D18-brightgreen)](https://nodejs.org/)
68

79
The official [Model Context Protocol](https://modelcontextprotocol.io/) server for **SceneView** — giving AI assistants deep knowledge of the SceneView 3D/AR SDK so they generate correct, compilable Kotlin code.
810

11+
---
12+
913
## What It Does
1014

11-
When connected to an AI assistant (Claude, GPT, Cursor, Windsurf, etc.), this MCP server provides:
15+
When connected to an AI assistant (Claude, Cursor, Windsurf, etc.), this MCP server provides **10 tools** and **2 resources** that give the assistant expert-level knowledge of the SceneView SDK:
16+
17+
### Tools
1218

1319
| Tool | Description |
1420
|------|-------------|
15-
| `get_node_reference` | Complete API reference for any SceneView node type |
21+
| `get_node_reference` | Complete API reference for any SceneView node type (22+ types) |
1622
| `list_node_types` | List all available node composables |
17-
| `validate_code` | Check SceneView code for 15+ common mistakes |
18-
| `get_sample` | Get complete, compilable sample code for any scenario |
19-
| `list_samples` | Browse 15 sample applications by tag |
20-
| `get_setup` | Get Gradle + manifest setup for 3D or AR |
21-
| `get_migration_guide` | Full v2→v3 migration instructions |
23+
| `validate_code` | Check SceneView code for 15+ common mistakes before presenting it |
24+
| `get_sample` | Get complete, compilable sample code for any of 14 scenarios |
25+
| `list_samples` | Browse all sample applications, optionally filtered by tag |
26+
| `get_setup` | Gradle + manifest setup for 3D or AR projects |
27+
| `get_migration_guide` | Full SceneView 2.x to 3.0 migration instructions |
28+
| `get_platform_roadmap` | Multi-platform roadmap (Android, iOS, KMP, Web) |
29+
| `get_best_practices` | Performance, architecture, memory, and threading best practices |
30+
| `get_ar_setup` | Detailed AR setup: manifest, permissions, session config, patterns |
31+
32+
### Resources
2233

23-
**Resources:**
2434
| Resource | Description |
2535
|----------|-------------|
26-
| `sceneview://api` | Complete SceneView 3.2.0 API reference |
27-
| `sceneview://known-issues` | Live open issues from GitHub (cached 10min) |
36+
| `sceneview://api` | Complete SceneView 3.2.0 API reference (llms.txt) |
37+
| `sceneview://known-issues` | Live open issues from GitHub (cached 10 min) |
38+
39+
---
40+
41+
## Installation
42+
43+
### Claude Desktop
44+
45+
Add to your Claude Desktop configuration file:
46+
47+
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
48+
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
49+
50+
```json
51+
{
52+
"mcpServers": {
53+
"sceneview": {
54+
"command": "npx",
55+
"args": ["-y", "sceneview-mcp"]
56+
}
57+
}
58+
}
59+
```
60+
61+
Restart Claude Desktop after saving the file.
62+
63+
### Claude Code
64+
65+
Run from your terminal:
66+
67+
```bash
68+
claude mcp add sceneview -- npx -y sceneview-mcp
69+
```
70+
71+
Or add to your `.claude/settings.json`:
2872

29-
## Quick Setup
73+
```json
74+
{
75+
"mcpServers": {
76+
"sceneview": {
77+
"command": "npx",
78+
"args": ["-y", "sceneview-mcp"]
79+
}
80+
}
81+
}
82+
```
83+
84+
### Cursor
85+
86+
Open **Settings > MCP** and add a new server:
87+
88+
**Name:** `sceneview`
89+
**Type:** `command`
90+
**Command:** `npx -y sceneview-mcp`
91+
92+
Or add to your `.cursor/mcp.json`:
93+
94+
```json
95+
{
96+
"mcpServers": {
97+
"sceneview": {
98+
"command": "npx",
99+
"args": ["-y", "sceneview-mcp"]
100+
}
101+
}
102+
}
103+
```
30104

31-
### Claude Desktop / Claude Code
105+
### Windsurf
32106

33-
Add to your MCP configuration:
107+
Open **Settings > MCP** and add:
34108

35109
```json
36110
{
@@ -43,20 +117,71 @@ Add to your MCP configuration:
43117
}
44118
```
45119

46-
### Cursor / Windsurf / Other MCP Clients
120+
### Other MCP Clients
121+
122+
The server communicates via **stdio** using the MCP protocol. Start it directly:
47123

48124
```bash
49125
npx sceneview-mcp
50126
```
51127

52-
The server communicates via stdio using the MCP protocol.
128+
---
53129

54-
### Verify Installation
130+
## Verify Installation
55131

56132
Once connected, ask your AI assistant:
133+
57134
> "List all SceneView node types"
58135
59-
It should return the full list of 22+ composable nodes.
136+
It should return the full list of 22+ composable nodes. If it does, the MCP server is working.
137+
138+
---
139+
140+
## Tool Examples
141+
142+
### Get a sample project
143+
144+
> "Show me an AR tap-to-place sample with SceneView"
145+
146+
The assistant will call `get_sample("ar-model-viewer")` and return a complete, compilable Kotlin composable with all imports and dependencies.
147+
148+
### Validate generated code
149+
150+
> "Create a 3D model viewer and validate the code"
151+
152+
The assistant will generate the code, then call `validate_code` to check it against 15+ rules (threading, null safety, API correctness, lifecycle) before presenting it.
153+
154+
### Look up a node's API
155+
156+
> "What parameters does LightNode accept?"
157+
158+
The assistant will call `get_node_reference("LightNode")` and return the exact function signature, parameter types, defaults, and a usage example.
159+
160+
### Get setup instructions
161+
162+
> "How do I set up ARCore with SceneView in my project?"
163+
164+
The assistant will call `get_ar_setup` and return the complete Gradle dependency, AndroidManifest.xml changes, session configuration options, and working AR starter templates.
165+
166+
### Get best practices
167+
168+
> "What are the performance best practices for SceneView?"
169+
170+
The assistant will call `get_best_practices("performance")` and return guidance on model optimization, runtime performance, environment/lighting setup, and common anti-patterns.
171+
172+
### Check the roadmap
173+
174+
> "Does SceneView support iOS?"
175+
176+
The assistant will call `get_platform_roadmap` and return the current multi-platform status and future plans.
177+
178+
### Migrate from v2 to v3
179+
180+
> "I'm upgrading from SceneView 2.x. What changed?"
181+
182+
The assistant will call `get_migration_guide` and return every breaking change with before/after code examples.
183+
184+
---
60185

61186
## Why Use This?
62187

@@ -74,6 +199,54 @@ It should return the full list of 22+ composable nodes.
74199
- Validate code against 15+ rules before presenting it
75200
- Provide working sample code for any scenario
76201

202+
---
203+
204+
## Troubleshooting
205+
206+
### "MCP server not found" or connection errors
207+
208+
1. Ensure Node.js 18+ is installed: `node --version`
209+
2. Test the server manually: `npx sceneview-mcp` — it should start without errors and wait for input
210+
3. Restart your AI client after changing the MCP configuration
211+
212+
### "npx command not found"
213+
214+
Install Node.js from [nodejs.org](https://nodejs.org/) (LTS recommended). npm and npx are included.
215+
216+
### Server starts but tools are not available
217+
218+
- In Claude Desktop, check the MCP icon in the input bar. It should show "sceneview" as connected.
219+
- In Cursor, check **Settings > MCP** and verify the server shows a green status.
220+
- Try restarting the MCP server by restarting your AI client.
221+
222+
### Stale data from `sceneview://known-issues`
223+
224+
GitHub issues are cached for 10 minutes. Wait for the cache to expire or restart the server.
225+
226+
### Validation false positives
227+
228+
The `validate_code` tool uses pattern matching and may flag valid code in some edge cases. If a validation warning seems incorrect, review the rule explanation in the output — it includes the rule ID and a detailed explanation.
229+
230+
### Firewall or proxy issues
231+
232+
The only network call is to the GitHub API (for `sceneview://known-issues`). All other tools work fully offline. If you are behind a corporate proxy, set the `HTTPS_PROXY` environment variable:
233+
234+
```json
235+
{
236+
"mcpServers": {
237+
"sceneview": {
238+
"command": "npx",
239+
"args": ["-y", "sceneview-mcp"],
240+
"env": {
241+
"HTTPS_PROXY": "http://proxy.example.com:8080"
242+
}
243+
}
244+
}
245+
}
246+
```
247+
248+
---
249+
77250
## Development
78251

79252
```bash

0 commit comments

Comments
 (0)