处理器
分享与实践
跨处理器工具共享、文件布局、使用场景和后续步骤。
使用场景
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],
})
在处理器之间共享工具
对于任何新处理器，优先使用 多处理器组织 功能（文件夹约定加上
getMcp* 函数形式）。下面的模式仍然完全受支持，适用于显式、手工构建的处理器配置。你可以通过将工具定义导出到单独文件，在处理器之间共享它们：
server/mcp/shared-tools.ts
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'
export const sharedTool = defineMcpTool({
name: 'shared-tool',
description: '一个共享工具',
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 # 默认处理器覆盖（可选）
├── migration.ts # 顶层处理器（默认包含所有工具）
├── tools/ # 默认处理器工具（孤立项）
├── resources/ # 默认处理器资源（孤立项）
├── prompts/ # 默认处理器提示词（孤立项）
└── handlers/ # ✨ 命名处理器文件夹（推荐）
├── admin/
│ ├── index.ts # 必需：defineMcpHandler({ ... })
│ ├── tools/ # 自动附加到 /mcp/admin
│ └── prompts/
└── apps/
├── index.ts
└── tools/ # 自动附加到 /mcp/apps
server/mcp/ 根目录下的 index.ts 会覆盖默认处理器配置。在 handlers/<name>/ 目录中，index.ts 是必需的（即使只有一行：export default defineMcpHandler({})）——它负责注册 /mcp/<name> 路由。最佳实践
- 使用描述性名称：让处理器名称清晰且具体
- 将相关功能分组：把相关的工具/资源放在一起
- 为处理器添加版本：对处理器版本使用语义化版本控制
- 记录处理器：添加注释说明每个处理器的作用
- 保持处理器聚焦：每个处理器都应有明确、单一的目的