核心概念

提示词 (Prompts)

为 AI 助手创建可复用的提示词，支持可选参数。

什么是提示词？

提示词是可供 AI 助手使用的可复用消息模板。它们可以包含动态参数，并返回预格式化的消息。

Prompt

使用 @nuxtjs/mcp-toolkit 在我的 Nuxt 应用中创建一个新的 MCP 提示词。

- 在 server/mcp/prompts/ 中创建一个文件（例如 server/mcp/prompts/review-code.ts）
- 使用 defineMcpPrompt（自动导入）并配置 description 和 handler
- handler 可以返回字符串（自动包装为用户消息）或包含 messages 数组的完整 GetPromptResult
- 在 inputSchema 中使用 `import { z } from 'zod'` 定义参数（提示词参数必须为字符串）
- 使用 role 选项（'user' 或 'assistant'）控制字符串返回时的默认角色
- 使用 completable() 为参数提供自动补全建议
- 返回多条消息以创建对话流程
- name 和 title 将根据文件名自动生成
- 在聊天中输入 / 时，提示词会显示在 Cursor 和 VS Code 中

文档：https://mcp-toolkit.nuxt.dev/core-concepts/prompts

为什么使用提示词？

与临时指令相比，MCP 提示词具有多项优势：

可复用性

一次定义，随处使用。在团队间共享提示词，确保 AI 交互的一致性。

标准化

确保代码审查或文档编写等特定任务的格式和上下文保持一致。

可定制性

使用参数使提示词适应不同场景，同时保持结构不变。

IDE 集成

提示词会显示在 Cursor、VS Code 和 Visual Studio 中，便于开发时快速调用。

IDE 集成

MCP 提示词与现代开发环境无缝集成。当您的 MCP 服务器连接后，提示词将直接在 IDE 中可用。

在 Cursor / VS Code 中使用提示词

输入 /：在聊天框中输入 / 即可查看所有可用的 MCP 提示词
选择提示词：从列表中选择（例如 local-mcp/setup-mcp-server）
填写参数：对于提示词模板，将弹出对话框以填写所需参数

自动生成的 Name 和 Title

您可以省略 name 和 title —— 它们将根据文件名自动生成：

server/mcp/prompts/greeting.ts

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

export default defineMcpPrompt({
  // name 和 title 将根据文件名自动生成：
  // name: 'greeting'
  // title: 'Greeting'
  description: 'Generate a personalized greeting message',
  handler: async () => {
    // ...
  },
})

文件名 greeting.ts 将自动转换为：

name: greeting (kebab-case)
title: Greeting (title case)

您仍然可以显式提供 name 或 title 以覆盖自动生成的值。

简单提示词（无参数）

创建不带参数的提示词。Handler 可以返回一个简单的字符串 —— 它将自动包装为单条用户消息：

server/mcp/prompts/greeting.ts

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

export default defineMcpPrompt({
  name: 'greeting',
  title: 'Greeting',
  description: 'Generate a personalized greeting message',
  handler: async () => {
    const hour = new Date().getHours()
    const timeOfDay = hour < 12 ? 'morning' : hour < 18 ? 'afternoon' : 'evening'

    return `Good ${timeOfDay}! How can I help you today?`
  },
})

默认角色

当 handler 返回字符串时，默认会包装为 user 角色。使用 role 选项可更改此行为：

server/mcp/prompts/code-reviewer.ts

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

export default defineMcpPrompt({
  role: 'assistant',
  description: 'Code review assistant persona',
  handler: async () => 'I am a code review assistant. Share your code and I will review it for best practices.',
})

role 选项仅影响字符串返回。当返回完整的 GetPromptResult 时，请直接在 messages 数组中定义角色。

带参数的提示词

创建接受参数的提示词：

server/mcp/prompts/summarize.ts

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

export default defineMcpPrompt({
  name: 'summarize',
  title: 'Text Summarizer',
  description: 'Summarize any text content',
  inputSchema: {
    text: z.string().describe('The text to summarize'),
    maxLength: z.string().optional().describe('Maximum length of summary in words'),
  },
  handler: async ({ text, maxLength }) => {
    const words = text.split(/\s+/)
    const maxWords = maxLength ? Number.parseInt(maxLength) : Math.ceil(words.length * 0.3)
    const summary = words.slice(0, maxWords).join(' ')

    return `Summary (${maxWords} words): ${summary}${words.length > maxWords ? '...' : ''}`
  },
})

提示词结构

提示词定义包含以下部分：

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

export default defineMcpPrompt({
  name: 'prompt-name',  // 唯一标识符
  handler: async () => 'Your prompt text here',
})

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

export default defineMcpPrompt({
  name: 'prompt-name',
  role: 'assistant',             // 字符串返回时的角色（默认：'user'）
  handler: async () => 'I am an assistant persona.',
})

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

