工具
错误与缓存
工具处理器中的 H3 和普通错误，以及基于 Nitro 的响应缓存。
错误处理
直接从你的处理器中抛出错误——就像在 Nitro 事件处理器中一样。抛出的错误会被自动捕获并转换为符合 MCP 规范的 isError 结果。
H3 错误（推荐）
对带有状态码的错误使用 H3 的 createError()：
server/mcp/tools/get-user.ts
import { z } from 'zod'
import { createError } from 'h3'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpTool({
name: 'get-user',
description: '通过 ID 获取用户',
inputSchema: {
id: z.string(),
},
handler: async ({ id }) => {
const user = await findUser(id)
if (!user) {
throw createError({ statusCode: 404, message: '未找到用户' })
}
return user
},
})
// 错误结果: { isError: true, content: [{ type: 'text', text: '[404] 未找到用户' }] }
H3 错误也可以包含结构化数据：
throw createError({
statusCode: 400,
message: '验证失败',
data: { fields: ['name', 'email'] },
})
// 错误文本: '[400] 验证失败\n{ "fields": ["name", "email"] }'
普通错误
常规的 Error 实例也可以正常使用：
server/mcp/tools/safe-divide.ts
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpTool({
name: 'safe-divide',
inputSchema: {
a: z.number(),
b: z.number(),
},
handler: async ({ a, b }) => {
if (b === 0) throw new Error('除数不能为零')
return a / b
},
})
响应缓存
你可以使用 Nitro 的缓存系统来缓存工具响应。cache 选项接受三种格式：
简单时长
使用字符串时长（由 ms 解析）或以毫秒为单位的数字：
server/mcp/tools/cached-data.ts
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpTool({
description: '获取带有 1 小时缓存的数据',
inputSchema: {
id: z.string(),
},
cache: '1h', // 或 '30m'、'2 days'、3600000 等
handler: async ({ id }) => {
return await fetchExpensiveData(id)
},
})
完整缓存选项
如需更多控制，请使用包含所有 Nitro 缓存选项的对象：
server/mcp/tools/cached-pages.ts
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpTool({
description: '获取带自定义缓存键的页面',
inputSchema: {
path: z.string(),
},
cache: {
maxAge: '1h',
getKey: args => `page-${args.path}`,
swr: true, // 陈旧时重新验证
},
handler: async ({ path }) => {
// ...
},
})
缓存选项参考
| Option | Type | Required | Description |
|---|---|---|---|
maxAge | string | number | Yes | 缓存持续时间（例如：'1h'、3600000） |
getKey | (args) => string | No | 自定义缓存键生成器 |
staleMaxAge | number | No | 陈旧时重新验证的持续时间 |
swr | boolean | No | 启用陈旧时重新验证（默认 false，见下方警告） |
name | string | No | 缓存名称（根据工具名称自动生成） |
group | string | No | 缓存分组（默认：'mcp'） |
有关所有可用选项，请参阅 Nitro 缓存文档。
swr 默认为 false（而 Nitro 本身默认为 true）。当 swr: true 时，过期命中会立即返回，并且处理器会在请求响应后于后台刷新，因此请求作用域内的写入（结构化日志、跟踪）可能会被丢弃。只有在你接受这种权衡时才启用。