You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The basic mode provides core MCP functionality with simple text-based tool responses. Perfect for understanding the MCP protocol without UI complexity.
35
43
36
-
**Pure MCP (default):**
37
44
```bash
38
-
# .env (local opaque token default)
39
-
# OAUTH_SERVER_URL defaults to http://localhost:3001
40
-
# OAUTH_INTROSPECT_URL defaults to ${OAUTH_SERVER_URL}/introspect
45
+
npm run dev
46
+
```
41
47
42
-
DISABLE_AUTH=false
43
-
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.
44
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
87
+
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
45
93
npm run dev
46
94
```
47
95
48
-
**MCP + UI Components:**
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.
103
+
104
+
**Build for production:**
49
105
```bash
50
-
# Same .env as above
51
-
npm run dev:ui
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:
The pure MCP mode focuses on core MCP functionality (auth, tools, endpoints). The UI mode adds rich component experiences with interactive forms and visual feedback.
124
+
**Examples for different modes:**
125
+
```dockerfile
126
+
# Basic mode (no UI)
127
+
CMD ["npm", "run", "start"]
55
128
56
-
Tip: If you want to run MCP without auth locally, set the explicit flag (in env or inline):
129
+
# HTML UI mode
130
+
CMD ["npm", "run", "start:ui-html"]
131
+
132
+
# React UI mode
133
+
CMD ["npm", "run", "start:ui-react"]
134
+
```
57
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):**
58
143
```bash
59
144
DISABLE_AUTH=true npm run dev
60
145
```
61
146
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
+
62
152
### Token modes: introspection (local default) or JWT (managed IdP)
63
153
64
154
This server supports two auth modes, controlled by `AUTH_TOKEN_MODE`:
@@ -205,9 +295,12 @@ curl -i -X POST http://localhost:3000/mcp \
**UI Mode:** The `greet` tool renders a simple component with an input field. In rich-UI clients, it is associated with the template `ui://widget/greet.html` and can initiate tool calls from the iframe when supported. The tool also returns `structuredContent` with `{ name, greeting }` so the component can hydrate initial UI state.
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
209
302
210
-
**Pure MCP Mode:** The `greet` tool returns simple text responses without UI components, perfect for learning MCP fundamentals.
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.
0 commit comments