Smoothen the process of getting started (#103)

* 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 <[email protected]>

* 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 <[email protected]>

* 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 <[email protected]>

* 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 <[email protected]>

* 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 <[email protected]>

---------

Co-authored-by: Claude Opus 4.5 <[email protected]>

Author: jonathanhefner

README.md

@@ -54,18 +54,22 @@ Your `package.json` will then look like:
 
 ## Examples
 
-- [`examples/basic-server-react`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-react) — Example MCP server with tools that return UI Apps (React)
+Start with these foundational examples to learn the SDK:
+
 - [`examples/basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs) — Example MCP server with tools that return UI Apps (vanilla JS)
+- [`examples/basic-server-react`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-react) — Example MCP server with tools that return UI Apps (React)
 - [`examples/basic-host`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) — Bare-bones example of hosting MCP Apps
 
-To run the examples end-to-end:
+The [`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples) directory contains additional demo apps showcasing real-world use cases.
+
+To run all examples together:
 
 ```
-npm i
+npm install
 npm run examples:start
 ```
 
-Then open http://localhost:8080/
+Then open http://localhost:8080/.
 
 ## Resources
 

examples/basic-host/README.md

@@ -1,6 +1,6 @@
 # Example: Basic Host
 
-A reference implementation showing how to build an MCP Host application that connects to MCP servers and renders tool UIs in a secure sandbox.
+A reference implementation showing how to build an MCP host application that connects to MCP servers and renders tool UIs in a secure sandbox.
 
 This basic host can also be used to test MCP Apps during local development.
 
@@ -14,10 +14,16 @@ This basic host can also be used to test MCP Apps during local development.
 
 ```bash
 npm install
-npm run dev
+npm run start
 # Open http://localhost:8080
 ```
 
+By default, the host application will try to connect to an MCP server at `http://localhost:3001/mcp`. You can configure this behavior by setting the `SERVERS` environment variable with a JSON array of server URLs:
+
+```bash
+SERVERS='["http://localhost:1234/mcp", "http://localhost:5678/mcp"]' npm run start
+```
+
 ## Architecture
 
 This example uses a double-iframe sandbox pattern for secure UI isolation:

examples/basic-host/serve.ts

@@ -18,7 +18,9 @@ const __dirname = dirname(__filename);
 const HOST_PORT = parseInt(process.env.HOST_PORT || "8080", 10);
 const SANDBOX_PORT = parseInt(process.env.SANDBOX_PORT || "8081", 10);
 const DIRECTORY = join(__dirname, "dist");
-const SERVERS: string[] = process.env.SERVERS ? JSON.parse(process.env.SERVERS) : [];
+const SERVERS: string[] = process.env.SERVERS
+  ? JSON.parse(process.env.SERVERS)
+  : ["http://localhost:3001/mcp"];
 
 // ============ Host Server (port 8080) ============
 const hostApp = express();

examples/basic-server-react/package.json

@@ -24,6 +24,7 @@
     "@types/react": "^19.2.2",
     "@types/react-dom": "^19.2.2",
     "@vitejs/plugin-react": "^4.3.4",
+    "bun": "^1.3.2",
     "concurrently": "^9.2.1",
     "cors": "^2.8.5",
     "express": "^5.1.0",

examples/basic-server-vanillajs/package.json

@@ -19,6 +19,7 @@
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.0",
     "@types/node": "^22.0.0",
+    "bun": "^1.3.2",
     "concurrently": "^9.2.1",
     "cors": "^2.8.5",
     "express": "^5.1.0",

examples/budget-allocator-server/README.md

@@ -30,11 +30,11 @@ An interactive budget allocation tool demonstrating real-time data visualization
 2. Build and start the server:
 
    ```bash
-   npm start
+   npm run start:http  # for Streamable HTTP transport
+   # OR
+   npm run start:stdio  # for stdio transport
    ```
 
-   The server will listen on `http://localhost:3001/mcp`.
-
 3. View using the [`basic-host`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) example or another MCP Apps-compatible host.
 
 ## Architecture

examples/budget-allocator-server/package.json

@@ -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": "../..",
@@ -20,6 +23,7 @@
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.0",
     "@types/node": "^22.0.0",
+    "bun": "^1.3.2",
     "concurrently": "^9.2.1",
     "cors": "^2.8.5",
     "express": "^5.1.0",

examples/cohort-heatmap-server/README.md

@@ -30,11 +30,11 @@ A demo MCP App that displays cohort retention data as an interactive heatmap, sh
 2. Build and start the server:
 
    ```bash
-   npm start
+   npm run start:http  # for Streamable HTTP transport
+   # OR
+   npm run start:stdio  # for stdio transport
    ```
 
-   The server will listen on `http://localhost:3001/mcp`.
-
 3. View using the [`basic-host`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) example or another MCP Apps-compatible host.
 
 ## Architecture

examples/cohort-heatmap-server/package.json

@@ -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": "../..",
@@ -24,6 +27,7 @@
     "@types/react": "^19.2.2",
     "@types/react-dom": "^19.2.2",
     "@vitejs/plugin-react": "^4.3.4",
+    "bun": "^1.3.2",
     "concurrently": "^9.2.1",
     "cors": "^2.8.5",
     "express": "^5.1.0",

examples/customer-segmentation-server/README.md

@@ -22,27 +22,21 @@ A demo MCP App that displays customer data as an interactive scatter/bubble char
 
 ## Running
 
-1. Install [Bun](https://github.com/oven-sh/bun) (if not already installed):
-
-   ```bash
-   curl -fsSL https://bun.com/install | bash
-   ```
-
-2. Install dependencies:
+1. Install dependencies:
 
    ```bash
    npm install
    ```
 
-3. Build and start the server:
+2. Build and start the server:
 
    ```bash
-   npm start
+   npm run start:http  # for Streamable HTTP transport
+   # OR
+   npm run start:stdio  # for stdio transport
    ```
 
-   The server will listen on `http://localhost:3001/mcp`.
-
-4. View using the [`basic-host`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) example or another MCP Apps-compatible host.
+3. View using the [`basic-host`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) example or another MCP Apps-compatible host.
 
 ## Architecture