核心概念

处理器 (Handlers)

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

什么是处理器 (Handlers)？

处理器允许你在单个 Nuxt 应用中创建多个 MCP 端点。每个处理器都有自己的路由、名称、版本，并且可以包含专属的工具、资源和提示词集合。

Prompt

使用 @nuxtjs/mcp-toolkit 创建具有专属端点和工具的自定义 MCP 处理器。

- 在 server/mcp/ 根目录下创建 .ts 文件（例如 server/mcp/admin.ts）—— tools/、resources/、prompts/ 等子目录中的文件是定义文件，而非处理器
- 使用 defineMcpHandler（自动导入）并配置 name、route、tools、resources 和 prompts
- 显式设置路由（例如 route: '/mcp/admin'）
- 使用 defineMcpTool 内联定义工具，或导入共享工具
- 通过创建 server/mcp/index.ts 并使用 defineMcpHandler 来覆盖默认处理器
- 添加中间件以实现处理器特定的身份验证或日志记录
- 为每个处理器设置 version 和 browserRedirect

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

在以下场景中非常有用：

将不同的 MCP 功能分离到不同的端点
创建带版本控制的 MCP API
按领域或功能组织工具/资源

默认处理器

默认情况下，该模块会在 /mcp（或你配置的路由）处创建单个 MCP 端点，其中包含 server/mcp/ 目录下的所有工具、资源和提示词。

覆盖默认处理器

你可以通过在 server/mcp/ 中创建 index.ts 文件来覆盖默认处理器的配置：

server/mcp/index.ts

export default defineMcpHandler({
  version: '2.0.0',
  browserRedirect: '/docs',
  // 如果未指定 tools/resources/prompts，则使用全局定义
})

这允许你自定义：

version - 覆盖服务器版本
browserRedirect - 覆盖浏览器重定向 URL
name - 覆盖服务器名称（可选）
tools、resources、prompts - 使用特定定义而非全局定义
middleware - 添加请求拦截以用于身份验证、日志记录等（了解更多）

默认处理器会忽略route 属性。如需更改路由，请在 nuxt.config.ts 中使用 mcp.route。

示例：自定义版本和重定向

server/mcp/index.ts

export default defineMcpHandler({
  name: 'My Documentation MCP',
  version: '1.2.0',
  browserRedirect: '/getting-started',
})

示例：限制暴露的工具

server/mcp/index.ts

import { myTool, anotherTool } from './tools/my-tools'

export default defineMcpHandler({
  // 仅暴露特定工具，而非 server/mcp/tools/ 中的所有工具
  tools: [myTool, anotherTool],
})

自定义处理器

使用 defineMcpHandler 创建自定义处理器：

server/mcp/migration.ts

