1# Common Patterns
2 
3Complete end-to-end examples showing server + widget implementations for common use cases.
4 
5**Examples:** Weather app, Todo list, Recipe browser, File manager
6 
7---
8 
9## Weather App
10 
11### Server (index.ts)
12 
13```typescript
14import { MCPServer, text, widget, object, error } from "mcp-use/server";
15import { z } from "zod";
16 
17const server = new MCPServer({
18  name: "weather-server",
19  title: "Weather Server",
20  version: "1.0.0",
21  baseUrl: process.env.MCP_URL || "http://localhost:3000"
22});
23 
24// Mock weather data
25const weatherData: Record<string, { temp: number; conditions: string; icon: string }> = {
26  "New York": { temp: 22, conditions: "Partly Cloudy", icon: "⛅" },
27  "London": { temp: 15, conditions: "Rainy", icon: "🌧️" },
28  "Tokyo": { temp: 28, conditions: "Sunny", icon: "☀️" },
29  "Paris": { temp: 18, conditions: "Overcast", icon: "☁️" },
30  "Sydney": { temp: 25, conditions: "Clear", icon: "🌤️" }
31};
32 
33// Tool: Get weather with widget
34server.tool(
35  {
36    name: "get-weather",
37    description: "Get current weather for a city",
38    schema: z.object({
39      city: z.string().describe("City name (e.g., 'New York', 'Tokyo')")
40    }),
41    widget: {
42      name: "weather-display",
43      invoking: "Fetching weather...",
44      invoked: "Weather loaded"
45    }
46  },
47  async ({ city }) => {
48    const data = weatherData[city];
49 
50    if (!data) {
51      return error(`No weather data for ${city}. Available cities: ${Object.keys(weatherData).join(", ")}`);
52    }
53 
54    return widget({
55      props: {
56        city,
57        temp: data.temp,
58        conditions: data.conditions,
59        icon: data.icon,
60        timestamp: new Date().toISOString()
61      },
62      output: text(`Weather in ${city}: ${data.temp}°C, ${data.conditions}`)
63    });
64  }
65);
66 
67// Resource: Available cities
68server.resource(
69  {
70    name: "available_cities",
71    uri: "weather://cities",
72    title: "Available Cities",
73    description: "List of cities with weather data"
74  },
75  async () => object({
76    cities: Object.keys(weatherData)
77  })
78);
79 
80server.listen();
81```
82 
83### Widget (resources/weather-display.tsx)
84 
85```tsx
86import { McpUseProvider, useWidget, useWidgetTheme, type WidgetMetadata } from "mcp-use/react";
87import { z } from "zod";
88 
89export const widgetMetadata: WidgetMetadata = {
90  description: "Display weather information for a city",
91  props: z.object({
92    city: z.string(),
93    temp: z.number(),
94    conditions: z.string(),
95    icon: z.string(),
96    timestamp: z.string()
97  }),
98  exposeAsTool: false
99};
100 
101export default function WeatherDisplay() {
102  const { props, isPending } = useWidget();
103  const theme = useWidgetTheme();
104 
105  if (isPending) {
106    return (
107      <McpUseProvider autoSize>
108        <div style={{ padding: 40, textAlign: "center" }}>
109          <div style={{ fontSize: 48, marginBottom: 16 }}>🌍</div>
110          <p>Loading weather...</p>
111        </div>
112      </McpUseProvider>
113    );
114  }
115 
116  const bgColor = theme === "dark" ? "#1e1e1e" : "#ffffff";
117  const textColor = theme === "dark" ? "#e0e0e0" : "#1a1a1a";
118  const secondaryColor = theme === "dark" ? "#b0b0b0" : "#666";
119 
120  return (
121    <McpUseProvider autoSize>
122      <div style={{
123        padding: 24,
124        backgroundColor: bgColor,
125        color: textColor,
126        borderRadius: 8
127      }}>
128        <h2 style={{ margin: "0 0 8px 0", fontSize: 24 }}>{props.city}</h2>
129        <p style={{ margin: "0 0 20px 0", color: secondaryColor, fontSize: 12 }}>
130          {new Date(props.timestamp).toLocaleString()}
131        </p>
132 
133        <div style={{ display: "flex", alignItems: "center", gap: 16 }}>
134          <div style={{ fontSize: 64 }}>{props.icon}</div>
135          <div>
136            <div style={{ fontSize: 48, fontWeight: "bold" }}>{props.temp}°C</div>
137            <div style={{ fontSize: 18, color: secondaryColor }}>{props.conditions}</div>
138          </div>
139        </div>
140      </div>
141    </McpUseProvider>
142  );
143}
144```
145 
146---
147 
148## Todo List
149 
150### Server (index.ts)
151 
152```typescript
153import { MCPServer, text, widget, object, error } from "mcp-use/server";
154import { z } from "zod";
155 
156const server = new MCPServer({
157  name: "todo-server",
158  title: "Todo Server",
159  version: "1.0.0"
160});
161 
162// Mock database
163let todos: Array<{ id: string; title: string; completed: boolean }> = [
164  { id: "1", title: "Learn MCP", completed: true },
165  { id: "2", title: "Build first widget", completed: false },
166  { id: "3", title: "Deploy server", completed: false }
167];
168 
169// Tool: List todos with widget
170server.tool(
171  {
172    name: "list-todos",
173    description: "List all todos",
174    schema: z.object({}),
175    widget: {
176      name: "todo-list",
177      invoking: "Loading todos...",
178      invoked: "Todos loaded"
179    }
180  },
181  async () => {
182    return widget({
183      props: {
184        todos,
185        totalCount: todos.length,
186        completedCount: todos.filter(t => t.completed).length
187      },
188      output: text(`Found ${todos.length} todos (${todos.filter(t => t.completed).length} completed)`)
189    });
190  }
191);
192 
193// Tool: Create todo
194server.tool(
195  {
196    name: "create-todo",
197    description: "Create a new todo",
198    schema: z.object({
199      title: z.string().describe("Todo title")
200    })
201  },
202  async ({ title }) => {
203    const newTodo = {
204      id: Date.now().toString(),
205      title,
206      completed: false
207    };
208 
209    todos.push(newTodo);
210 
211    return text(`Created todo: ${title}`);
212  }
213);
214 
215// Tool: Toggle todo
216server.tool(
217  {
218    name: "toggle-todo",
219    description: "Toggle todo completion status",
220    schema: z.object({
221      id: z.string().describe("Todo ID"),
222      completed: z.boolean().describe("New completion status")
223    })
224  },
225  async ({ id, completed }) => {
226    const todo = todos.find(t => t.id === id);
227 
228    if (!todo) {
229      return error(`Todo not found: ${id}`);
230    }
231 
232    todo.completed = completed;
233 
234    return text(`Todo ${completed ? "completed" : "uncompleted"}`);
235  }
236);
237 
238// Tool: Delete todo
239server.tool(
240  {
241    name: "delete-todo",
242    description: "Delete a todo",
243    schema: z.object({
244      id: z.string().describe("Todo ID")
245    }),
246    annotations: {
247      destructiveHint: true
248    }
249  },
250  async ({ id }) => {
251    const index = todos.findIndex(t => t.id === id);
252 
253    if (index === -1) {
254      return error(`Todo not found: ${id}`);
255    }
256 
257    const deleted = todos.splice(index, 1)[0];
258 
259    return text(`Deleted todo: ${deleted.title}`);
260  }
261);
262 
263server.listen();
264```
265 
266### Widget (resources/todo-list.tsx)
267 
268```tsx
269import { useState } from "react";
270import { McpUseProvider, useWidget, useWidgetTheme, useCallTool, type WidgetMetadata } from "mcp-use/react";
271import { z } from "zod";
272 
273export const widgetMetadata: WidgetMetadata = {
274  description: "Interactive todo list",
275  props: z.object({
276    todos: z.array(z.object({
277      id: z.string(),
278      title: z.string(),
279      completed: z.boolean()
280    })),
281    totalCount: z.number(),
282    completedCount: z.number()
283  }),
284  exposeAsTool: false
285};
286 
287export default function TodoList() {
288  const { props, isPending } = useWidget();
289  const theme = useWidgetTheme();
290  const { callTool: createTodo, isPending: isCreating } = useCallTool("create-todo");
291  const { callTool: toggleTodo } = useCallTool("toggle-todo");
292  const { callTool: deleteTodo } = useCallTool("delete-todo");
293  const [newTodo, setNewTodo] = useState("");
294  const [deletingId, setDeletingId] = useState<string | null>(null);
295 
296  if (isPending) {
297    return (
298      <McpUseProvider autoSize>
299        <div style={{ padding: 20 }}>Loading todos...</div>
300      </McpUseProvider>
301    );
302  }
303 
304  // Theme-aware colors (see ui-guidelines.md for useColors() hook pattern)
305  const colors = {
306    bg: theme === "dark" ? "#1e1e1e" : "#ffffff",
307    text: theme === "dark" ? "#e0e0e0" : "#1a1a1a",
308    border: theme === "dark" ? "#404040" : "#e0e0e0",
309    hover: theme === "dark" ? "#2a2a2a" : "#f5f5f5"
310  };
311 
312  const handleCreate = (e: React.FormEvent) => {
313    e.preventDefault();
314    if (!newTodo.trim()) return;
315 
316    createTodo({ title: newTodo }, {
317      onSuccess: () => setNewTodo(""),
318      onError: () => alert("Failed to create todo"),
319    });
320  };
321 
322  const handleToggle = (id: string, completed: boolean) => {
323    toggleTodo({ id, completed: !completed });
324  };
325 
326  const handleDelete = (id: string) => {
327    setDeletingId(id);
328    deleteTodo({ id }, {
329      onError: () => alert("Failed to delete"),
330      onSettled: () => setDeletingId(null),
331    });
332  };
333 
334  return (
335    <McpUseProvider autoSize>
336      <div style={{ padding: 20, backgroundColor: colors.bg, color: colors.text }}>
337        <h2 style={{ margin: "0 0 8px 0" }}>
338          Todos ({props.completedCount}/{props.totalCount})
339        </h2>
340 
341        {/* Create form */}
342        <form onSubmit={handleCreate} style={{ marginBottom: 16, display: "flex", gap: 8 }}>
343          <input
344            type="text"
345            value={newTodo}
346            onChange={e => setNewTodo(e.target.value)}
347            placeholder="New todo..."
348            disabled={isCreating}
349            style={{
350              flex: 1,
351              padding: 8,
352              border: `1px solid ${colors.border}`,
353              borderRadius: 4,
354              backgroundColor: colors.bg,
355              color: colors.text
356            }}
357          />
358          <button
359            type="submit"
360            disabled={isCreating}
361            style={{
362              padding: "8px 16px",
363              border: "none",
364              borderRadius: 4,
365              backgroundColor: "#0066cc",
366              color: "white",
367              cursor: isCreating ? "not-allowed" : "pointer"
368            }}
369          >
370            {isCreating ? "Adding..." : "Add"}
371          </button>
372        </form>
373 
374        {/* Todo list */}
375        <div>
376          {props.todos.map(todo => (
377            <div
378              key={todo.id}
379              style={{
380                display: "flex",
381                alignItems: "center",
382                gap: 8,
383                padding: 12,
384                borderBottom: `1px solid ${colors.border}`,
385                backgroundColor: colors.bg
386              }}
387            >
388              <input
389                type="checkbox"
390                checked={todo.completed}
391                onChange={() => handleToggle(todo.id, todo.completed)}
392                style={{ cursor: "pointer" }}
393              />
394              <span style={{
395                flex: 1,
396                textDecoration: todo.completed ? "line-through" : "none",
397                opacity: todo.completed ? 0.6 : 1
398              }}>
399                {todo.title}
400              </span>
401              <button
402                onClick={() => handleDelete(todo.id)}
403                disabled={deletingId === todo.id}
404                style={{
405                  padding: "4px 12px",
406                  border: "none",
407                  borderRadius: 4,
408                  backgroundColor: "transparent",
409                  color: "#dc3545",
410                  cursor: deletingId === todo.id ? "not-allowed" : "pointer"
411                }}
412              >
413                {deletingId === todo.id ? "..." : "Delete"}
414              </button>
415            </div>
416          ))}
417        </div>
418 
419        {props.todos.length === 0 && (
420          <p style={{ textAlign: "center", color: colors.border, padding: 40 }}>
421            No todos yet. Create one above!
422          </p>
423        )}
424      </div>
425    </McpUseProvider>
426  );
427}
428```
429 
430---
431 
432## Recipe Browser
433 
434### Server (index.ts)
435 
436```typescript
437import { MCPServer, widget, text } from "mcp-use/server";
438import { z } from "zod";
439 
440const server = new MCPServer({
441  name: "recipe-server",
442  title: "Recipe Server",
443  version: "1.0.0"
444});
445 
446// Mock recipe data
447const recipes = [
448  {
449    id: "1",
450    name: "Spaghetti Carbonara",
451    category: "Italian",
452    time: 20,
453    difficulty: "Easy",
454    ingredients: ["Spaghetti", "Eggs", "Bacon", "Parmesan", "Black pepper"],
455    instructions: "Cook pasta. Fry bacon. Mix eggs and cheese. Combine all with pasta."
456  },
457  {
458    id: "2",
459    name: "Chicken Tikka Masala",
460    category: "Indian",
461    time: 45,
462    difficulty: "Medium",
463    ingredients: ["Chicken", "Yogurt", "Tomatoes", "Cream", "Spices"],
464    instructions: "Marinate chicken. Cook in spiced tomato sauce. Add cream."
465  },
466  {
467    id: "3",
468    name: "Caesar Salad",
469    category: "Salad",
470    time: 15,
471    difficulty: "Easy",
472    ingredients: ["Romaine lettuce", "Croutons", "Parmesan", "Caesar dressing"],
473    instructions: "Toss lettuce with dressing. Top with croutons and cheese."
474  }
475];
476 
477// Tool: Browse recipes
478server.tool(
479  {
480    name: "browse-recipes",
481    description: "Browse recipe collection",
482    schema: z.object({
483      category: z.string().optional().describe("Filter by category (Italian, Indian, Salad)")
484    }),
485    widget: {
486      name: "recipe-browser",
487      invoking: "Loading recipes...",
488      invoked: "Recipes loaded"
489    }
490  },
491  async ({ category }) => {
492    const filtered = category
493      ? recipes.filter(r => r.category === category)
494      : recipes;
495 
496    return widget({
497      props: {
498        recipes: filtered,
499        categories: ["All", ...new Set(recipes.map(r => r.category))],
500        selectedCategory: category || "All"
501      },
502      output: text(`Found ${filtered.length} recipes`)
503    });
504  }
505);
506 
507server.listen();
508```
509 
510### Widget (resources/recipe-browser.tsx)
511 
512```tsx
513import { useState, useEffect } from "react";
514import { McpUseProvider, useWidget, useWidgetTheme, type WidgetMetadata } from "mcp-use/react";
515import { z } from "zod";
516 
517export const widgetMetadata: WidgetMetadata = {
518  description: "Browse and view recipes",
519  props: z.object({
520    recipes: z.array(z.object({
521      id: z.string(),
522      name: z.string(),
523      category: z.string(),
524      time: z.number(),
525      difficulty: z.string(),
526      ingredients: z.array(z.string()),
527      instructions: z.string()
528    })),
529    categories: z.array(z.string()),
530    selectedCategory: z.string()
531  }),
532  exposeAsTool: false
533};
534 
535export default function RecipeBrowser() {
536  const { props, isPending } = useWidget();
537  const theme = useWidgetTheme();
538  const [selectedRecipe, setSelectedRecipe] = useState<string | null>(null);
539  const [filter, setFilter] = useState<string>("all");
540 
541  // Sync initial filter from props once loaded
542  useEffect(() => {
543    if (!isPending && props.selectedCategory) {
544      setFilter(props.selectedCategory);
545    }
546  }, [isPending, props.selectedCategory]);
547 
548  if (isPending) {
549    return (
550      <McpUseProvider autoSize>
551        <div style={{ padding: 20 }}>Loading recipes...</div>
552      </McpUseProvider>
553    );
554  }
555 
556  // Theme-aware colors (see ui-guidelines.md for useColors() hook pattern)
557  const colors = {
558    bg: theme === "dark" ? "#1e1e1e" : "#ffffff",
559    text: theme === "dark" ? "#e0e0e0" : "#1a1a1a",
560    secondary: theme === "dark" ? "#b0b0b0" : "#666",
561    border: theme === "dark" ? "#404040" : "#e0e0e0",
562    hover: theme === "dark" ? "#2a2a2a" : "#f5f5f5"
563  };
564 
565  const filteredRecipes = filter === "All"
566    ? props.recipes
567    : props.recipes.filter(r => r.category === filter);
568 
569  const selected = filteredRecipes.find(r => r.id === selectedRecipe);
570 
571  return (
572    <McpUseProvider autoSize>
573      <div style={{ backgroundColor: colors.bg, color: colors.text }}>
574        {/* Header */}
575        <div style={{ padding: 16, borderBottom: `1px solid ${colors.border}` }}>
576          <h2 style={{ margin: "0 0 12px 0" }}>Recipe Browser</h2>
577 
578          {/* Category filters */}
579          <div style={{ display: "flex", gap: 8, flexWrap: "wrap" }}>
580            {props.categories.map(cat => (
581              <button
582                key={cat}
583                onClick={() => setFilter(cat)}
584                style={{
585                  padding: "6px 12px",
586                  border: `1px solid ${colors.border}`,
587                  borderRadius: 4,
588                  backgroundColor: filter === cat ? "#0066cc" : "transparent",
589                  color: filter === cat ? "white" : colors.text,
590                  cursor: "pointer",
591                  fontSize: 14
592                }}
593              >
594                {cat}
595              </button>
596            ))}
597          </div>
598        </div>
599 
600        {/* Recipe list */}
601        <div style={{ display: "flex" }}>
602          <div style={{ flex: 1, borderRight: `1px solid ${colors.border}` }}>
603            {filteredRecipes.map(recipe => (
604              <div
605                key={recipe.id}
606                onClick={() => setSelectedRecipe(recipe.id)}
607                style={{
608                  padding: 16,
609                  borderBottom: `1px solid ${colors.border}`,
610                  cursor: "pointer",
611                  backgroundColor: selectedRecipe === recipe.id ? colors.hover : "transparent"
612                }}
613              >
614                <h3 style={{ margin: "0 0 4px 0", fontSize: 16 }}>{recipe.name}</h3>
615                <p style={{
616                  margin: 0,
617                  fontSize: 12,
618                  color: colors.secondary
619                }}>
620                  {recipe.category} • {recipe.time} min • {recipe.difficulty}
621                </p>
622              </div>
623            ))}
624          </div>
625 
626          {/* Recipe detail */}
627          <div style={{ flex: 2, padding: 16 }}>
628            {selected ? (
629              <div>
630                <h2 style={{ margin: "0 0 8px 0" }}>{selected.name}</h2>
631                <p style={{ margin: "0 0 16px 0", color: colors.secondary }}>
632                  {selected.category} • {selected.time} minutes • {selected.difficulty}
633                </p>
634 
635                <h3 style={{ fontSize: 16, marginBottom: 8 }}>Ingredients</h3>
636                <ul style={{ marginBottom: 16, paddingLeft: 20 }}>
637                  {selected.ingredients.map((ing, i) => (
638                    <li key={i}>{ing}</li>
639                  ))}
640                </ul>
641 
642                <h3 style={{ fontSize: 16, marginBottom: 8 }}>Instructions</h3>
643                <p style={{ lineHeight: 1.6 }}>{selected.instructions}</p>
644              </div>
645            ) : (
646              <p style={{ color: colors.secondary, textAlign: "center", paddingTop: 40 }}>
647                Select a recipe to view details
648              </p>
649            )}
650          </div>
651        </div>
652      </div>
653    </McpUseProvider>
654  );
655}
656```
657 
658---
659 
660## Key Patterns Demonstrated
661 
662### 1. **Mock Data First**
663All examples use mock data, making it easy to prototype and test before connecting real APIs.
664 
665### 2. **Widget + Tool Combination**
666Each example shows how to pair a tool with a widget for visual output.
667 
668### 3. **Interactive Actions**
669Todo list shows create/update/delete operations from within widgets using `useCallTool()`.
670 
671### 4. **Theme Support**
672All widgets use `useWidgetTheme()` to adapt to light/dark mode.
673 
674### 5. **State Management**
675Recipe browser demonstrates local widget state (selected recipe, filters) vs server state (recipe data).
676 
677### 6. **Error Handling**
678Weather app shows proper error responses when data not found.
679 
680### 7. **Loading States**
681All widgets check `isPending` and show loading UI.
682 
683### 8. **Master-Detail Layout**
684Recipe browser shows a master-detail pattern with list + detail view.
685 
686---
687 
688## Expanding These Examples
689 
690### Add Real APIs
691Replace mock data with API calls:
692 
693```typescript
694// Weather with real API
695const WEATHER_API_KEY = process.env.WEATHER_API_KEY;
696 
697server.tool(
698  { name: "get-weather", schema: z.object({ city: z.string() }), widget: { name: "weather-display" } },
699  async ({ city }) => {
700    if (!WEATHER_API_KEY) {
701      return error("WEATHER_API_KEY not configured. Set it in environment variables.");
702    }
703 
704    const response = await fetch(
705      `https://api.weatherapi.com/v1/current.json?key=${WEATHER_API_KEY}&q=${city}`
706    );
707 
708    if (!response.ok) {
709      return error(`Weather API error: ${response.statusText}`);
710    }
711 
712    const data = await response.json();
713 
714    return widget({
715      props: {
716        city: data.location.name,
717        temp: data.current.temp_c,
718        conditions: data.current.condition.text,
719        icon: data.current.condition.icon,
720        timestamp: data.current.last_updated
721      },
722      output: text(`Weather in ${city}: ${data.current.temp_c}°C, ${data.current.condition.text}`)
723    });
724  }
725);
726```
727 
728### Add Database
729Replace in-memory data with database:
730 
731```typescript
732import { Database } from "better-sqlite3";
733 
734const db = new Database("todos.db");
735 
736db.exec(`
737  CREATE TABLE IF NOT EXISTS todos (
738    id TEXT PRIMARY KEY,
739    title TEXT NOT NULL,
740    completed INTEGER NOT NULL DEFAULT 0,
741    created_at TEXT NOT NULL
742  )
743`);
744 
745server.tool(
746  { name: "list-todos", schema: z.object({}), widget: { name: "todo-list" } },
747  async () => {
748    const todos = db.prepare("SELECT * FROM todos ORDER BY created_at DESC").all();
749 
750    return widget({
751      props: {
752        todos: todos.map(t => ({ ...t, completed: Boolean(t.completed) })),
753        totalCount: todos.length,
754        completedCount: todos.filter(t => t.completed).length
755      },
756      output: text(`Found ${todos.length} todos`)
757    });
758  }
759);
760```
761 
762---
763 
764## Next Steps
765 
766- **Review server concepts** → [../server/tools.md](../server/tools.md)
767- **Learn widget basics** → [../widgets/basics.md](../widgets/basics.md)
768- **Check best practices** → [../../SKILL.md](../../SKILL.md)
769