NuxtMCP Toolkit
处理器

示例与路由

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

完整示例

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

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: '获取用户信息',
  inputSchema: {
    userId: z.string(),
  },
  handler: async ({ userId }) => {
    const user = await db.users.find(userId)
    return user
  },
})

const createUserTool = defineMcpTool({
  name: 'create-user',
  description: '创建新用户',
  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: '获取用户操作帮助',
  handler: async () => {
    return {
      messages: [{
        role: 'user',
        content: {
          type: 'text',
          text: '我该如何管理用户？',
        },
      }],
    }
  },
})

// 导出处理器
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          # 迁移处理器
    ├── api-handler.ts        # API 处理器
    ├── admin-handler.ts      # 管理员处理器
    ├── tools/
    │   └── echo.ts           # 默认处理器工具
    ├── resources/
    │   └── readme.ts         # 默认处理器资源
    └── prompts/
        └── greeting.ts       # 默认处理器提示词

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

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/自定义或全局在处理器中定义
名称来自配置自定义或配置处理器名称（必填）
版本来自配置自定义或配置处理器版本

结构与选项

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

分享与实践

跨处理器工具共享、文件布局、使用场景和后续步骤。