import { z } from 'zod'
import { defineMcpTool, defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

const migrationTool = defineMcpTool({
  name: 'migrate-v3-to-v4',
  title: 'Migrate v3 to v4',
  description: 'Migrate code from version 3 to version 4',
  inputSchema: {
    code: z.string().describe('The code to migrate'),
  },
  handler: async ({ code }) => {
    return code.replace(/v3/g, 'v4')
  },
})

export default defineMcpHandler({
  name: 'migration',
  version: '0.1.0',
  route: '/mcp/migration',
  tools: [migrationTool],
  browserRedirect: '/',
})

处理器结构

处理器定义包含以下内容：

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

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

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

export default defineMcpHandler({
  name: 'handler-name',
  version: '1.0.0',              // 处理器版本
  route: '/mcp/custom',          // 自定义路由
  browserRedirect: '/',          // 浏览器重定向 URL
  middleware: async (event) => { ... }, // 请求拦截
  tools: [ ... ],                 // 工具数组
  resources: [ ... ],            // 资源数组
  prompts: [ ... ],               // 提示词数组
  experimental_codeMode: true,    // 启用代码模式（实验性）
})

处理器选项

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

`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`（可选）

专属于此处理器的工具定义数组，或根据请求上下文动态返回工具的函数：

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

const tool1 = defineMcpTool({ ... })
const tool2 = defineMcpTool({ ... })

export default defineMcpHandler({
  name: 'custom',
  tools: [tool1, tool2],
})

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

export default defineMcpHandler({
  name: 'custom',
  middleware: async (event) => {
    event.context.user = await getUser(event)
  },
  tools: async (event) => {
    const base = [publicTool]
    if (event.context.user?.role === 'admin') {
      base.push(adminTool)
    }
    return base
  },
})

有关基于身份验证的过滤和 enabled 守卫的详细信息，请参阅动态定义指南。

`resources`（可选）

专属于此处理器的资源定义数组。

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

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

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

`prompts`（可选）

专属于此处理器的提示词定义数组。

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

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

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

完整示例

以下是一个自定义处理器的完整示例：

server/mcp/api-handler.ts

import { z } from 'zod'
import { defineMcpTool, defineMcpResource, defineMcpPrompt, defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

const getUserTool = defineMcpTool({
  name: 'get-user',
  description: 'Get user information',
  inputSchema: {
    userId: z.string(),
  },
  handler: async ({ userId }) => {
    const user = await db.users.find(userId)
    return user
  },
})

const createUserTool = defineMcpTool({
  name: 'create-user',
  description: 'Create a new user',
  inputSchema: {
    name: z.string(),
    email: z.string().email(),
  },
  handler: async ({ name, email }) => {
    const user = await db.users.create({ name, email })
    return `User created: ${user.id}`
  },
})

// 为此处理器定义资源
const userResource = defineMcpResource({
  name: 'user',
  uri: 'api://users/{id}',
  handler: async (uri, variables) => {
    const id = variables.id as string
    const user = await db.users.find(id)
    return {
      contents: [{
        uri: uri.toString(),
        mimeType: 'application/json',
        text: JSON.stringify(user),
      }],
    }
  },
})

// 为此处理器定义提示词
const userPrompt = defineMcpPrompt({
  name: 'user-help',
  description: 'Get help with user operations',
  handler: async () => {
    return {
      messages: [{
        role: 'user',
        content: {
          type: 'text',
          text: 'How can I manage users?',
        },
      }],
    }
  },
})

// 导出处理器
export default defineMcpHandler({
  name: 'api',
  version: '1.0.0',
  route: '/mcp/api',
  tools: [getUserTool, createUserTool],
  resources: [userResource],
  prompts: [userPrompt],
  browserRedirect: '/docs/api',
})

多个处理器

您可以在应用程序中创建多个处理器：

server/
└── mcp/
    ├── migration.ts          # Migration handler
    ├── api-handler.ts        # API handler
    ├── admin-handler.ts      # Admin handler
    ├── tools/
    │   └── echo.ts           # Default handler tools
    ├── resources/
    │   └── readme.ts         # Default handler resources
    └── prompts/
        └── greeting.ts       # Default handler prompts

每个处理器文件都应导出一个默认的处理器定义：

server/mcp/migration.ts

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

export default defineMcpHandler({
  name: 'migration',
  tools: [ ... ],
})

server/mcp/api-handler.ts

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

export default defineMcpHandler({
  name: 'api',
  tools: [ ... ],
})

处理器路由

处理器的 name 决定了它的挂载位置。默认情况下，处理器可通过 /mcp/:name 访问，其中 :name 是处理器的名称：

名称为 name: 'migration' 的处理器 → 挂载于 /mcp/migration
名称为 name: 'api' 的处理器 → 挂载于 /mcp/api
名称为 name: 'admin' 的处理器 → 挂载于 /mcp/admin

您也可以指定自定义路由来覆盖默认路由：

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

export default defineMcpHandler({
  name: 'api',
  route: '/api/mcp/v1', // 自定义路由，替代默认的 /mcp/api
})

默认处理器与自定义处理器

特性	默认处理器	默认处理器覆盖 (`index.ts`)	自定义处理器
路由	`/mcp`（通过配置）	`/mcp`（通过配置）	`/mcp/:name`（或自定义路由）
工具	来自 `server/mcp/tools/`	自定义或全局	在处理器中定义
资源	来自 `server/mcp/resources/`	自定义或全局	在处理器中定义
提示词	来自 `server/mcp/prompts/`	自定义或全局	在处理器中定义
名称	来自配置	自定义或配置	处理器名称（必填）
版本	来自配置	自定义或配置	处理器版本

使用场景

1. 功能分离

将不同的功能分离到不同的处理器中：

server/mcp/user-management.ts

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

export default defineMcpHandler({
  name: 'users',
  tools: [getUserTool, createUserTool, updateUserTool],
})

server/mcp/content-management.ts

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

export default defineMcpHandler({
  name: 'content',
  tools: [createPostTool, updatePostTool, deletePostTool],
})

2. 版本化 API

创建带版本号的处理器：

server/mcp/api-v1.ts

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

export default defineMcpHandler({
  name: 'api-v1',
  version: '1.0.0',
  route: '/api/v1/mcp',
  tools: [ ... ],
})

server/mcp/api-v2.ts

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

export default defineMcpHandler({
  name: 'api-v2',
  version: '2.0.0',
  route: '/api/v2/mcp',
  tools: [ ... ],
})

3. 领域特定处理器

按业务领域进行组织：

server/mcp/ecommerce.ts

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

export default defineMcpHandler({
  name: 'ecommerce',
  tools: [addToCartTool, checkoutTool, getProductsTool],
})

server/mcp/analytics.ts

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

export default defineMcpHandler({
  name: 'analytics',
  tools: [getStatsTool, generateReportTool],
})

在处理器之间共享工具

您可以通过将工具定义导出到单独的文件中，在多个处理器之间共享它们：

server/mcp/shared-tools.ts

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

export const sharedTool = defineMcpTool({
  name: 'shared-tool',
  description: 'A shared tool',
  inputSchema: {
    input: z.string(),
  },
  handler: async ({ input }) => `Shared: ${input}`,
})

server/mcp/handler1.ts

import { sharedTool } from './shared-tools'
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'handler1',
  tools: [sharedTool],
})

