工具

注释与输入示例

MCP 客户端的行为提示以及复杂工具的具体 inputExamples。

工具注释

注释是行为提示，用于告诉 MCP 客户端某个工具的行为方式。客户端可以据此决定何时提示用户进行确认（human-in-the-loop）。

server/mcp/tools/delete-user.ts

import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  name: 'delete-user',
  description: '删除用户账户',
  inputSchema: {
    userId: z.string(),
  },
  annotations: {
    readOnlyHint: false,    // 工具会修改状态
    destructiveHint: true,  // 工具会执行破坏性更新
    idempotentHint: true,   // 多次删除同一个用户不会产生额外影响
    openWorldHint: false,   // 工具不会与外部系统交互
  },
  handler: async ({ userId }) => {
    // ...
  },
})

注释参考

注释	类型	默认值	描述
`readOnlyHint`	`boolean`	`false`	如果为 `true`，工具只读取数据，不修改任何状态（可安全重试）。
`destructiveHint`	`boolean`	`true`	如果为 `true`，工具可能执行破坏性操作，例如删除数据。仅在 `readOnlyHint` 为 `false` 时有意义。
`idempotentHint`	`boolean`	`false`	如果为 `true`，使用相同参数多次调用该工具，除首次调用外不会产生额外影响。仅在 `readOnlyHint` 为 `false` 时有意义。
`openWorldHint`	`boolean`	`true`	如果为 `true`，工具可能与外部世界交互（外部 API、互联网）。如果为 `false`，则只对本地/内部数据进行操作。

以下是典型工具的常见注释模式：

// 搜索、列表、查询、计算...
annotations: {
  readOnlyHint: true,
  destructiveHint: false,
  openWorldHint: false,
}

// 每次都会创建一条新记录
annotations: {
  readOnlyHint: false,
  destructiveHint: false,
  idempotentHint: false,
  openWorldHint: false,
}

// 更新是幂等的（相同输入 → 相同结果）
annotations: {
  readOnlyHint: false,
  destructiveHint: false,
  idempotentHint: true,
  openWorldHint: false,
}

// 具有破坏性且幂等（删除两次与删除一次效果相同）
annotations: {
  readOnlyHint: false,
  destructiveHint: true,
  idempotentHint: true,
  openWorldHint: false,
}

所有注释都只是提示——并不能保证会被每个 MCP 客户端遵守。客户端绝不应基于来自不受信任服务器的注释做出安全关键决策。

输入示例

你可以使用 inputExamples 为工具提供具体用法示例。这些示例是类型安全的（与 inputSchema 匹配），并会通过 _meta.inputExamples 传输给客户端。

输入示例有助于 AI 模型理解如何正确填写工具参数，尤其适用于具有可选字段或复杂输入的工具。

server/mcp/tools/create-todo.ts

import { z } from 'zod'
import { defineMcpTool } from '@nuxtjs/mcp-toolkit/server'

export default defineMcpTool({
  description: '创建新的待办事项',
  inputSchema: {
    title: z.string().describe('待办事项的标题'),
    content: z.string().optional().describe('可选描述'),
  },
  inputExamples: [
    { title: 'Buy groceries', content: 'Milk, eggs, bread' },
    { title: 'Fix login bug' },  // content 是可选的
  ],
  handler: async ({ title, content }) => {
    // ...
  },
})

inputExamples 对于带有可选参数、枚举或复杂嵌套输入的工具尤其有用，因为展示具体值有助于模型选择正确的格式。

Edit this pageorReport an issue

Schema, handler & returns

使用 Zod 定义工具输入和输出，并从处理器返回文本、结构化数据或媒体。

错误与缓存

工具处理器中的 H3 和普通错误，以及基于 Nitro 的响应缓存。