进阶主题
使用 TypeScript 增强类型安全
Nuxt MCP 模块中的类型安全和 TypeScript 功能。
类型安全
Nuxt MCP 模块提供完整的 TypeScript 支持，具备全面的类型推断和类型安全。
自动导入
所有辅助函数和类型都会在你的服务器文件中自动导入：
Functions:
defineMcpTool,defineMcpResource,defineMcpPrompt,defineMcpHandler,defineMcpAppimageResult,audioResult(用于工具响应的二进制媒体辅助函数)completable,extractToolNamesuseMcpSession,useMcpServer,useMcpLogger,useMcpElicitation,useMcpApplistMcpTools,listMcpResources,listMcpPrompts,listMcpDefinitionsgetMcpTools,getMcpResources,getMcpPrompts
textResult、jsonResult 和 errorResult 辅助函数已弃用。请直接从你的处理器中返回字符串、数字、布尔值、对象或数组——工具包会自动包装它们。对于错误，请抛出 Error，或使用 h3 中的 createError。请参见 错误与缓存。Types:
McpRequestExtra— 传递给每个工具、提示词和资源处理器的额外参数（中止信号、认证信息、会话 ID、元数据）。等同于 SDK 中的RequestHandlerExtra<ServerRequest, ServerNotification>。McpServerHelper—useMcpServer()的返回类型。McpSessionStore—useMcpSession()返回的带类型存储。McpClientNotifier,McpLogger,McpRequestLogger,McpUserFields,McpSessionFields—useMcpLogger()背后的类型。McpElicitation,ElicitationFormParams,ElicitationFormResult,ElicitationUrlParams,ElicitationUrlResult,ElicitationMode—useMcpElicitation()背后的类型。- 常见的 SDK 协议类型会从单一导入路径重新导出：
Annotations,CallToolResult,GetPromptResult,ReadResourceResult,Resource,ServerNotification,ServerRequest,ToolAnnotations。
别名
McpToolExtra、McpPromptExtra 和 McpResourceExtra 为了向后兼容而保留，但已弃用——它们都会解析为 McpRequestExtra。在新代码中请优先使用规范名称。import { z } from 'zod'
export default defineMcpTool({
name: 'example',
inputSchema: {
message: z.string(),
},
handler: async ({ message }, extra: McpRequestExtra) => {
// message 的类型为 string
// extra.signal, extra.authInfo, extra.sessionId 可用
},
})
你可以在配置中设置 autoImports: false 来完全禁用自动导入，并改为从 @nuxtjs/mcp-toolkit/server 显式导入。
类型推断
工具输入类型
输入类型会根据你的 inputSchema 自动推断：
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpTool({
name: 'example',
inputSchema: {
name: z.string(),
age: z.number(),
email: z.string().email().optional(),
},
handler: async ({ name, age, email }) => {
// name: string
// age: number
// email: string | undefined
},
})
工具输出类型
输出类型会根据 outputSchema 进行推断：
import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpTool({
name: 'example',
inputSchema: {
value: z.number(),
},
outputSchema: {
result: z.number(),
doubled: z.number(),
},
handler: async ({ value }) => {
const result = value * 2
return {
structuredContent: {
result, // TypeScript 知道这是 number 类型
doubled: result * 2, // TypeScript 知道这是 number 类型
},
}
},
})
提示词参数类型
提示词参数类型会根据 inputSchema 进行推断：
import { defineMcpPrompt } from '@nuxtjs/mcp-toolkit/server'
export default defineMcpPrompt({
name: 'example',
inputSchema: {
text: z.string(),
maxLength: z.string().optional(),
},
handler: async ({ text, maxLength }) => {
// text: string
// maxLength: string | undefined
},
})
运行时配置类型
访问具有类型提示的运行时配置：
server/api/config.ts
export default defineEventHandler((event) => {
const config = useRuntimeConfig(event).mcp
// config 的类型包含：
// - enabled: boolean
// - route: string
// - browserRedirect: string
// - name: string
// - version: string
// - dir: string
return config
})