1# Response Helpers
2 
3Response helpers format output from tools, resources, and prompts. Always use helpers instead of returning raw values.
4 
5**Available helpers:** `text()`, `object()`, `markdown()`, `image()`, `error()`, `widget()`, `mix()`, `resource()`
6 
7---
8 
9## Why Use Response Helpers?
10 
11```typescript
12// ❌ Bad - Raw return value
13server.tool(
14  { name: "get-data", schema: z.object({}) },
15  async () => {
16    return { status: "ok", data: [1, 2, 3] };  // Wrong!
17  }
18);
19 
20// ✅ Good - Using helper
21server.tool(
22  { name: "get-data", schema: z.object({}) },
23  async () => {
24    return object({ status: "ok", data: [1, 2, 3] });
25  }
26);
27```
28 
29**Why:**
30- Helpers set correct MIME types
31- Ensure proper serialization
32- Enable client-side rendering
33- Support multi-content responses
34 
35---
36 
37## text()
38 
39Simple string responses. Most common helper.
40 
41```typescript
42import { text } from "mcp-use/server";
43 
44server.tool(
45  { name: "greet", schema: z.object({ name: z.string() }) },
46  async ({ name }) => {
47    return text(`Hello, ${name}!`);
48  }
49);
50 
51// Multi-line text
52server.tool(
53  { name: "format-address", schema: z.object({
54    address: z.object({
55      street: z.string(),
56      city: z.string(),
57      state: z.string(),
58      zip: z.string(),
59      country: z.string()
60    })
61  }) },
62  async ({ address }) => {
63    return text(
64      `${address.street}\n` +
65      `${address.city}, ${address.state} ${address.zip}\n` +
66      `${address.country}`
67    );
68  }
69);
70```
71 
72**Use for:**
73- Simple messages
74- Confirmation text
75- Status updates
76- Plain text output
77 
78---
79 
80## object()
81 
82Structured JSON data. Use when AI or client needs structured information.
83 
84```typescript
85import { object } from "mcp-use/server";
86 
87server.tool(
88  { name: "get-user", schema: z.object({ id: z.string() }) },
89  async ({ id }) => {
90    const user = await fetchUser(id);
91 
92    return object({
93      id: user.id,
94      name: user.name,
95      email: user.email,
96      createdAt: user.createdAt,
97      settings: {
98        theme: user.theme,
99        notifications: user.notifications
100      }
101    });
102  }
103);
104 
105// With arrays
106server.tool(
107  { name: "list-todos", schema: z.object({}) },
108  async () => {
109    const todos = await getTodos();
110 
111    return object({
112      total: todos.length,
113      items: todos.map(t => ({
114        id: t.id,
115        title: t.title,
116        completed: t.completed,
117        dueDate: t.dueDate
118      }))
119    });
120  }
121);
122```
123 
124**Use for:**
125- Structured data
126- Lists and arrays
127- Nested objects
128- Data that AI needs to parse
129 
130---
131 
132## markdown()
133 
134Formatted text with markdown syntax. Great for documentation, reports, explanations.
135 
136```typescript
137import { markdown } from "mcp-use/server";
138 
139server.tool(
140  { name: "generate-report", schema: z.object({ data: z.array(z.any()) }) },
141  async ({ data }) => {
142    return markdown(`
143# Daily Report
144 
145## Summary
146Total items processed: ${data.length}
147 
148## Breakdown
149| Category | Count |
150|----------|-------|
151| Success  | ${data.filter(d => d.status === "ok").length} |
152| Failed   | ${data.filter(d => d.status === "error").length} |
153 
154## Details
155${data.map(d => `- **${d.id}**: ${d.message}`).join('\n')}
156 
157---
158*Generated at ${new Date().toISOString()}*
159    `);
160  }
161);
162 
163// Code examples in markdown
164server.tool(
165  { name: "explain-function", schema: z.object({ name: z.string() }) },
166  async ({ name }) => {
167    return markdown(`
168# ${name}() Function
169 
170## Usage
171\`\`\`typescript
172const result = await ${name}(params);
173\`\`\`
174 
175## Description
176This function performs...
177 
178## Parameters
179- \`params\` - Configuration object
180 
181## Returns
182Returns a Promise that resolves to...
183    `);
184  }
185);
186```
187 
188**Use for:**
189- Documentation
190- Formatted reports
191- Explanations with structure
192- Code examples
193- Rich text output
194 
195---
196 
197## image()
198 
199Embed images in responses. Supports URLs or base64 data.
200 
201```typescript
202import { image } from "mcp-use/server";
203 
204// Image from URL
205server.tool(
206  { name: "get-chart", schema: z.object({ data: z.array(z.number()) }) },
207  async ({ data }) => {
208    const chartUrl = await generateChart(data);
209    return image(chartUrl);
210  }
211);
212 
213// Base64 image
214server.tool(
215  { name: "generate-qr", schema: z.object({ text: z.string() }) },
216  async ({ text }) => {
217    const qrCodeBase64 = await generateQRCode(text);
218    return image(`data:image/png;base64,${qrCodeBase64}`);
219  }
220);
221 
222// Image with MIME type
223server.tool(
224  { name: "get-diagram", schema: z.object({ id: z.string() }) },
225  async ({ id }) => {
226    const diagramUrl = await getDiagram(id);
227    return image(diagramUrl, "image/svg+xml");
228  }
229);
230```
231 
232**Use for:**
233- Charts and graphs
234- QR codes
235- Diagrams
236- Generated images
237- Visual output
238 
239---
240 
241## error()
242 
243Error responses. Always use this instead of throwing exceptions.
244 
245```typescript
246import { error } from "mcp-use/server";
247 
248server.tool(
249  { name: "fetch-data", schema: z.object({ id: z.string() }) },
250  async ({ id }) => {
251    try {
252      const data = await fetchData(id);
253 
254      if (!data) {
255        return error(`No data found for ID: ${id}`);
256      }
257 
258      return object(data);
259    } catch (err) {
260      return error(
261        `Failed to fetch data: ${err instanceof Error ? err.message : "Unknown error"}`
262      );
263    }
264  }
265);
266 
267// Multiple error cases
268server.tool(
269  { name: "update-user", schema: z.object({ id: z.string(), name: z.string() }) },
270  async ({ id, name }) => {
271    const user = await getUser(id);
272 
273    if (!user) {
274      return error(`User not found: ${id}`);
275    }
276 
277    if (!name.trim()) {
278      return error("Name cannot be empty");
279    }
280 
281    await updateUser(id, { name });
282    return text("User updated successfully");
283  }
284);
285```
286 
287**Use for:**
288- Validation errors
289- Not found errors
290- Permission errors
291- Operation failures
292 
293---
294 
295## widget()
296 
297Return visual UI alongside data. Tool must have `widget: { name }` config.
298 
299```typescript
300import { widget, text } from "mcp-use/server";
301 
302server.tool(
303  {
304    name: "search-products",
305    description: "Search products by query",
306    schema: z.object({
307      query: z.string().describe("Search query")
308    }),
309    widget: {
310      name: "product-list",  // Must match resources/product-list.tsx
311      invoking: "Searching...",
312      invoked: "Products loaded"
313    }
314  },
315  async ({ query }) => {
316    const products = await searchProducts(query);
317 
318    return widget({
319      props: {
320        products,
321        query,
322        totalCount: products.length
323      },
324      output: text(`Found ${products.length} products matching "${query}"`)
325    });
326  }
327);
328```
329 
330**Widget response structure:**
331- `props` - Data sent to widget component
332- `output` - Text/object the AI model sees
333 
334**Use for:**
335- Browsing lists
336- Comparing items
337- Interactive selection
338- Visual data representation
339 
340See [../widgets/basics.md](../widgets/basics.md) for widget implementation.
341 
342---
343 
344## mix()
345 
346Combine multiple content types in a single response.
347 
348```typescript
349import { mix, text, image, markdown } from "mcp-use/server";
350 
351server.tool(
352  { name: "generate-report", schema: z.object({ id: z.string() }) },
353  async ({ id }) => {
354    const report = await getReport(id);
355    const chartUrl = await generateChart(report.data);
356 
357    return mix(
358      markdown(`# Report: ${report.title}\n\n${report.summary}`),
359      image(chartUrl),
360      text(`Generated at ${new Date().toISOString()}`)
361    );
362  }
363);
364 
365// Text + structured data
366server.tool(
367  { name: "analyze-code", schema: z.object({ code: z.string() }) },
368  async ({ code }) => {
369    const analysis = await analyzeCode(code);
370 
371    return mix(
372      text(`Analysis complete. Found ${analysis.issues.length} issues.`),
373      object({
374        complexity: analysis.complexity,
375        issues: analysis.issues,
376        suggestions: analysis.suggestions
377      })
378    );
379  }
380);
381```
382 
383**Use for:**
384- Rich responses with multiple formats
385- Text + image combinations
386- Summary + detailed data
387- Multiple related pieces of content
388 
389---
390 
391## Embedding Resources
392 
393Reference resources in tool responses:
394 
395```typescript
396import { text, resource } from "mcp-use/server";
397 
398server.tool(
399  { name: "get-help", schema: z.object({ topic: z.string() }) },
400  async ({ topic }) => {
401    return mix(
402      text(`Help documentation for: ${topic}`),
403      resource(`docs://${topic}`, "text/markdown")
404    );
405  }
406);
407```
408 
409---
410 
411## Response Patterns
412 
413### Success with Data
414```typescript
415return object({
416  success: true,
417  data: { ... },
418  message: "Operation completed successfully"
419});
420```
421 
422### Success with Message
423```typescript
424return text("User created successfully");
425```
426 
427### Not Found
428```typescript
429if (!item) {
430  return error(`Item not found: ${id}`);
431}
432```
433 
434### Validation Error
435```typescript
436if (!email.includes("@")) {
437  return error("Invalid email address");
438}
439```
440 
441### Server Error
442```typescript
443try {
444  // ... operation
445} catch (err) {
446  console.error("Operation failed:", err);
447  return error("Operation failed. Please try again.");
448}
449```
450 
451---
452 
453## Complete Example
454 
455```typescript
456import {
457  MCPServer,
458  text,
459  object,
460  markdown,
461  image,
462  error,
463  widget,
464  mix
465} from "mcp-use/server";
466import { z } from "zod";
467 
468const server = new MCPServer({
469  name: "response-examples",
470  version: "1.0.0"
471});
472 
473// Simple text
474server.tool(
475  { name: "greet", schema: z.object({ name: z.string() }) },
476  async ({ name }) => text(`Hello, ${name}!`)
477);
478 
479// Structured data
480server.tool(
481  { name: "get-stats", schema: z.object({}) },
482  async () => object({
483    users: 1523,
484    active: 342,
485    growth: "+12%"
486  })
487);
488 
489// Markdown report
490server.tool(
491  { name: "daily-summary", schema: z.object({}) },
492  async () => markdown(`
493# Daily Summary
494 
495## Metrics
496- **Users**: 1,523
497- **Revenue**: $4,231
498- **Orders**: 87
499 
500## Top Products
5011. Widget Pro
5022. Gadget Plus
5033. Tool Kit
504  `)
505);
506 
507// Error handling
508server.tool(
509  { name: "fetch-item", schema: z.object({ id: z.string() }) },
510  async ({ id }) => {
511    try {
512      const item = await db.get(id);
513 
514      if (!item) {
515        return error(`Item not found: ${id}`);
516      }
517 
518      return object(item);
519    } catch (err) {
520      return error("Database error");
521    }
522  }
523);
524 
525// Mixed content
526server.tool(
527  { name: "analyze", schema: z.object({ data: z.array(z.number()) }) },
528  async ({ data }) => {
529    const stats = calculateStats(data);
530    const chartUrl = await generateChart(data);
531 
532    return mix(
533      markdown(`## Analysis Results\n\nProcessed ${data.length} data points`),
534      object(stats),
535      image(chartUrl)
536    );
537  }
538);
539 
540// Widget response
541server.tool(
542  {
543    name: "browse-items",
544    schema: z.object({ category: z.string() }),
545    widget: { name: "item-browser" }
546  },
547  async ({ category }) => {
548    const items = await getItems(category);
549 
550    return widget({
551      props: { items, category },
552      output: text(`Found ${items.length} items in ${category}`)
553    });
554  }
555);
556 
557server.listen();
558```
559 
560---
561 
562## Best Practices
563 
564### 1. Always Use Helpers
565```typescript
566❌ return { data: "value" };
567✅ return object({ data: "value" });
568```
569 
570### 2. Match Helper to Content
571```typescript
572✅ text("Simple message")
573✅ object({ structured: "data" })
574✅ markdown("# Formatted text")
575✅ error("Error message")
576```
577 
578### 3. Handle Errors Gracefully
579```typescript
580✅ return error("User not found: userId_123");
581❌ throw new Error("Raw exception");
582```
583 
584### 4. Provide Context in Errors
585```typescript
586✅ error(`User not found: ${userId}`);
587✅ error(`Invalid email format: ${email}`);
588❌ error("Error");
589```
590 
591### 5. Use Markdown for Rich Content
592```typescript
593✅ markdown(`# Title\n\n- Point 1\n- Point 2`);
594❌ text("Title\nPoint 1\nPoint 2");  // No formatting
595```
596 
597### 6. Widget Output is for AI
598```typescript
599return widget({
600  props: { /* visual data */ },
601  output: text("Concise summary for AI")  // AI only sees this
602});
603```
604 
605---
606 
607## Response Helper Reference
608 
609| Helper | Returns | Use For | Example |
610|--------|---------|---------|---------|
611| `text(string)` | Plain text | Simple messages | `text("Hello")` |
612| `object(any)` | JSON | Structured data | `object({ id: 1 })` |
613| `markdown(string)` | Formatted text | Documentation, reports | `markdown("# Title")` |
614| `image(url, mime?)` | Image | Charts, diagrams | `image(url)` |
615| `error(msg)` | Error | Failures | `error("Not found")` |
616| `widget(config)` | UI + data | Visual interfaces | `widget({ props, output })` |
617| `mix(...results)` | Multiple | Rich responses | `mix(text(), image())` |
618| `resource(uri, mime)` | Resource ref | Embed resources | `resource("docs://guide", "text/markdown")` |
619 
620---
621 
622## Next Steps
623 
624- **Create tools** → [tools.md](tools.md)
625- **Add resources** → [resources.md](resources.md)
626- **Build widgets** → [../widgets/basics.md](../widgets/basics.md)
627- **See examples** → [../patterns/common-patterns.md](../patterns/common-patterns.md)
628