Prompts

Prompts are reusable message templates with parameters that help structure AI interactions.

Use prompts for: Code review templates, summarization patterns, translation templates, instruction templates

---

Basic Prompt

import { MCPServer, text } from "mcp-use/server";
import { z } from "zod";

const server = new MCPServer({
  name: "my-server",
  version: "1.0.0",
});

server.prompt(
  {
    name: "code-review",
    description: "Generate a code review prompt for given language",
    schema: z.object({
      language: z
        .string()
        .describe("Programming language (e.g., 'TypeScript', 'Python')"),
      focusArea: z
        .string()
        .optional()
        .describe(
          "Specific area to focus on (e.g., 'security', 'performance')",
        ),
    }),
  },
  async ({ language, focusArea }) => {
    const focus = focusArea ? ` with emphasis on ${focusArea}` : "";

    return text(
      `Please review this ${language} code for best practices and potential issues${focus}.\n\n` +
        `Consider:\n` +
        `- Code quality and readability\n` +
        `- Potential bugs or edge cases\n` +
        `- Performance implications\n` +
        `- Security vulnerabilities\n` +
        `- Adherence to ${language} idioms`,
    );
  },
);

Key points:

• First argument: prompt configuration (name, description, schema)
• Second argument: async handler that returns prompt text
• Handler receives validated input matching schema
• Returns text() or markdown() helper with prompt content

---

Prompt Definition

Name

Use kebab-case, descriptive names:

✅ "code-review"
✅ "summarize-document"
✅ "translate-text"
✅ "explain-concept"

❌ "prompt1"
❌ "review"  // Too vague

Description

Explain what the prompt template does:

✅ "Generate a code review prompt for any programming language with optional focus areas"
✅ "Create a translation prompt from source to target language"
✅ "Build a summarization prompt with configurable length and style"

❌ "Code review"  // Not descriptive enough

Schema

Define parameters with Zod, always use .describe():

// ✅ Good
z.object({
  language: z.string().describe("Programming language to review"),
  focusArea: z
    .enum(["security", "performance", "style", "bugs"])
    .optional()
    .describe("Specific aspect to focus on"),
  severity: z
    .enum(["all", "critical", "major"])
    .default("all")
    .describe("Minimum issue severity to report"),
});

// ❌ Bad - no descriptions
z.object({
  language: z.string(),
  focusArea: z.string().optional(),
});

---

Common Prompt Patterns

Code Review

server.prompt(
  {
    name: "code-review",
    description: "Generate code review instructions",
    schema: z.object({
      language: z.string().describe("Programming language"),
      style: z
        .enum(["strict", "moderate", "lenient"])
        .optional()
        .describe("Review strictness"),
    }),
  },
  async ({ language, style = "moderate" }) => {
    const strictness = {
      strict:
        "Be thorough and point out all issues, including minor style problems.",
      moderate: "Focus on significant issues and best practices.",
      lenient: "Only highlight critical bugs and security issues.",
    };

    return text(
      `Review this ${language} code.\n\n` +
        `${strictness[style]}\n\n` +
        `Check for:\n` +
        `- Correctness and potential bugs\n` +
        `- Security vulnerabilities\n` +
        `- Performance issues\n` +
        `- Code clarity and maintainability`,
    );
  },
);

Summarization

server.prompt(
  {
    name: "summarize",
    description: "Create a summarization prompt",
    schema: z.object({
      length: z
        .enum(["brief", "medium", "detailed"])
        .describe("Summary length"),
      format: z
        .enum(["paragraph", "bullets", "outline"])
        .describe("Output format"),
    }),
  },
  async ({ length, format }) => {
    const lengthGuide = {
      brief: "2-3 sentences",
      medium: "1 paragraph (5-7 sentences)",
      detailed: "2-3 paragraphs with key points",
    };

    const formatGuide = {
      paragraph: "as a cohesive paragraph",
      bullets: "as bullet points",
      outline: "as a hierarchical outline",
    };

    return text(
      `Summarize the following content in ${lengthGuide[length]} ` +
        `${formatGuide[format]}.\n\n` +
        `Focus on the main points and key takeaways.`,
    );
  },
);

