create-tool

创建 xmcp 工具

你将帮助用户创建新的 xmcp 工具。请遵循以下交互式工作流程。

步骤 1：收集信息

在生成任何代码之前，使用 AskUserQuestion 向用户提出以下问题：

1. 工具名称（如果参数中未提供）：工具应该叫什么名称？（使用 kebab-case）

2. 处理程序类型：询问用户需要哪种处理程序类型：

   • Standard —— 用于数据查询、计算、API 调用（返回字符串/JSON）
   • Template Literal (HTML) —— 用于带外部脚本的 HTML 小组件
   • React Component —— 用于交互式有状态小组件（.tsx 文件）

3. 架构字段：工具应接受哪些参数？询问以下内容：

   • 参数名称
   • 类型（string、number、boolean、enum、array、object）
   • 描述
   • 是否为可选参数
   • 任何验证规则

4. 注解：询问有关行为提示的信息：

   • 是否为只读？（不会修改环境）
   • 是否具有破坏性？（可能删除或修改数据）
   • 是否为幂等操作？（重复调用会产生相同效果）
   • 是否与外部世界交互？（openWorldHint）

5. 小组件支持（如果选择 Template Literal 或 React）：询问用户是否需要：

   • OpenAI 工具调用消息（invoking/invoked 状态）
   • 小组件无障碍支持（widgetAccessible）
   • 小组件与工具之间的通信

步骤 2：生成工具

在 src/tools/ 中创建工具文件，并使用适当的扩展名：

• Standard 和 Template Literal 处理程序使用 .ts
• React Component 处理程序使用 .tsx

文件位置

src/tools/{tool-name}.ts   # or .tsx for React

工具结构参考

每个 xmcp 工具都有三个主要导出项：

// 1. Schema (optional) - Define parameters with Zod
export const schema = { /* ... */ };

// 2. Metadata (optional) - Tool configuration
export const metadata: ToolMetadata = { /* ... */ };

// 3. Handler (required) - Default export function
export default function handler(params) { /* ... */ }

快速参考

必要的导入

import { z } from "zod";
import { type InferSchema, type ToolMetadata } from "xmcp";

处理程序类型摘要

类型	使用场景	文件扩展名
Standard (string)	简单查询、计算	.ts
Standard (async)	API 调用、数据库查询	.ts
Template Literal	HTML 小组件、iframe、脚本	.ts
React Component	交互式有状态 UI	.tsx
No Parameters	无需输入的工具	.ts
With Extra Args	依赖身份验证/上下文的工具	.ts

注解快速参考

注解	使用时机
readOnlyHint: true	工具不会修改环境
destructiveHint: true	工具可能会删除/修改数据
idempotentHint: true	重复调用会产生相同效果
openWorldHint: true	工具与外部世界交互

详细模板

完整代码模板包括：

• 架构模式（简单、验证、枚举、可选、对象）
• 元数据模式（基本信息、注解、OpenAI 小组件、MCP Apps UI）
• 所有处理程序类型模板（A 至 G）
• 返回值模式
• 类型导入参考

请阅读：references/templates.md

---

生成后检查清单

1. 已在 src/tools/{tool-name}.ts（或 .tsx）中创建文件
2. 架构中的所有参数都使用 .describe()
3. 如果使用元数据，请确保包含描述性的 name 和 description
4. 根据工具行为设置了适当的注解
5. 处理程序与所选类型匹配
6. 所有导入均正确

建议运行 pnpm build，以验证工具是否可以正确编译。