Skip to content

Commit 32738ba

Browse files
eli6eli6
authored
Merge pull request #1 from eli6/updating-to-three-examples-html-react-and-basic
Updating to three examples html react and basic
2 parents bf35bc1 + 647fb69 commit 32738ba

File tree

20 files changed

+8564
-189
lines changed

20 files changed

+8564
-189
lines changed

‎.dockerignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,13 @@
11
node_modules
2+
**/node_modules
23
npm-debug.log
34
Dockerfile*
45
.git
56
.gitignore
67
**/.DS_Store
78
.vscode
89
*.swp
10+
11+
# Web build artifacts (built inside container, don't copy from host)
12+
web/dist
13+
web/node_modules

‎.gitignore‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,11 @@
11
/node_modules
2-
*env
2+
node_modules/
3+
*env
4+
5+
# Web build artifacts
6+
web/dist/
7+
web/node_modules/
8+
9+
10+
.DS_Store
11+
**/.DS_Store

‎Dockerfile‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,19 +3,24 @@
33
FROM node:20-alpine
44
WORKDIR /app
55

6-
# Install dependencies with caching
6+
# Install root dependencies with caching
77
COPY package.json package-lock.json ./
88
RUN --mount=type=cache,target=/root/.npm npm ci
99

10+
# Build web components if web/ directory exists (for React UI mode)
11+
# Copy entire web directory (package.json, src/, tsconfig.json)
12+
COPY web/ ./web/
13+
RUN if [ -f web/package.json ]; then \
14+
cd web && npm ci && npm run build; \
15+
fi
16+
1017
# Copy source
1118
COPY tsconfig.json ./
1219
COPY src ./src
1320

1421
# App listens on 3000
1522
EXPOSE 3000
1623

17-
# Explicitly disable auth by default in this image (can override at runtime)
18-
ENV DISABLE_AUTH=true
19-
24+
# Tool mode: basic (default), ui-html, or ui-react
2025
# Start the MCP server (uses devDependency tsx)
21-
CMD ["npm", "run", "start"]
26+
CMD ["npm", "run", "start:ui-react"]

‎README.md‎