Translation

server.prompt(
  {
    name: "translate",
    description: "Generate translation instructions",
    schema: z.object({
      sourceLang: z.string().describe("Source language"),
      targetLang: z.string().describe("Target language"),
      tone: z
        .enum(["formal", "casual", "technical"])
        .optional()
        .describe("Translation tone"),
    }),
  },
  async ({ sourceLang, targetLang, tone = "formal" }) => {
    return text(
      `Translate the following text from ${sourceLang} to ${targetLang}.\n\n` +
        `Maintain a ${tone} tone.\n` +
        `Preserve the original meaning and nuance.\n` +
        `Keep any technical terms or proper nouns intact unless they have established translations.`,
    );
  },
);

Explanation

server.prompt(
  {
    name: "explain-concept",
    description: "Generate explanation instructions for technical concepts",
    schema: z.object({
      concept: z.string().describe("Concept to explain"),
      audience: z
        .enum(["beginner", "intermediate", "expert"])
        .describe("Target audience"),
      includeExamples: z
        .boolean()
        .default(true)
        .describe("Include code examples"),
    }),
  },
  async ({ concept, audience, includeExamples }) => {
    const audienceLevel = {
      beginner: "someone new to programming",
      intermediate: "a developer with 1-2 years experience",
      expert: "an experienced software engineer",
    };

    let prompt = `Explain ${concept} to ${audienceLevel[audience]}.\n\n`;

    if (includeExamples) {
      prompt += `Include practical code examples.\n`;
    }

    prompt += `Use clear language and avoid unnecessary jargon.`;

    return text(prompt);
  },
);

---

Markdown Prompts

For longer, structured prompts use markdown():

import { markdown } from "mcp-use/server";

server.prompt(
  {
    name: "api-design-review",
    description: "Generate comprehensive API design review prompt",
    schema: z.object({
      apiType: z.enum(["REST", "GraphQL", "gRPC"]).describe("API type"),
    }),
  },
  async ({ apiType }) => {
    return markdown(`
# ${apiType} API Design Review

Please review this ${apiType} API design for the following aspects:

## 1. Design Quality
- RESTful principles (if REST)
- Resource naming and structure
- Consistency across endpoints
- Use of HTTP methods appropriately

## 2. Security
- Authentication/authorization strategy
- Input validation
- Rate limiting considerations
- Sensitive data handling

## 3. Performance
- Pagination strategy
- Caching headers
- Payload size optimization
- N+1 query prevention

## 4. Developer Experience
- Clear, predictable patterns
- Good error messages
- Comprehensive examples
- Documentation clarity

## 5. Versioning & Evolution
- Versioning strategy
- Backward compatibility
- Deprecation plan

Please provide specific, actionable feedback with examples.
    `);
  },
);

---

Dynamic Prompts

Build prompts that adapt based on context:

server.prompt(
  {
    name: "debug-help",
    description: "Generate debugging assistance prompt",
    schema: z.object({
      errorType: z
        .string()
        .describe("Type of error (e.g., 'TypeError', 'NetworkError')"),
      language: z.string().describe("Programming language"),
      hasStackTrace: z.boolean().describe("Whether a stack trace is available"),
    }),
  },
  async ({ errorType, language, hasStackTrace }) => {
    let prompt = `Help me debug this ${errorType} in ${language}.\n\n`;

    if (hasStackTrace) {
      prompt += `I have a stack trace. Please:\n`;
      prompt += `1. Identify the root cause from the stack trace\n`;
      prompt += `2. Explain why this error occurred\n`;
      prompt += `3. Suggest fixes with code examples\n`;
    } else {
      prompt += `I don't have a full stack trace. Please:\n`;
      prompt += `1. Ask questions to narrow down the issue\n`;
      prompt += `2. Suggest common causes of ${errorType}\n`;
      prompt += `3. Recommend debugging steps\n`;
    }

    return text(prompt);
  },
);