server/mcp/handler2.ts

import { sharedTool } from './shared-tools'
import { defineMcpHandler } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpHandler({
  name: 'handler2',
  tools: [sharedTool],
})

文件组织

在 server/mcp/ 目录中组织处理器文件：

server/
└── mcp/
    ├── index.ts              # Default handler override (optional)
    ├── migration.ts          # Custom handler
    ├── api-handler.ts        # Custom handler
    ├── admin.ts              # Custom handler
    ├── shared-tools.ts       # Shared tool definitions
    ├── tools/
    │   └── # Tools for default handler
    ├── resources/
    │   └── # Resources for default handler
    └── prompts/
        └── # Prompts for default handler

index.ts 文件比较特殊——它会覆盖默认处理器的配置，而不是创建一个新的自定义处理器。

最佳实践

使用描述性名称：确保处理器名称清晰且具体
分组相关功能：将相关的工具/资源放在一起
为处理器添加版本：使用语义化版本控制处理器版本
编写处理器文档：添加注释说明每个处理器的作用
保持处理器职责单一：每个处理器应有明确且单一的职责

下一步

代码模式 - 使用 LLM 生成的 JavaScript 编排工具
中间件 - 添加身份验证和日志记录
动态定义 - 有条件地注册定义
配置 - 配置默认处理器
工具 - 为您的处理器创建工具
示例 - 查看更多处理器示例

Edit this pageorReport an issue

提示词 (Prompts)

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

自定义路径

自定义模块查找 MCP 定义的位置。