NuxtMCP Toolkit
处理器

结构与选项

必填字段以及 defineMcpHandler 的每个选项，包括 tools、resources 和 prompts。

处理器结构

一个处理器定义由以下内容组成：

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

export default defineMcpHandler({
  name: 'handler-name',  // 唯一标识符
})

处理器选项

name（必需）

处理器的唯一标识符。name 决定处理器将挂载到哪里。默认情况下，处理器可通过 /mcp/:name 访问。

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

export default defineMcpHandler({
  name: 'migration', // 处理器挂载在 /mcp/migration
})

version（可选）

处理器的版本。默认为模块配置的版本。

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

export default defineMcpHandler({
  name: 'migration',
  version: '2.0.0',
})

description（可选）

在 MCP 初始化期间作为 serverInfo 的一部分发送的、人类可读的描述。客户端使用它在 UI 中识别该处理器（服务器列表、安装提示、工具提示）。若未设置，则回退到 nuxt.config.ts 中的 mcp.description。

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

export default defineMcpHandler({
  name: 'admin',
  description: 'Admin tools — destructive operations gated by Bearer auth.',
})

instructions（可选）

面向 AI 代理的操作指导——通常由客户端注入到模型的系统提示中。可用于描述工作流、约束或工具之间的关系（使用 description 来标识处理器）。若未设置，则回退到 nuxt.config.ts 中的 mcp.instructions。

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

export default defineMcpHandler({
  name: 'admin',
  instructions: 'Always call list-users before delete-user. Confirm with the operator before any destructive action.',
})

icons（可选）

客户端在其 UI 中显示的图标。每个条目需要 src 和 mimeType，可选 sizes 和 theme（'light' | 'dark'）。若未设置，则回退到 nuxt.config.ts 中的 mcp.icons。

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

export default defineMcpHandler({
  name: 'admin',
  icons: [
    { src: 'https://example.com/admin.png', mimeType: 'image/png', sizes: ['64x64'] },
  ],
})
description、instructions 和 icons 是 MCP 生命周期规范 的一部分。请在模块级别设置它们以共享元数据；当某个特定端点需要不同身份时，可按处理器覆盖。

route（可选）

处理器的自定义路由。默认为 /mcp/:name。

此选项仅用于自定义处理器。对于默认处理器覆盖（index.ts），请改用 nuxt.config.ts 中的 mcp.route。
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'migration',
  route: '/api/mcp/migration', // 自定义路由
})

browserRedirect（可选）

当浏览器访问处理器端点时重定向到的 URL。默认为模块配置的 browserRedirect。

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

export default defineMcpHandler({
  name: 'migration',
  browserRedirect: '/docs/migration',
})

middleware（可选）

在请求处理前后拦截请求的函数。适用于身份验证、日志记录和设置上下文。

server/mcp/custom.ts
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'custom',
  middleware: async (event) => {
    event.context.userId = 'user-123'
  },
})
有关详细文档和示例，请参阅中间件指南。

experimental_codeMode（可选）

启用代码模式，让 LLM 在一次 JavaScript 执行中编排多个工具调用。传入 true 使用默认值，或传入一个选项对象：

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

export default defineMcpHandler({
  name: 'custom',
  experimental_codeMode: {
    progressive: true,
    memoryLimit: 128,
  },
})

代码模式需要 secure-exec 和 Node.js >=18.16.0。

有关完整文档、安全细节和配置选项，请参阅代码模式指南。

tools（可选）

支持三种形式——请选择最符合你使用场景的一种：

// server/mcp/handlers/admin/index.ts
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

// `tools` 省略 → handlers/admin/tools/ 下的每个工具
// 都会自动注册（文件夹约定）。
export default defineMcpHandler({
  middleware: requireAdmin,
})
有关文件夹约定，请参阅多处理器组织；有关临时过滤，请参阅getMcpTools。每个工具的 enabled() 保护都会自动应用——请参阅动态定义。

resources（可选）

与tools相同的形式：省略则使用文件夹约定自动归属，传入数组，或传入 event => getMcpResources({ event, ... })。

import { defineMcpResource, defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

const resource1 = defineMcpResource({ ... })
const resource2 = defineMcpResource({ ... })

export default defineMcpHandler({
  name: 'custom',
  resources: [resource1, resource2],
})

prompts（可选）

与tools相同的形式：省略则使用文件夹约定自动归属，传入数组，或传入 event => getMcpPrompts({ event, ... })。

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

const prompt1 = defineMcpPrompt({ ... })
const prompt2 = defineMcpPrompt({ ... })

export default defineMcpHandler({
  name: 'custom',
  prompts: [prompt1, prompt2],
})

默认与自定义处理器

覆盖默认的 `/mcp` 处理器并添加自定义 defineMcpHandler 端点。

示例与路由

完整的处理器示例、多个处理器、路由，以及默认与自定义的比较。