Prompts

Input, handler & messages

Zod arguments, handler return types, roles, and multi-message prompts.

Input Schema

Use Zod to define and validate prompt arguments:

server/mcp/prompts/translate.ts

import { z } from 'zod'
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  name: 'translate',
  inputSchema: {
    // Required string argument
    text: z.string().describe('Text to translate'),

    // Required enum argument
    targetLanguage: z.enum(['en', 'fr', 'es', 'de']).describe('Target language'),

    // Optional argument
    sourceLanguage: z.string().optional().describe('Source language (auto-detect if not provided)'),

    // Optional with default
    formality: z.enum(['formal', 'informal']).default('formal'),
  },
  handler: async ({ text, targetLanguage, sourceLanguage, formality }) => {
    // Implementation
  },
})

Common Argument Types

Zod Type	Example	Description
`z.string()`	`z.string().min(1)`	String with validation
`z.enum()`	`z.enum(['a', 'b'])`	Enumeration
`z.optional()`	`z.string().optional()`	Optional field
`z.default()`	`z.string().default('value')`	Field with default

Note: Prompt arguments must be strings. Use z.string() and convert to other types in your handler if needed.

Argument Autocompletion

Wrap a schema field with completable() to provide autocompletion suggestions when clients fill in prompt arguments:

server/mcp/prompts/review-code.ts

export default defineMcpPrompt({
  description: 'Review code for best practices',
  inputSchema: {
    language: completable(
      z.string().describe('Programming language'),
      value => ['typescript', 'javascript', 'python', 'rust', 'go']
        .filter(lang => lang.startsWith(value)),
    ),
  },
  handler: async ({ language }) => {
    return `Review the following ${language} code for best practices and potential issues.`
  },
})

The completable helper is auto-imported and re-exported from the MCP SDK. The callback receives the current input value and returns matching suggestions.

Handler Function

The handler receives validated arguments (if inputSchema is provided) and returns a prompt result.

Return Types

Handlers support two return types:

// Return a string — auto-wrapped into a single user message
handler: async () => 'You are a helpful assistant.'

// With arguments
handler: async ({ topic }) => `Help me understand ${topic}.`

// Return the full MCP result for multi-message or assistant-role prompts
handler: async () => ({
  messages: [
    { role: 'user', content: { type: 'text', text: 'Review this code.' } },
    { role: 'assistant', content: { type: 'text', text: 'I will review it.' } },
  ],
})

When returning a string, it is automatically wrapped into { messages: [{ role, content: { type: 'text', text: '...' } }] } using the role option (defaults to 'user').

Handler Arguments

// Without inputSchema — no arguments
handler: async () => 'Message text'

// With inputSchema — receives validated arguments
handler: async (args, extra) => {
  // args: Validated arguments matching inputSchema
  // extra: Request handler extra information
  return `Message with ${args.param}`
}

Message Roles

Prompts can return messages with different roles:

return {
  messages: [{
    role: 'user',
    content: {
      type: 'text',
      text: 'User message with instructions',
    },
  }],
}

return {
  messages: [{
    role: 'assistant',
    content: {
      type: 'text',
      text: 'Pre-filled assistant response',
    },
  }],
}

Note: The MCP specification only supports user and assistant roles. To provide context or instructions, include them in the user message text.

Multiple Messages

Return multiple messages to create a conversation flow:

server/mcp/prompts/conversation.ts

import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpPrompt({
  name: 'conversation-starter',
  inputSchema: {
    topic: z.string().describe('Conversation topic'),
  },
  handler: async ({ topic }) => {
    return {
      messages: [
        {
          role: 'user',
          content: {
            type: 'text',
            text: `You are a helpful assistant. Let's discuss ${topic}.`,
          },
        },
        {
          role: 'assistant',
          content: {
            type: 'text',
            text: `I'd be happy to discuss ${topic} with you.`,
          },
        },
      ],
    }
  },
})

Edit this pageorReport an issue

Authoring & structure

Names, roles, arguments, and the shape of a prompt definition.

Patterns & advanced

Real-world examples, organization, type safety, best practices, and conditional registration.