Lines changed: 113 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -31,25 +31,124 @@ Start the OAuth demo (port 3001):
3131
npm run dev:oauth
3232
```
3333

34-
Start the MCP server (port 3000). By default, local runs use opaque tokens via the demo OAuth server (introspection mode). Place your env in `.env` and run dev for hot reload:
34+
## Tool Modes & Development
35+
36+
This server supports three distinct tool modes, each optimized for different use cases. Choose the mode that best fits your needs:
37+
38+
### 🛠️ Basic Tools Mode (Default)
39+
40+
**Best for:** Learning MCP fundamentals, CLI tools, and simple text-based interactions.
41+
42+
The basic mode provides core MCP functionality with simple text-based tool responses. Perfect for understanding the MCP protocol without UI complexity.
3543

3644
```bash
37-
# .env (local opaque token default)
38-
# OAUTH_SERVER_URL defaults to http://localhost:3001
39-
# OAUTH_INTROSPECT_URL defaults to ${OAUTH_SERVER_URL}/introspect
45+
npm run dev
46+
```
4047

41-
DISABLE_AUTH=false
42-
AUTH_TOKEN_MODE=introspection
48+
**Features:**
49+
- Pure MCP protocol implementation
50+
- Text-based tool responses
51+
- Minimal dependencies
52+
- Fast and lightweight
53+
54+
### 🎨 HTML UI Mode
55+
56+
**Best for:** Quick prototypes, simple forms, and lightweight interactive components.
57+
58+
HTML UI mode enables rich, interactive components using vanilla HTML, CSS, and JavaScript. Components are served as standalone HTML files that can be embedded in MCP clients.
59+
60+
```bash
61+
npm run dev:ui-html
62+
```
63+
64+
**Features:**
65+
- Interactive HTML components
66+
- No build step required
67+
- Fast iteration
68+
- Lightweight bundle size
69+
70+
### ⚛️ React UI Mode
71+
72+
**Best for:** Complex, stateful components and modern React-based UIs.
73+
74+
React UI mode provides full React component support with TypeScript, enabling sophisticated user interfaces with state management, hooks, and modern React patterns.
75+
76+
```bash
77+
npm run dev:ui-react
78+
```
79+
80+
**Features:**
81+
- Full React 18+ support
82+
- TypeScript for type safety
83+
- Component state management
84+
- Modern React patterns (hooks, context, etc.)
85+
86+
### 🧪 React Component Development
4387

88+
The `web/` directory contains a lightweight React development environment for designing and testing your UI components locally.
89+
90+
**Start the development server:**
91+
```bash
92+
cd web
4493
npm run dev
4594
```
4695

47-
Tip: If you want to run MCP without auth locally, set the explicit flag (in env or inline):
96+
This launches a Vite-powered dev server with:
97+
- ⚡ Hot module replacement (instant updates)
98+
- 🔍 Component preview in browser
99+
- 🎯 Mock `window.openai` API for testing
100+
- 📦 Automatic TypeScript compilation
101+
102+
Edit `web/src/components/greet.tsx` and see your changes instantly. The mock API simulates tool calls, so you can develop and test your component's behavior without running the full MCP server.
48103

104+
**Build for production:**
105+
```bash
106+
cd web
107+
npm run build
108+
```
109+
110+
This generates `web/dist/greet.js`, which is automatically included when running the MCP server in React UI mode.
111+
112+
### 🐳 Docker Configuration
113+
114+
In production deployments, configure the tool mode by changing the `CMD` in your Dockerfile to use the appropriate npm script. The npm scripts already set the `TOOL_MODE` environment variable internally, so you don't need to set it separately.
115+
116+
**Dockerfile:**
117+
```dockerfile
118+
# Choose the start script that matches your desired mode:
119+
# CMD ["npm", "run", "start"] # Basic tools (default)
120+
# CMD ["npm", "run", "start:ui-html"] # HTML UI
121+
CMD ["npm", "run", "start:ui-react"] # React UI
122+
```
123+
124+
**Examples for different modes:**
125+
```dockerfile
126+
# Basic mode (no UI)
127+
CMD ["npm", "run", "start"]
128+
129+
# HTML UI mode
130+
CMD ["npm", "run", "start:ui-html"]
131+
132+
# React UI mode
133+
CMD ["npm", "run", "start:ui-react"]
134+
```
135+
136+
The Dockerfile automatically builds React components during the image build process, so React UI mode is ready to use in production.
137+
138+
---
139+
140+
### Development Tips
141+
142+
**Run without authentication (local testing):**
49143
```bash
50144
DISABLE_AUTH=true npm run dev
51145
```
52146

147+
**Switch between modes:**
148+
- `npm run dev` → Basic tools
149+
- `npm run dev:ui-html` → HTML UI
150+
- `npm run dev:ui-react` → React UI (builds web components first)
151+
53152
### Token modes: introspection (local default) or JWT (managed IdP)
54153

55154
This server supports two auth modes, controlled by `AUTH_TOKEN_MODE`:
@@ -196,6 +295,13 @@ curl -i -X POST http://localhost:3000/mcp \
196295
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"greet","arguments":{"name":"Elin"}}}'
197296
```
198297

298+
**Tool mode differences:**
299+
- **Basic mode:** Returns simple text response: `"Hello, Elin!"`
300+
- **HTML UI mode:** Returns HTML component template (`ui://widget/greet.html`) with structured content for hydration
301+
- **React UI mode:** Returns React component template (`ui://widget/greet.js`) with full React support and state management
302+
303+
In UI modes, rich clients can render interactive components that allow users to interact directly with the tool, and components can initiate tool calls via the `window.openai.callTool` API when supported.
304+
199305
Call `count`:
200306

201307
```bash

0 commit comments

Comments
 (0)