export default defineMcpPrompt({
  name: 'prompt-name',
  title: 'Prompt Title',        // 人类可读的标题
  description: 'Description',   // 提示词的作用
  inputSchema: { ... },          // 参数的 Zod 校验规则
  handler: async (args) => {    // 带参数的处理函数
    return `Prompt text with ${args.param}`
  },
})

输入校验规则 (Input Schema)

使用 Zod 定义并校验提示词参数：

server/mcp/prompts/translate.ts

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

export default defineMcpPrompt({
  name: 'translate',
  inputSchema: {
    // 必填字符串参数
    text: z.string().describe('Text to translate'),

    // 必填枚举参数
    targetLanguage: z.enum(['en', 'fr', 'es', 'de']).describe('Target language'),

    // 可选参数
    sourceLanguage: z.string().optional().describe('Source language (auto-detect if not provided)'),

    // 带默认值的可选参数
    formality: z.enum(['formal', 'informal']).default('formal'),
  },
  handler: async ({ text, targetLanguage, sourceLanguage, formality }) => {
    // 实现逻辑
  },
})

常用参数类型

Zod Type	Example	Description
`z.string()`	`z.string().min(1)`	带校验的字符串
`z.enum()`	`z.enum(['a', 'b'])`	枚举类型
`z.optional()`	`z.string().optional()`	可选字段
`z.default()`	`z.string().default('value')`	带默认值的字段

注意：提示词参数必须为字符串。如有需要，请使用 z.string() 并在 handler 中转换为其他类型。

参数自动补全

使用 completable() 包装 schema 字段，以便在客户端填写提示词参数时提供自动补全建议：

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.`
  },
})

completable 辅助函数已自动导入并从 MCP SDK 重新导出。该回调函数接收当前输入值，并返回匹配的建议项。

处理函数 (Handler)

Handler 接收已校验的参数（如果提供了 inputSchema），并返回提示词结果。

返回类型

Handler 支持两种返回类型：

// 返回字符串 —— 自动包装为单条用户消息
handler: async () => 'You are a helpful assistant.'

// 带参数
handler: async ({ topic }) => `Help me understand ${topic}.`

// 返回完整的 MCP 结果，适用于多消息或助手角色提示词
handler: async () => ({
  messages: [
    { role: 'user', content: { type: 'text', text: 'Review this code.' } },
    { role: 'assistant', content: { type: 'text', text: 'I will review it.' } },
  ],
})

返回字符串时，它将使用 role 选项（默认为 'user'）自动包装为 { messages: [{ role, content: { type: 'text', text: '...' } }] }。

Handler 参数

// 无 inputSchema —— 无参数
handler: async () => 'Message text'

// 有 inputSchema —— 接收已校验的参数
handler: async (args, extra) => {
  // args: 与 inputSchema 匹配的已校验参数
  // extra: 请求处理器的额外信息
  return `Message with ${args.param}`
}

消息角色

提示词可以返回具有不同角色的消息：

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

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

注意：MCP 规范仅支持 user 和 assistant 角色。如需提供上下文或指令，请将其包含在 user 消息文本中。

多条消息

返回多条消息以创建对话流：

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.`,
          },
        },
      ],
    }
  },
})

使用场景

Prompt（提示词）特别适用于以下场景：

1. 设置与新手引导

帮助新开发者或 AI 助手了解如何使用你的代码库：

server/mcp/prompts/setup-guide.ts

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

export default defineMcpPrompt({
  description: 'Provide complete setup instructions for this project',
  handler: async () => `You are setting up this Nuxt project. Here's what you need to know:

1. Install dependencies: \`pnpm install\`
2. Start dev server: \`pnpm dev\`
3. Project structure follows Nuxt conventions
4. MCP tools are available in server/mcp/

Ask me what you'd like to build!`,
})

2. 代码审查标准

确保一致的代码审查标准：

server/mcp/prompts/review-standards.ts

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

export default defineMcpPrompt({
  description: 'Apply team code review standards',
  inputSchema: {
    focus: z.enum(['security', 'performance', 'maintainability', 'all']).default('all'),
  },
  handler: async ({ focus }) => `You are a code reviewer following our team standards. Focus on: ${focus}.

Review the code I provide, checking for best practices and potential issues.`,
})

3. 文档生成

标准化文档格式：

server/mcp/prompts/generate-docs.ts

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

export default defineMcpPrompt({
  description: 'Generate documentation in team format',
  inputSchema: {
    type: z.enum(['api', 'component', 'function']).describe('What to document'),
  },
  handler: async ({ type }) => {
    const templates = {
      api: 'Document this API endpoint with: endpoint, method, parameters, response format, and examples.',
      component: 'Document this Vue component with: props, emits, slots, and usage examples.',
      function: 'Document this function with: parameters, return value, and usage examples.',
    }

    return templates[type]
  },
})

