工具
Schema, handler & returns
使用 Zod 定义工具输入和输出，并从处理器返回文本、结构化数据或媒体。
输入 Schema
inputSchema 是可选的，使用 Zod 来定义和验证输入参数。提供时，每个字段都必须是 Zod schema。没有参数的工具可以完全省略 inputSchema：
server/mcp/tools/echo.ts
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpTool({
name: 'echo',
description: '回显一条消息',
handler: async () => '回显：test',
})
对于带参数的工具，请使用 Zod schema 来定义它们：
server/mcp/tools/calculator.ts
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpTool({
name: 'calculator',
inputSchema: {
// 字符串输入
operation: z.string().describe('要执行的操作'),
// 数字输入
a: z.number().describe('第一个数字'),
b: z.number().describe('第二个数字'),
// 可选字段
precision: z.number().optional().describe('小数精度'),
// 枚举输入
format: z.enum(['decimal', 'fraction']).describe('输出格式'),
// 数组输入
numbers: z.array(z.number()).describe('数字列表'),
},
handler: async ({ operation, a, b, precision, format, numbers }) => {
// 处理器实现
},
})
常见 Zod 类型
| Zod 类型 | 示例 | 描述 |
|---|---|---|
z.string() | z.string().min(1).max(100) | 带校验的字符串 |
z.number() | z.number().min(0).max(100) | 带校验的数字 |
z.boolean() | z.boolean() | 布尔值 |
z.array() | z.array(z.string()) | 值数组 |
z.object() | z.object({ ... }) | 嵌套对象 |
z.enum() | z.enum(['a', 'b']) | 枚举 |
z.optional() | z.string().optional() | 可选字段 |
z.default() | z.string().default('value') | 带默认值的字段 |
输出 Schema
使用 outputSchema 定义结构化输出：
server/mcp/tools/bmi.ts
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpTool({
name: 'calculate-bmi',
description: '计算身体质量指数',
inputSchema: {
weightKg: z.number().describe('体重（千克）'),
heightM: z.number().describe('身高（米）'),
},
outputSchema: {
bmi: z.number(),
category: z.string(),
},
handler: async ({ weightKg, heightM }) => {
const bmi = weightKg / (heightM * heightM)
let category = '正常'
if (bmi < 18.5) category = '偏瘦'
else if (bmi >= 25) category = '超重'
else if (bmi >= 30) category = '肥胖'
return {
structuredContent: {
bmi: Math.round(bmi * 100) / 100,
category,
},
}
},
})
structuredContent 字段提供与 outputSchema 匹配的结构化数据，使 AI 助手更容易处理结果。
处理器函数
处理器是一个异步函数，接收经过验证的输入并返回结果。你可以直接返回简化值——它们会自动包装为 MCP CallToolResult 格式。
简化返回
你可以直接从处理器返回 string、number、boolean、对象或数组：
handler: async ({ name }) => `你好 ${name}`
// → { content: [{ type: 'text', text: '你好 World' }] }
handler: async ({ a, b }) => a + b
// → { content: [{ type: 'text', text: '10' }] }
handler: async ({ id }) => {
const user = await getUser(id)
return user
}
// → { content: [{ type: 'text', text: '{ "id": ... }' }] }
handler: async ({ id }) => await exists(id)
// → { content: [{ type: 'text', text: 'true' }] }
当你需要更多控制时，也可以返回完整的 CallToolResult 格式（例如图片、多条 content 项、structuredContent）。
内容类型
对于高级用例，返回带类型内容的完整 CallToolResult：
return {
content: [{
type: 'image',
data: base64ImageData,
mimeType: 'image/png',
}],
}
return {
structuredContent: {
bmi: 25.5,
category: '正常',
},
}
// 作为旧客户端的回退，文本内容会自动生成
return {
content: [{
type: 'resource',
resource: {
uri: 'file:///path/to/file',
text: '文件内容',
mimeType: 'text/plain',
},
}],
}
结果辅助函数
该模块提供 imageResult 和 audioResult 辅助函数，用于工具响应中的二进制媒体（base64 编码数据加 MIME 类型）：
import { z } from 'zod'
import { defineMcpTool, imageResult, audioResult } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpTool({
description: '生成图表',
inputSchema: { data: z.array(z.number()) },
handler: async ({ data }) => {
const base64 = await generateChart(data)
return imageResult(base64, 'image/png')
},
})
import { z } from 'zod'
import { defineMcpTool, audioResult } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpTool({
description: '文本转语音',
inputSchema: { text: z.string() },
handler: async ({ text }) => {
const base64 = await synthesizeSpeech(text)
return audioResult(base64, 'audio/mp3')
},
})