1# Prompts
2 
3Prompts are reusable message templates with parameters that help structure AI interactions.
4 
5**Use prompts for:** Code review templates, summarization patterns, translation templates, instruction templates
6 
7---
8 
9## Basic Prompt
10 
11```typescript
12import { MCPServer, text } from "mcp-use/server";
13import { z } from "zod";
14 
15const server = new MCPServer({
16  name: "my-server",
17  version: "1.0.0"
18});
19 
20server.prompt(
21  {
22    name: "code-review",
23    description: "Generate a code review prompt for given language",
24    schema: z.object({
25      language: z.string().describe("Programming language (e.g., 'TypeScript', 'Python')"),
26      focusArea: z.string().optional().describe("Specific area to focus on (e.g., 'security', 'performance')")
27    })
28  },
29  async ({ language, focusArea }) => {
30    const focus = focusArea ? ` with emphasis on ${focusArea}` : "";
31 
32    return text(
33      `Please review this ${language} code for best practices and potential issues${focus}.\n\n` +
34      `Consider:\n` +
35      `- Code quality and readability\n` +
36      `- Potential bugs or edge cases\n` +
37      `- Performance implications\n` +
38      `- Security vulnerabilities\n` +
39      `- Adherence to ${language} idioms`
40    );
41  }
42);
43```
44 
45**Key points:**
46- First argument: prompt configuration (name, description, schema)
47- Second argument: async handler that returns prompt text
48- Handler receives validated input matching schema
49- Returns `text()` or `markdown()` helper with prompt content
50 
51---
52 
53## Prompt Definition
54 
55### Name
56Use kebab-case, descriptive names:
57```typescript
58✅ "code-review"
59✅ "summarize-document"
60✅ "translate-text"
61✅ "explain-concept"
62 
63❌ "prompt1"
64❌ "review"  // Too vague
65```
66 
67### Description
68Explain what the prompt template does:
69```typescript
70✅ "Generate a code review prompt for any programming language with optional focus areas"
71✅ "Create a translation prompt from source to target language"
72✅ "Build a summarization prompt with configurable length and style"
73 
74❌ "Code review"  // Not descriptive enough
75```
76 
77### Schema
78Define parameters with Zod, always use `.describe()`:
79 
80```typescript
81// ✅ Good
82z.object({
83  language: z.string().describe("Programming language to review"),
84  focusArea: z.enum(["security", "performance", "style", "bugs"])
85    .optional()
86    .describe("Specific aspect to focus on"),
87  severity: z.enum(["all", "critical", "major"])
88    .default("all")
89    .describe("Minimum issue severity to report")
90})
91 
92// ❌ Bad - no descriptions
93z.object({
94  language: z.string(),
95  focusArea: z.string().optional()
96})
97```
98 
99---
100 
101## Common Prompt Patterns
102 
103### Code Review
104 
105```typescript
106server.prompt(
107  {
108    name: "code-review",
109    description: "Generate code review instructions",
110    schema: z.object({
111      language: z.string().describe("Programming language"),
112      style: z.enum(["strict", "moderate", "lenient"]).optional().describe("Review strictness")
113    })
114  },
115  async ({ language, style = "moderate" }) => {
116    const strictness = {
117      strict: "Be thorough and point out all issues, including minor style problems.",
118      moderate: "Focus on significant issues and best practices.",
119      lenient: "Only highlight critical bugs and security issues."
120    };
121 
122    return text(
123      `Review this ${language} code.\n\n` +
124      `${strictness[style]}\n\n` +
125      `Check for:\n` +
126      `- Correctness and potential bugs\n` +
127      `- Security vulnerabilities\n` +
128      `- Performance issues\n` +
129      `- Code clarity and maintainability`
130    );
131  }
132);
133```
134 
135### Summarization
136 
137```typescript
138server.prompt(
139  {
140    name: "summarize",
141    description: "Create a summarization prompt",
142    schema: z.object({
143      length: z.enum(["brief", "medium", "detailed"]).describe("Summary length"),
144      format: z.enum(["paragraph", "bullets", "outline"]).describe("Output format")
145    })
146  },
147  async ({ length, format }) => {
148    const lengthGuide = {
149      brief: "2-3 sentences",
150      medium: "1 paragraph (5-7 sentences)",
151      detailed: "2-3 paragraphs with key points"
152    };
153 
154    const formatGuide = {
155      paragraph: "as a cohesive paragraph",
156      bullets: "as bullet points",
157      outline: "as a hierarchical outline"
158    };
159 
160    return text(
161      `Summarize the following content in ${lengthGuide[length]} ` +
162      `${formatGuide[format]}.\n\n` +
163      `Focus on the main points and key takeaways.`
164    );
165  }
166);
167```
168 
169### Translation
170 
171```typescript
172server.prompt(
173  {
174    name: "translate",
175    description: "Generate translation instructions",
176    schema: z.object({
177      sourceLang: z.string().describe("Source language"),
178      targetLang: z.string().describe("Target language"),
179      tone: z.enum(["formal", "casual", "technical"]).optional().describe("Translation tone")
180    })
181  },
182  async ({ sourceLang, targetLang, tone = "formal" }) => {
183    return text(
184      `Translate the following text from ${sourceLang} to ${targetLang}.\n\n` +
185      `Maintain a ${tone} tone.\n` +
186      `Preserve the original meaning and nuance.\n` +
187      `Keep any technical terms or proper nouns intact unless they have established translations.`
188    );
189  }
190);
191```
192 
193### Explanation
194 
195```typescript
196server.prompt(
197  {
198    name: "explain-concept",
199    description: "Generate explanation instructions for technical concepts",
200    schema: z.object({
201      concept: z.string().describe("Concept to explain"),
202      audience: z.enum(["beginner", "intermediate", "expert"]).describe("Target audience"),
203      includeExamples: z.boolean().default(true).describe("Include code examples")
204    })
205  },
206  async ({ concept, audience, includeExamples }) => {
207    const audienceLevel = {
208      beginner: "someone new to programming",
209      intermediate: "a developer with 1-2 years experience",
210      expert: "an experienced software engineer"
211    };
212 
213    let prompt = `Explain ${concept} to ${audienceLevel[audience]}.\n\n`;
214 
215    if (includeExamples) {
216      prompt += `Include practical code examples.\n`;
217    }
218 
219    prompt += `Use clear language and avoid unnecessary jargon.`;
220 
221    return text(prompt);
222  }
223);
224```
225 
226---
227 
228## Markdown Prompts
229 
230For longer, structured prompts use `markdown()`:
231 
232```typescript
233import { markdown } from "mcp-use/server";
234 
235server.prompt(
236  {
237    name: "api-design-review",
238    description: "Generate comprehensive API design review prompt",
239    schema: z.object({
240      apiType: z.enum(["REST", "GraphQL", "gRPC"]).describe("API type")
241    })
242  },
243  async ({ apiType }) => {
244    return markdown(`
245# ${apiType} API Design Review
246 
247Please review this ${apiType} API design for the following aspects:
248 
249## 1. Design Quality
250- RESTful principles (if REST)
251- Resource naming and structure
252- Consistency across endpoints
253- Use of HTTP methods appropriately
254 
255## 2. Security
256- Authentication/authorization strategy
257- Input validation
258- Rate limiting considerations
259- Sensitive data handling
260 
261## 3. Performance
262- Pagination strategy
263- Caching headers
264- Payload size optimization
265- N+1 query prevention
266 
267## 4. Developer Experience
268- Clear, predictable patterns
269- Good error messages
270- Comprehensive examples
271- Documentation clarity
272 
273## 5. Versioning & Evolution
274- Versioning strategy
275- Backward compatibility
276- Deprecation plan
277 
278Please provide specific, actionable feedback with examples.
279    `);
280  }
281);
282```
283 
284---
285 
286## Dynamic Prompts
287 
288Build prompts that adapt based on context:
289 
290```typescript
291server.prompt(
292  {
293    name: "debug-help",
294    description: "Generate debugging assistance prompt",
295    schema: z.object({
296      errorType: z.string().describe("Type of error (e.g., 'TypeError', 'NetworkError')"),
297      language: z.string().describe("Programming language"),
298      hasStackTrace: z.boolean().describe("Whether a stack trace is available")
299    })
300  },
301  async ({ errorType, language, hasStackTrace }) => {
302    let prompt = `Help me debug this ${errorType} in ${language}.\n\n`;
303 
304    if (hasStackTrace) {
305      prompt += `I have a stack trace. Please:\n`;
306      prompt += `1. Identify the root cause from the stack trace\n`;
307      prompt += `2. Explain why this error occurred\n`;
308      prompt += `3. Suggest fixes with code examples\n`;
309    } else {
310      prompt += `I don't have a full stack trace. Please:\n`;
311      prompt += `1. Ask questions to narrow down the issue\n`;
312      prompt += `2. Suggest common causes of ${errorType}\n`;
313      prompt += `3. Recommend debugging steps\n`;
314    }
315 
316    return text(prompt);
317  }
318);
319```
320 
321---
322 
323## Multi-Step Prompts
324 
325Chain multiple prompts for complex workflows:
326 
327```typescript
328server.prompt(
329  {
330    name: "refactor-guide",
331    description: "Generate step-by-step refactoring instructions",
332    schema: z.object({
333      codeSmell: z.string().describe("Type of code smell to address"),
334      safetyLevel: z.enum(["aggressive", "moderate", "conservative"]).describe("Refactoring approach")
335    })
336  },
337  async ({ codeSmell, safetyLevel }) => {
338    const steps = {
339      aggressive: [
340        "Identify all instances of the code smell",
341        "Propose bold refactoring that may require significant changes",
342        "Show before/after code",
343        "List breaking changes"
344      ],
345      moderate: [
346        "Identify the code smell",
347        "Propose incremental improvements",
348        "Show refactoring steps",
349        "Ensure backward compatibility"
350      ],
351      conservative: [
352        "Identify the code smell",
353        "Propose minimal, safe changes",
354        "Preserve existing behavior exactly",
355        "Add tests before refactoring"
356      ]
357    };
358 
359    return text(
360      `Refactor this code to address: ${codeSmell}\n\n` +
361      `Approach: ${safetyLevel}\n\n` +
362      `Follow these steps:\n` +
363      steps[safetyLevel].map((step, i) => `${i + 1}. ${step}`).join('\n')
364    );
365  }
366);
367```
368 
369---
370 
371## Prompt with Context
372 
373Include environmental or system context:
374 
375```typescript
376server.prompt(
377  {
378    name: "optimize-for-runtime",
379    description: "Generate optimization suggestions for specific runtime",
380    schema: z.object({
381      runtime: z.enum(["node", "browser", "edge", "serverless"]).describe("Target runtime"),
382      metric: z.enum(["latency", "throughput", "memory", "cost"]).describe("Optimization goal")
383    })
384  },
385  async ({ runtime, metric }) => {
386    const runtimeContext = {
387      node: "Node.js server environment with access to filesystem and native modules",
388      browser: "Browser environment with limited resources and network constraints",
389      edge: "Edge runtime with fast cold starts but limited execution time",
390      serverless: "Serverless function with cold start concerns and pay-per-invocation pricing"
391    };
392 
393    return text(
394      `Optimize this code for ${runtime} runtime to improve ${metric}.\n\n` +
395      `Context: ${runtimeContext[runtime]}\n\n` +
396      `Consider:\n` +
397      `- ${metric === "latency" ? "Reduce response time" : ""}\n` +
398      `- ${metric === "throughput" ? "Increase requests/second" : ""}\n` +
399      `- ${metric === "memory" ? "Reduce memory footprint" : ""}\n` +
400      `- ${metric === "cost" ? "Minimize execution time and resources" : ""}\n\n` +
401      `Provide specific code changes with explanations.`
402    );
403  }
404);
405```
406 
407---
408 
409## Completion (Autocomplete)
410 
411Add autocomplete suggestions to prompt arguments using `completable()`:
412 
413```typescript
414import { MCPServer, text, completable } from "mcp-use/server";
415import { z } from "zod";
416 
417// Static list of suggestions
418server.prompt(
419  {
420    name: "code-review",
421    schema: z.object({
422      language: completable(z.string().describe("Programming language"), ["python", "typescript", "go", "rust"]),
423      code: z.string().describe("Code to review")
424    })
425  },
426  async ({ language, code }) => text(`Review this ${language} code...`)
427);
428```
429 
430### Dynamic Completion
431 
432Use a callback for suggestions that depend on context or external data:
433 
434```typescript
435server.prompt(
436  {
437    name: "analyze-project",
438    schema: z.object({
439      userId: completable(z.string().describe("User ID"), async (value) => {
440        const users = await fetchUsers();
441        return users.map(u => u.id).filter(id => id.startsWith(value));
442      }),
443      projectId: completable(z.string().describe("Project ID"), async (value, ctx) => {
444        // Use other argument values for contextual suggestions
445        const userId = ctx?.arguments?.userId;
446        const projects = await fetchProjects(userId);
447        return projects.map(p => p.id).filter(id => id.startsWith(value));
448      })
449    })
450  },
451  async ({ userId, projectId }) => text(`Analyzing project ${projectId}...`)
452);
453```
454 
455**Key points:**
456- `completable(schema, values)` — static list, prefix-matched automatically
457- `completable(schema, callback)` — dynamic, receives `(value, ctx)` where `ctx.arguments` has other field values
458- Works with `z.string()`, `z.number()`, and `z.enum()` schemas
459- Clients request suggestions via MCP `completion/complete`
460 
461---
462 
463## Best Practices
464 
465### 1. Clear Instructions
466```typescript
467✅ "Translate the following text from English to Spanish. Maintain formal tone."
468❌ "Translate this."
469```
470 
471### 2. Structured Output
472When you want structured responses, specify format:
473```typescript
474return text(
475  `Review this code and respond in the following format:\n\n` +
476  `## Issues Found\n` +
477  `- [Issue description]\n\n` +
478  `## Suggested Fixes\n` +
479  `- [Fix description with code]\n\n` +
480  `## Severity\n` +
481  `[Critical/Major/Minor]`
482);
483```
484 
485### 3. Provide Context
486Include relevant context in the prompt:
487```typescript
488return text(
489  `You are reviewing ${language} code for a ${projectType} project.\n` +
490  `Team follows ${styleGuide} style guide.\n\n` +
491  `Review the code below...`
492);
493```
494 
495### 4. Be Specific
496```typescript
497✅ "Summarize in 3-5 bullet points, each under 20 words"
498❌ "Summarize briefly"
499```
500 
501---
502 
503## Prompts vs Tools
504 
505**Use a prompt when:**
506- ✅ Providing instructions to the AI
507- ✅ Creating reusable message templates
508- ✅ Structuring AI interactions
509- ✅ No backend logic needed
510 
511**Use a tool when:**
512- ✅ Executing backend actions
513- ✅ Calling APIs or databases
514- ✅ Returning computed data
515- ✅ Has side effects
516 
517**Example:**
518```typescript
519// ✅ Prompt - Just instructions
520server.prompt(
521  { name: "review-code", ... },
522  async ({ language }) => text(`Review this ${language} code...`)
523);
524 
525// ✅ Tool - Executes action
526server.tool(
527  { name: "run-linter", schema: z.object({ file: z.string() }) },
528  async ({ file }) => {
529    const results = await runLinter(file);
530    return object(results);
531  }
532);
533```
534 
535---
536 
537## Complete Example
538 
539```typescript
540import { MCPServer, text, markdown } from "mcp-use/server";
541import { z } from "zod";
542 
543const server = new MCPServer({
544  name: "prompt-server",
545  version: "1.0.0"
546});
547 
548// Simple text prompt
549server.prompt(
550  {
551    name: "explain-error",
552    description: "Generate error explanation prompt",
553    schema: z.object({
554      errorMessage: z.string().describe("The error message"),
555      context: z.string().optional().describe("Additional context")
556    })
557  },
558  async ({ errorMessage, context }) => {
559    let prompt = `Explain this error message in simple terms:\n"${errorMessage}"\n\n`;
560 
561    if (context) {
562      prompt += `Context: ${context}\n\n`;
563    }
564 
565    prompt += `Provide:\n1. What it means\n2. Common causes\n3. How to fix it`;
566 
567    return text(prompt);
568  }
569);
570 
571// Structured markdown prompt
572server.prompt(
573  {
574    name: "pr-review",
575    description: "Generate pull request review checklist",
576    schema: z.object({
577      type: z.enum(["feature", "bugfix", "refactor"]).describe("PR type")
578    })
579  },
580  async ({ type }) => {
581    return markdown(`
582# Pull Request Review Checklist (${type})
583 
584## Code Quality
585- [ ] Code follows project style guide
586- [ ] No unnecessary code duplication
587- [ ] Functions are small and focused
588- [ ] Variable names are clear and descriptive
589 
590## Testing
591- [ ] ${type === "feature" ? "New tests added for new functionality" : ""}
592- [ ] ${type === "bugfix" ? "Regression test added" : ""}
593- [ ] All tests pass
594- [ ] Edge cases covered
595 
596## Documentation
597- [ ] Code comments where necessary
598- [ ] README updated if needed
599- [ ] API docs updated
600 
601## ${type === "feature" ? "Feature Specific" : type === "bugfix" ? "Bug Fix Specific" : "Refactor Specific"}
602${type === "feature" ? "- [ ] Feature flag implemented if needed\n- [ ] Backward compatible" : ""}
603${type === "bugfix" ? "- [ ] Root cause identified\n- [ ] Fix verified in production-like environment" : ""}
604${type === "refactor" ? "- [ ] No behavior changes\n- [ ] Performance impact assessed" : ""}
605    `);
606  }
607);
608 
609server.listen();
610```
611 
612---
613 
614## Next Steps
615 
616- **Format responses** → [response-helpers.md](response-helpers.md)
617- **Create tools** → [tools.md](tools.md)
618- **See examples** → [../patterns/common-patterns.md](../patterns/common-patterns.md)
619