4. 故障排查工作流

指导常见问题的调试：

server/mcp/prompts/debug-helper.ts

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

export default defineMcpPrompt({
  description: 'Help debug common issues',
  inputSchema: {
    area: z.enum(['api', 'auth', 'database', 'frontend']).describe('Area of the issue'),
  },
  handler: async ({ area }) => `You are debugging a ${area} issue. Ask clarifying questions and suggest diagnostic steps.`,
})

分组与标签

使用 group 和 tags 对提示词进行分类组织。这些字段的工作方式与工具相同。

server/mcp/prompts/onboarding/setup-guide.ts

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

export default defineMcpPrompt({
  tags: ['getting-started'],
  description: 'Help new developers set up the project',
  handler: async () => 'You are setting up this project...',
})

将文件放置在 prompts/onboarding/ 目录下会自动推断出 group: 'onboarding'。

提示词的 group 和 tags 会存储在定义对象中，但尚未包含在 prompts/list 协议响应中。当 MCP SDK 采纳 SEP-1300 后，将支持此功能。

文件组织

将你的提示词组织在 server/mcp/prompts/ 目录中。支持扁平化和嵌套布局：

server/
└── mcp/
    └── prompts/
        ├── greeting.ts
        ├── summarize.ts
        ├── onboarding/
        │   └── setup-guide.ts
        └── debugging/
            └── troubleshoot.ts

每个文件都应导出一个默认的提示词定义。子目录会自动设置 group。

类型安全

该模块提供完整的 TypeScript 类型推断：

// 参数类型从 inputSchema 推断
handler: async ({ text, maxLength }) => {
  // text 的类型为 string
  // maxLength 的类型为 string | undefined
}

最佳实践

1. 为 AI 理解而设计

编写能为 AI 提供清晰上下文和预期的提示词：

// 良好：清晰的上下文和指令
handler: async ({ code }) =>
  `You are a senior developer reviewing code for a Nuxt application.

Review this code for Vue 3 best practices:\n\n${code}`

// 效果较差：模糊的指令
handler: async ({ code }) => code

2. 使用描述性参数

始终在 Zod 字段上使用 .describe()，以帮助用户和 AI 理解预期内容：

inputSchema: {
  // 良好：清晰的描述
  language: z.enum(['typescript', 'javascript']).describe('Programming language of the code'),
  strict: z.boolean().default(true).describe('Whether to enforce strict TypeScript rules'),

  // 帮助较小：无描述
  lang: z.string(),
  s: z.boolean(),
}

3. 使用对话流

使用 user 和 assistant 消息来引导 AI：

// 有效：用户提供上下文，助手确认
messages: [
  { role: 'user', content: { type: 'text', text: 'You are an expert in accessibility. Review this HTML for a11y issues.' } },
  { role: 'assistant', content: { type: 'text', text: 'I\'ll analyze the HTML for accessibility issues.' } },
]

4. 保持提示词专注

每个提示词应具有单一、明确的目的。创建多个提示词，而不是一个复杂的提示词：

// 良好：分离的专注提示词
// server/mcp/prompts/review-security.ts
// server/mcp/prompts/review-performance.ts
// server/mcp/prompts/review-style.ts

// 可维护性较差：一个试图完成所有任务的复杂提示词

5. 提供默认值

为可选参数使用 .default() 以提高可用性：

inputSchema: {
  format: z.enum(['brief', 'detailed']).default('detailed').describe('Output format'),
  language: z.string().default('en').describe('Response language'),
}

6. 在复杂提示词中包含示例

对于需要特定输出格式的提示词，请包含示例：

handler: async () => `Generate a commit message following this format:

type(scope): description

Example:
feat(auth): add OAuth2 login support

Types: feat, fix, docs, style, refactor, test, chore`

条件注册

你可以使用 enabled 守卫来控制提示词是否对客户端可见：

server/mcp/prompts/admin-prompt.ts

export default defineMcpPrompt({
  name: 'admin-prompt',
  description: 'Admin-only prompt',
  enabled: event => event.context.user?.role === 'admin',
  handler: async () => 'Admin instructions...',
})

有关基于身份验证过滤的详细文档，请参阅动态定义指南。

后续步骤

提示词示例 - 查看高级提示词示例
工具 - 创建工具以执行操作
资源 - 创建资源以暴露数据
处理器 - 创建自定义 MCP 端点
动态定义 - 有条件地注册定义

Edit this pageorReport an issue

资源

将只读数据源公开为 MCP 资源，以便为 AI 模型提供上下文。

处理器 (Handlers)

创建具有专属工具、资源和提示词的自定义 MCP 端点。