---

Multi-Step Prompts

Chain multiple prompts for complex workflows:

server.prompt(
  {
    name: "refactor-guide",
    description: "Generate step-by-step refactoring instructions",
    schema: z.object({
      codeSmell: z.string().describe("Type of code smell to address"),
      safetyLevel: z
        .enum(["aggressive", "moderate", "conservative"])
        .describe("Refactoring approach"),
    }),
  },
  async ({ codeSmell, safetyLevel }) => {
    const steps = {
      aggressive: [
        "Identify all instances of the code smell",
        "Propose bold refactoring that may require significant changes",
        "Show before/after code",
        "List breaking changes",
      ],
      moderate: [
        "Identify the code smell",
        "Propose incremental improvements",
        "Show refactoring steps",
        "Ensure backward compatibility",
      ],
      conservative: [
        "Identify the code smell",
        "Propose minimal, safe changes",
        "Preserve existing behavior exactly",
        "Add tests before refactoring",
      ],
    };

    return text(
      `Refactor this code to address: ${codeSmell}\n\n` +
        `Approach: ${safetyLevel}\n\n` +
        `Follow these steps:\n` +
        steps[safetyLevel].map((step, i) => `${i + 1}. ${step}`).join("\n"),
    );
  },
);

---

Prompt with Context

Include environmental or system context:

server.prompt(
  {
    name: "optimize-for-runtime",
    description: "Generate optimization suggestions for specific runtime",
    schema: z.object({
      runtime: z
        .enum(["node", "browser", "edge", "serverless"])
        .describe("Target runtime"),
      metric: z
        .enum(["latency", "throughput", "memory", "cost"])
        .describe("Optimization goal"),
    }),
  },
  async ({ runtime, metric }) => {
    const runtimeContext = {
      node: "Node.js server environment with access to filesystem and native modules",
      browser:
        "Browser environment with limited resources and network constraints",
      edge: "Edge runtime with fast cold starts but limited execution time",
      serverless:
        "Serverless function with cold start concerns and pay-per-invocation pricing",
    };

    return text(
      `Optimize this code for ${runtime} runtime to improve ${metric}.\n\n` +
        `Context: ${runtimeContext[runtime]}\n\n` +
        `Consider:\n` +
        `- ${metric === "latency" ? "Reduce response time" : ""}\n` +
        `- ${metric === "throughput" ? "Increase requests/second" : ""}\n` +
        `- ${metric === "memory" ? "Reduce memory footprint" : ""}\n` +
        `- ${metric === "cost" ? "Minimize execution time and resources" : ""}\n\n` +
        `Provide specific code changes with explanations.`,
    );
  },
);

---

Completion (Autocomplete)

Add autocomplete suggestions to prompt arguments using completable():

import { MCPServer, text, completable } from "mcp-use/server";
import { z } from "zod";

// Static list of suggestions
server.prompt(
  {
    name: "code-review",
    schema: z.object({
      language: completable(z.string().describe("Programming language"), [
        "python",
        "typescript",
        "go",
        "rust",
      ]),
      code: z.string().describe("Code to review"),
    }),
  },
  async ({ language, code }) => text(`Review this ${language} code...`),
);

Dynamic Completion

Use a callback for suggestions that depend on context or external data:

server.prompt(
  {
    name: "analyze-project",
    schema: z.object({
      userId: completable(z.string().describe("User ID"), async (value) => {
        const users = await fetchUsers();
        return users.map((u) => u.id).filter((id) => id.startsWith(value));
      }),
      projectId: completable(
        z.string().describe("Project ID"),
        async (value, ctx) => {
          // Use other argument values for contextual suggestions
          const userId = ctx?.arguments?.userId;
          const projects = await fetchProjects(userId);
          return projects.map((p) => p.id).filter((id) => id.startsWith(value));
        },
      ),
    }),
  },
  async ({ userId, projectId }) => text(`Analyzing project ${projectId}...`),
);

Key points:

