create-mcp-use-app 0.4.6 → 0.4.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,332 @@
|
|
|
1
|
+
# Apps SDK MCP Server
|
|
2
|
+
|
|
3
|
+
[](https://mcp-use.com/deploy/start?repository-url=https%3A%2F%2Fgithub.com%2Fmcp-use%2Fmcp-use%2Ftree%2Fmain%2Flibraries%2Ftypescript%2Fpackages%2Fcreate-mcp-use-app%2Fsrc%2Ftemplates%2Fapps-sdk&branch=main&project-name=apps-sdk-template&build-command=npm+install&start-command=npm+run+build+%26%26+npm+run+start&port=3000&runtime=node&base-image=node%3A18)
|
|
4
|
+
|
|
5
|
+
An MCP server template with OpenAI Apps SDK integration for ChatGPT-compatible widgets.
|
|
6
|
+
|
|
7
|
+
## Features
|
|
8
|
+
|
|
9
|
+
- **🤖 OpenAI Apps SDK**: Full compatibility with ChatGPT widgets
|
|
10
|
+
- **🎨 React Widgets**: Interactive UI components with theme support
|
|
11
|
+
- **🔄 Automatic Registration**: Widgets auto-register from `resources/` folder
|
|
12
|
+
- **📦 Props Schema**: Zod schema validation for widget props
|
|
13
|
+
- **🌙 Theme Support**: Dark/light theme detection via `useWidget` hook
|
|
14
|
+
- **🛠️ TypeScript**: Complete type safety
|
|
15
|
+
|
|
16
|
+
## What's New: Apps SDK Integration
|
|
17
|
+
|
|
18
|
+
This template demonstrates how to build ChatGPT-compatible widgets using OpenAI's Apps SDK:
|
|
19
|
+
|
|
20
|
+
```typescript
|
|
21
|
+
import { useWidget } from 'mcp-use/react';
|
|
22
|
+
|
|
23
|
+
const MyWidget: React.FC = () => {
|
|
24
|
+
const { props, theme } = useWidget<MyProps>();
|
|
25
|
+
|
|
26
|
+
// props contains validated inputs from OpenAI
|
|
27
|
+
// theme is 'dark' or 'light' based on ChatGPT setting
|
|
28
|
+
}
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Getting Started
|
|
32
|
+
|
|
33
|
+
### Development
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
# Install dependencies
|
|
37
|
+
npm install
|
|
38
|
+
|
|
39
|
+
# Start development server
|
|
40
|
+
npm run dev
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
This starts:
|
|
44
|
+
- MCP server on port 3000
|
|
45
|
+
- Widget serving at `/mcp-use/widgets/*`
|
|
46
|
+
- Inspector UI at `/inspector`
|
|
47
|
+
|
|
48
|
+
### Production
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
# Build the server and widgets
|
|
52
|
+
npm run build
|
|
53
|
+
|
|
54
|
+
# Run the built server
|
|
55
|
+
npm start
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Project Structure
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
apps-sdk/
|
|
62
|
+
├── resources/ # React widget components
|
|
63
|
+
│ └── display-weather.tsx # Weather widget example
|
|
64
|
+
├── index.ts # Server entry point
|
|
65
|
+
├── package.json
|
|
66
|
+
├── tsconfig.json
|
|
67
|
+
└── README.md
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## How Automatic Registration Works
|
|
71
|
+
|
|
72
|
+
All React components in the `resources/` folder are automatically registered as MCP tools and resources when they export `widgetMetadata`:
|
|
73
|
+
|
|
74
|
+
```typescript
|
|
75
|
+
import { z } from 'zod';
|
|
76
|
+
|
|
77
|
+
const propSchema = z.object({
|
|
78
|
+
city: z.string().describe('The city name'),
|
|
79
|
+
temperature: z.number().describe('Temperature in Celsius'),
|
|
80
|
+
});
|
|
81
|
+
|
|
82
|
+
export const widgetMetadata = {
|
|
83
|
+
description: 'My widget description',
|
|
84
|
+
inputs: propSchema,
|
|
85
|
+
};
|
|
86
|
+
|
|
87
|
+
const MyWidget: React.FC = () => {
|
|
88
|
+
const { props } = useWidget<z.infer<typeof propSchema>>();
|
|
89
|
+
// Your widget implementation
|
|
90
|
+
};
|
|
91
|
+
|
|
92
|
+
export default MyWidget;
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
This automatically creates:
|
|
96
|
+
- **Tool**: `display-weather` - Accepts parameters via OpenAI
|
|
97
|
+
- **Resource**: `ui://widget/display-weather` - Static access
|
|
98
|
+
|
|
99
|
+
## Building Widgets with Apps SDK
|
|
100
|
+
|
|
101
|
+
### Using the `useWidget` Hook
|
|
102
|
+
|
|
103
|
+
```typescript
|
|
104
|
+
import { useWidget } from 'mcp-use/react';
|
|
105
|
+
|
|
106
|
+
interface MyProps {
|
|
107
|
+
title: string;
|
|
108
|
+
count: number;
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
const MyWidget: React.FC = () => {
|
|
112
|
+
const { props, theme } = useWidget<MyProps>();
|
|
113
|
+
|
|
114
|
+
// props are validated and typed based on your schema
|
|
115
|
+
// theme is automatically set by ChatGPT
|
|
116
|
+
|
|
117
|
+
return (
|
|
118
|
+
<div className={theme === 'dark' ? 'dark-theme' : 'light-theme'}>
|
|
119
|
+
<h1>{props.title}</h1>
|
|
120
|
+
<p>Count: {props.count}</p>
|
|
121
|
+
</div>
|
|
122
|
+
);
|
|
123
|
+
};
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Defining Widget Metadata
|
|
127
|
+
|
|
128
|
+
Use Zod schemas to define widget inputs:
|
|
129
|
+
|
|
130
|
+
```typescript
|
|
131
|
+
import { z } from 'zod';
|
|
132
|
+
|
|
133
|
+
const propSchema = z.object({
|
|
134
|
+
name: z.string().describe('Person name'),
|
|
135
|
+
age: z.number().min(0).max(120).describe('Age in years'),
|
|
136
|
+
email: z.string().email().describe('Email address'),
|
|
137
|
+
});
|
|
138
|
+
|
|
139
|
+
export const widgetMetadata = {
|
|
140
|
+
description: 'Display user information',
|
|
141
|
+
inputs: propSchema,
|
|
142
|
+
};
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### Theme Support
|
|
146
|
+
|
|
147
|
+
Automatically adapt to ChatGPT's theme:
|
|
148
|
+
|
|
149
|
+
```typescript
|
|
150
|
+
const { theme } = useWidget();
|
|
151
|
+
|
|
152
|
+
const bgColor = theme === 'dark' ? 'bg-gray-900' : 'bg-white';
|
|
153
|
+
const textColor = theme === 'dark' ? 'text-gray-100' : 'text-gray-800';
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
## Example: Weather Widget
|
|
157
|
+
|
|
158
|
+
The included `display-weather.tsx` widget demonstrates:
|
|
159
|
+
|
|
160
|
+
1. **Schema Definition**: Zod schema for validation
|
|
161
|
+
2. **Metadata Export**: Widget registration info
|
|
162
|
+
3. **Theme Detection**: Dark/light mode support
|
|
163
|
+
4. **Type Safety**: Full TypeScript support
|
|
164
|
+
|
|
165
|
+
```typescript
|
|
166
|
+
// Get props from OpenAI Apps SDK
|
|
167
|
+
const { props, theme } = useWidget<WeatherProps>();
|
|
168
|
+
|
|
169
|
+
// props.city, props.weather, props.temperature are validated
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
## Using Widgets in ChatGPT
|
|
173
|
+
|
|
174
|
+
### Via Tool Call
|
|
175
|
+
|
|
176
|
+
```typescript
|
|
177
|
+
await client.callTool('display-weather', {
|
|
178
|
+
city: 'San Francisco',
|
|
179
|
+
weather: 'sunny',
|
|
180
|
+
temperature: 22
|
|
181
|
+
});
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
### Via Resource Access
|
|
185
|
+
|
|
186
|
+
```typescript
|
|
187
|
+
await client.readResource('ui://widget/display-weather');
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
## Customization Guide
|
|
191
|
+
|
|
192
|
+
### Adding New Widgets
|
|
193
|
+
|
|
194
|
+
1. Create a React component in `resources/my-widget.tsx`:
|
|
195
|
+
|
|
196
|
+
```tsx
|
|
197
|
+
import React from 'react';
|
|
198
|
+
import { z } from 'zod';
|
|
199
|
+
import { useWidget } from 'mcp-use/react';
|
|
200
|
+
|
|
201
|
+
const propSchema = z.object({
|
|
202
|
+
message: z.string().describe('Message to display'),
|
|
203
|
+
});
|
|
204
|
+
|
|
205
|
+
export const widgetMetadata = {
|
|
206
|
+
description: 'Display a message',
|
|
207
|
+
inputs: propSchema,
|
|
208
|
+
};
|
|
209
|
+
|
|
210
|
+
type Props = z.infer<typeof propSchema>;
|
|
211
|
+
|
|
212
|
+
const MyWidget: React.FC = () => {
|
|
213
|
+
const { props, theme } = useWidget<Props>();
|
|
214
|
+
|
|
215
|
+
return (
|
|
216
|
+
<div>
|
|
217
|
+
<h1>{props.message}</h1>
|
|
218
|
+
</div>
|
|
219
|
+
);
|
|
220
|
+
};
|
|
221
|
+
|
|
222
|
+
export default MyWidget;
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
2. The widget is automatically registered!
|
|
226
|
+
|
|
227
|
+
### Adding Traditional MCP Tools
|
|
228
|
+
|
|
229
|
+
You can mix Apps SDK widgets with regular MCP tools:
|
|
230
|
+
|
|
231
|
+
```typescript
|
|
232
|
+
server.tool({
|
|
233
|
+
name: 'get-data',
|
|
234
|
+
description: 'Fetch data from API',
|
|
235
|
+
cb: async () => {
|
|
236
|
+
return { content: [{ type: 'text', text: 'Data' }] };
|
|
237
|
+
},
|
|
238
|
+
});
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
## Testing Your Widgets
|
|
242
|
+
|
|
243
|
+
### Via Inspector UI
|
|
244
|
+
|
|
245
|
+
1. Start the server: `npm run dev`
|
|
246
|
+
2. Open: `http://localhost:3000/inspector`
|
|
247
|
+
3. Test widgets interactively
|
|
248
|
+
|
|
249
|
+
### Direct Browser Access
|
|
250
|
+
|
|
251
|
+
Visit: `http://localhost:3000/mcp-use/widgets/display-weather`
|
|
252
|
+
|
|
253
|
+
### Via MCP Client
|
|
254
|
+
|
|
255
|
+
```typescript
|
|
256
|
+
import { createMCPClient } from 'mcp-use/client';
|
|
257
|
+
|
|
258
|
+
const client = createMCPClient({
|
|
259
|
+
serverUrl: 'http://localhost:3000/mcp',
|
|
260
|
+
});
|
|
261
|
+
|
|
262
|
+
await client.connect();
|
|
263
|
+
|
|
264
|
+
// Call widget as tool
|
|
265
|
+
const result = await client.callTool('display-weather', {
|
|
266
|
+
city: 'London',
|
|
267
|
+
weather: 'rain',
|
|
268
|
+
temperature: 15
|
|
269
|
+
});
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
## Apps SDK vs Other Widget Types
|
|
273
|
+
|
|
274
|
+
| Feature | Apps SDK | External URL | Remote DOM |
|
|
275
|
+
| ----------------- | ------------------ | ------------ | ---------- |
|
|
276
|
+
| ChatGPT Compatible | ✅ Yes | ❌ No | ❌ No |
|
|
277
|
+
| Theme Detection | ✅ Automatic | ❌ Manual | ❌ Manual |
|
|
278
|
+
| Props Validation | ✅ Zod Schema | ❌ Manual | ❌ Manual |
|
|
279
|
+
| React Support | ✅ Full | ✅ Full | ❌ Limited |
|
|
280
|
+
| OpenAI Metadata | ✅ Yes | ❌ No | ❌ No |
|
|
281
|
+
|
|
282
|
+
## Benefits of Apps SDK
|
|
283
|
+
|
|
284
|
+
✅ **ChatGPT Native** - Works seamlessly in ChatGPT
|
|
285
|
+
✅ **Theme Aware** - Automatic dark/light mode
|
|
286
|
+
✅ **Type Safe** - Full TypeScript with Zod validation
|
|
287
|
+
✅ **Simple API** - One hook for all props
|
|
288
|
+
✅ **Auto Registration** - Export metadata and done
|
|
289
|
+
|
|
290
|
+
## Troubleshooting
|
|
291
|
+
|
|
292
|
+
### Widget Not Loading
|
|
293
|
+
|
|
294
|
+
- Ensure widget has `widgetMetadata` export
|
|
295
|
+
- Check Zod schema is valid
|
|
296
|
+
- Verify widget exists in `dist/resources/mcp-use/widgets/`
|
|
297
|
+
|
|
298
|
+
### Props Not Passed
|
|
299
|
+
|
|
300
|
+
- Ensure schema includes all props
|
|
301
|
+
- Check `.describe()` for each prop
|
|
302
|
+
- Verify `useWidget` hook is called
|
|
303
|
+
|
|
304
|
+
### Theme Not Applied
|
|
305
|
+
|
|
306
|
+
- Theme is only available in ChatGPT
|
|
307
|
+
- Use `theme` from `useWidget()` hook
|
|
308
|
+
- Test in actual ChatGPT interface
|
|
309
|
+
|
|
310
|
+
## Migration from Other Templates
|
|
311
|
+
|
|
312
|
+
Moving from `starter` to `apps-sdk`:
|
|
313
|
+
|
|
314
|
+
```typescript
|
|
315
|
+
// Before: Manual props handling
|
|
316
|
+
const params = new URLSearchParams(window.location.search);
|
|
317
|
+
const city = params.get('city');
|
|
318
|
+
|
|
319
|
+
// After: Apps SDK hook
|
|
320
|
+
const { props } = useWidget();
|
|
321
|
+
const city = props.city;
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
## Learn More
|
|
325
|
+
|
|
326
|
+
- [MCP Documentation](https://modelcontextprotocol.io)
|
|
327
|
+
- [OpenAI Apps SDK](https://platform.openai.com/docs/apps)
|
|
328
|
+
- [mcp-use Documentation](https://docs.mcp-use.com)
|
|
329
|
+
- [React Documentation](https://react.dev/)
|
|
330
|
+
- [Zod Documentation](https://zod.dev/)
|
|
331
|
+
|
|
332
|
+
Happy building! 🚀
|
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# UIResource MCP Server
|
|
2
2
|
|
|
3
|
+
[](https://mcp-use.com/deploy/start?repository-url=https%3A%2F%2Fgithub.com%2Fmcp-use%2Fmcp-use%2Ftree%2Fmain%2Flibraries%2Ftypescript%2Fpackages%2Fcreate-mcp-use-app%2Fsrc%2Ftemplates%2Fmcp-ui&branch=main&project-name=mcp-ui-template&build-command=npm+install&start-command=npm+run+build+%26%26+npm+run+start&port=3000&runtime=node&base-image=node%3A18)
|
|
4
|
+
|
|
3
5
|
An MCP server with the new UIResource integration for simplified widget management and MCP-UI compatibility.
|
|
4
6
|
|
|
5
7
|
## Features
|
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# MCP Starter Server
|
|
2
2
|
|
|
3
|
+
[](https://mcp-use.com/deploy/start?repository-url=https%3A%2F%2Fgithub.com%2Fmcp-use%2Fmcp-use%2Ftree%2Fmain%2Flibraries%2Ftypescript%2Fpackages%2Fcreate-mcp-use-app%2Fsrc%2Ftemplates%2Fstarter&branch=main&project-name=starter-template&build-command=npm+install&start-command=npm+run+build+%26%26+npm+run+start&port=3000&runtime=node&base-image=node%3A18)
|
|
4
|
+
|
|
3
5
|
A comprehensive MCP server template with examples of tools, resources, prompts, and all UIResource types.
|
|
4
6
|
|
|
5
7
|
> 📚 **[View Full Documentation](https://docs.mcp-use.com/typescript/getting-started/quickstart)** - Complete guides, API references, and tutorials
|
|
@@ -311,11 +313,11 @@ server.uiResource({
|
|
|
311
313
|
export const myScript = `
|
|
312
314
|
const container = document.createElement('ui-stack');
|
|
313
315
|
container.setAttribute('direction', 'column');
|
|
314
|
-
|
|
316
|
+
|
|
315
317
|
const text = document.createElement('ui-text');
|
|
316
318
|
text.textContent = 'Hello from Remote DOM!';
|
|
317
319
|
container.appendChild(text);
|
|
318
|
-
|
|
320
|
+
|
|
319
321
|
root.appendChild(container);
|
|
320
322
|
`
|
|
321
323
|
```
|