modelcontextprotocol/ext-apps
Watch
1
0
Fork
You've already forked ext-apps
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Smoothen the process of getting started (#103)

Browse source 
* Restructure threejs-server README to match marketing examples

- Update title format to "Example: Three.js App"
- Constrain screenshot width using table layout
- Add Features section with key capabilities
- Reorganize Running section with Tool Input subsection
- Add Architecture section describing server and app components
- Remove implementation-focused sections (WidgetProps, Creating a New Widget)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Add bun as devDependency to example packages

npm install now automatically installs bun, eliminating the need for
separate installation instructions. Removed manual bun install step
from customer-segmentation-server README.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Add start:http and start:stdio npm scripts to examples

For the 6 examples supporting --stdio transport, add explicit scripts:
- serve:http / serve:stdio for running the server
- start:http / start:stdio for build + serve
- start now aliases to start:http for backward compatibility

Update READMEs to document both transport options.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Default basic-host SERVERS to localhost:3001/mcp

- Change threejs-server default port from 3109 to 3001 for consistency
- Add default SERVERS value in basic-host serve.ts
- Document SERVERS env var in basic-host README

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Improve Examples section in README

Frame the three basic examples as foundational starting points and
add a link to the examples directory for additional demo apps.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Jonathan Hefner 2025-12-09 09:15:32 -06:00 • committed by GitHub
commit 4ca20f21c4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 149 additions and 132 deletions
Download patch file Download diff file Expand all files Collapse all files

141
examples/threejs-server/README.md
View file

@ -1,93 +1,43 @@
# Three.js MCP Server
# Example: Three.js App
Interactive 3D scene renderer using Three.js. Demonstrates streaming code preview and full MCP App integration.
![Screenshot](https://modelcontextprotocol.github.io/ext-apps/screenshots/threejs-server/screenshot.png)
<table>
<tr>
<td><a href="https://modelcontextprotocol.github.io/ext-apps/screenshots/threejs-server/screenshot.png"><img src="https://modelcontextprotocol.github.io/ext-apps/screenshots/threejs-server/screenshot.png" alt="Three.js scene" width="400"></a></td>
</tr>
</table>
## Tools
## Features
| Tool | Description |
| -------------------- | ------------------------------------ |
| `show_threejs_scene` | Render 3D scene from JavaScript code |
| `learn_threejs` | Get documentation and examples |
- **Interactive 3D Rendering**: Execute JavaScript code to create and animate Three.js scenes
- **Streaming Preview**: See the scene build in real-time as code is being written
- **Built-in Helpers**: Pre-configured `OrbitControls`, post-processing effects (bloom), and render passes
- **Documentation Tool**: `learn_threejs` provides API docs and code examples on demand
## Quick Start
## Running
```bash
# Build
npm run build
1. Install dependencies:
# Run (stdio mode for Claude Desktop)
bun server.ts --stdio
```bash
npm install
```
# Run (HTTP mode for basic-host)
bun server.ts
```
2. Build and start the server:
## Code Structure
```bash
npm run start:http # for Streamable HTTP transport
# OR
npm run start:stdio # for stdio transport
```
```
threejs-server/
├── server.ts # MCP server with tools
├── mcp-app.html # Entry HTML
└── src/
├── mcp-app-wrapper.tsx # Generic MCP App wrapper (reusable)
├── threejs-app.tsx # Three.js widget component
└── global.css # Styles
```
3. View using the [`basic-host`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) example or another MCP Apps-compatible host.
## Key Files
### Tool Input
### `src/mcp-app-wrapper.tsx`
To test the example, copy the contents of [`test-input.json`](test-input.json) into the tool input field in `basic-host`.
Generic wrapper handling MCP connection. Provides `WidgetProps` interface:
```tsx
interface WidgetProps<TToolInput> {
toolInputs: TToolInput | null; // Complete tool input
toolInputsPartial: TToolInput | null; // Streaming partial input
toolResult: CallToolResult | null; // Tool execution result
hostContext: McpUiHostContext | null; // Theme, viewport, locale
callServerTool: App["callServerTool"]; // Call MCP server tools
sendMessage: App["sendMessage"]; // Send chat messages
sendOpenLink: App["sendOpenLink"]; // Open URLs in browser
sendLog: App["sendLog"]; // Debug logging
}
```
### `src/threejs-app.tsx`
Widget component receiving all props. Uses:
- `toolInputs.code` - JavaScript to execute
- `toolInputsPartial.code` - Streaming preview
- `toolInputs.height` - Canvas height
### `server.ts`
MCP server with:
- `show_threejs_scene` tool linked to UI resource
- `learn_threejs` documentation tool
- stdio + HTTP transport support
## Available Three.js Globals
```javascript
THREE; // Three.js library
canvas; // Pre-created canvas
(width, height); // Canvas dimensions
OrbitControls; // Camera controls
EffectComposer; // Post-processing
RenderPass; // Render pass
UnrealBloomPass; // Bloom effect
```
## Test Input
Copy contents of `test-input.json` to test in basic-host (`http://localhost:8080`).
## Example Code
The test input creates a simple scene with a rotating cube:
```javascript
const scene = new THREE.Scene();
@ -128,10 +78,37 @@ function animate() {
animate();
```
## Creating a New Widget
#### Available Three.js Globals
1. Copy this example
2. Rename `threejs-app.tsx` to your widget name
3. Define your `ToolInput` interface
4. Implement your widget using the `WidgetProps`
5. Update `server.ts` with your tools
When writing custom code, these globals are available:
```javascript
THREE; // Three.js library
canvas; // Pre-created canvas element
width; // Canvas width
height; // Canvas height
OrbitControls; // Camera controls
EffectComposer; // Post-processing composer
RenderPass; // Render pass
UnrealBloomPass; // Bloom effect
```
## Architecture
### Server (`server.ts`)
Exposes two tools:
- `show_threejs_scene` - Renders a 3D scene from JavaScript code
- `learn_threejs` - Returns documentation and code examples for Three.js APIs
Supports Streamable HTTP and stdio transports.
### App (`src/threejs-app.tsx`)
React component that:
- Receives tool inputs via the MCP App SDK
- Displays streaming preview from `toolInputsPartial.code` as code arrives
- Executes final code from `toolInputs.code` when complete
- Renders to a pre-created canvas with configurable height

10
examples/threejs-server/package.json
View file

@ -6,9 +6,12 @@
"scripts": {
"build": "INPUT=mcp-app.html vite build",
"watch": "INPUT=mcp-app.html vite build --watch",
"serve": "bun server.ts",
"start": "NODE_ENV=development npm run build && npm run serve",
"dev": "NODE_ENV=development concurrently 'npm run watch' 'npm run serve'"
"serve:http": "bun server.ts",
"serve:stdio": "bun server.ts --stdio",
"start": "npm run start:http",
"start:http": "NODE_ENV=development npm run build && npm run serve:http",
"start:stdio": "NODE_ENV=development npm run build && npm run serve:stdio",
"dev": "NODE_ENV=development concurrently 'npm run watch' 'npm run serve:http'"
},
"dependencies": {
"@modelcontextprotocol/ext-apps": "../..",
@ -26,6 +29,7 @@
"@types/react-dom": "^19.2.2",
"@types/three": "^0.181.0",
"@vitejs/plugin-react": "^4.3.4",
"bun": "^1.3.2",
"concurrently": "^9.2.1",
"cors": "^2.8.5",
"express": "^5.1.0",

2
examples/threejs-server/server.ts
View file

@ -14,7 +14,7 @@ import path from "node:path";
import { z } from "zod";
import { RESOURCE_URI_META_KEY } from "../../dist/src/app";
const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 3109;
const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 3001;
const DIST_DIR = path.join(import.meta.dirname, "dist");
const THREEJS_DOCUMENTATION = `# Three.js Widget Documentation