• completable(schema, values) — static list, prefix-matched automatically
• completable(schema, callback) — dynamic, receives (value, ctx) where ctx.arguments has other field values
• Works with z.string(), z.number(), and z.enum() schemas
• Clients request suggestions via MCP completion/complete

---

Best Practices

1. Clear Instructions

✅ "Translate the following text from English to Spanish. Maintain formal tone."
❌ "Translate this."

2. Structured Output

When you want structured responses, specify format:

return text(
  `Review this code and respond in the following format:\n\n` +
    `## Issues Found\n` +
    `- [Issue description]\n\n` +
    `## Suggested Fixes\n` +
    `- [Fix description with code]\n\n` +
    `## Severity\n` +
    `[Critical/Major/Minor]`,
);

3. Provide Context

Include relevant context in the prompt:

return text(
  `You are reviewing ${language} code for a ${projectType} project.\n` +
    `Team follows ${styleGuide} style guide.\n\n` +
    `Review the code below...`,
);

4. Be Specific

✅ "Summarize in 3-5 bullet points, each under 20 words"
❌ "Summarize briefly"

---

Prompts vs Tools

Use a prompt when:

• ✅ Providing instructions to the AI
• ✅ Creating reusable message templates
• ✅ Structuring AI interactions
• ✅ No backend logic needed

Use a tool when:

• ✅ Executing backend actions
• ✅ Calling APIs or databases
• ✅ Returning computed data
• ✅ Has side effects

Example:

// ✅ Prompt - Just instructions
server.prompt(
  { name: "review-code", ... },
  async ({ language }) => text(`Review this ${language} code...`)
);

// ✅ Tool - Executes action
server.tool(
  { name: "run-linter", schema: z.object({ file: z.string() }) },
  async ({ file }) => {
    const results = await runLinter(file);
    return object(results);
  }
);

---

Complete Example

import { MCPServer, text, markdown } from "mcp-use/server";
import { z } from "zod";

const server = new MCPServer({
  name: "prompt-server",
  version: "1.0.0",
});

// Simple text prompt
server.prompt(
  {
    name: "explain-error",
    description: "Generate error explanation prompt",
    schema: z.object({
      errorMessage: z.string().describe("The error message"),
      context: z.string().optional().describe("Additional context"),
    }),
  },
  async ({ errorMessage, context }) => {
    let prompt = `Explain this error message in simple terms:\n"${errorMessage}"\n\n`;

    if (context) {
      prompt += `Context: ${context}\n\n`;
    }

    prompt += `Provide:\n1. What it means\n2. Common causes\n3. How to fix it`;

    return text(prompt);
  },
);

// Structured markdown prompt
server.prompt(
  {
    name: "pr-review",
    description: "Generate pull request review checklist",
    schema: z.object({
      type: z.enum(["feature", "bugfix", "refactor"]).describe("PR type"),
    }),
  },
  async ({ type }) => {
    return markdown(`
# Pull Request Review Checklist (${type})

## Code Quality
- [ ] Code follows project style guide
- [ ] No unnecessary code duplication
- [ ] Functions are small and focused
- [ ] Variable names are clear and descriptive

## Testing
- [ ] ${type === "feature" ? "New tests added for new functionality" : ""}
- [ ] ${type === "bugfix" ? "Regression test added" : ""}
- [ ] All tests pass
- [ ] Edge cases covered

## Documentation
- [ ] Code comments where necessary
- [ ] README updated if needed
- [ ] API docs updated

## ${type === "feature" ? "Feature Specific" : type === "bugfix" ? "Bug Fix Specific" : "Refactor Specific"}
${type === "feature" ? "- [ ] Feature flag implemented if needed\n- [ ] Backward compatible" : ""}
${type === "bugfix" ? "- [ ] Root cause identified\n- [ ] Fix verified in production-like environment" : ""}
${type === "refactor" ? "- [ ] No behavior changes\n- [ ] Performance impact assessed" : ""}
    `);
  },
);

server.listen();

---

Next Steps

• Format responses → response-helpers.md
• Create tools → tools.md
• See examples → ../patterns/common-patterns.md