Back to Details

create-tool

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create xmcp Tool

创建xmcp工具

You are helping the user create a new xmcp tool. Follow this interactive workflow.
您正在协助用户创建一个全新的xmcp工具，请遵循以下交互式工作流程。

Step 1: Gather Information

步骤1：收集信息

Before generating any code, ask the user these questions using AskUserQuestion:
  1. Tool name (if not provided as argument): What should the tool be named? (Use kebab-case)
  2. Handler type: Ask which handler type they need:
    • Standard - For data queries, calculations, API calls (returns string/JSON)
    • Template Literal (HTML) - For HTML widgets with external scripts
    • React Component - For interactive stateful widgets (.tsx file)
  3. Schema fields: What parameters should the tool accept? Ask for:
    • Parameter name
    • Type (string, number, boolean, enum, array, object)
    • Description
    • Whether it's optional
    • Any validation rules
  4. Annotations: Ask about behavior hints:
    • Is it read-only? (doesn't modify environment)
    • Is it destructive? (may delete or modify data)
    • Is it idempotent? (repeated calls have same effect)
    • Does it interact with external world? (openWorldHint)
  5. Widget support (if Template Literal or React): Ask if they need:
    • OpenAI tool invocation messages (invoking/invoked status)
    • Widget accessibility (widgetAccessible)
    • Widget-to-tool communication
在生成任何代码之前，请使用AskUserQuestion向用户询问以下问题：
  1. 工具名称（若未作为参数提供）：工具应该命名为什么？（请使用短横线分隔式命名（kebab-case））
  2. 处理器类型：询问用户需要哪种处理器类型：
    • 标准型 - 用于数据查询、计算、API调用（返回字符串/JSON）
    • 模板字面量（HTML） - 用于包含外部脚本的HTML小部件
    • React Component - 用于交互式有状态小部件（.tsx文件）
  3. Schema字段：工具应接受哪些参数？请询问：
    • 参数名称
    • 类型（字符串、数字、布尔值、枚举、数组、对象）
    • 描述
    • 是否为可选参数
    • 任何验证规则
  4. 注解：询问有关行为提示的信息：
    • 它是否为只读？（不修改环境）
    • 它是否具有破坏性？（可能删除或修改数据）
    • 它是否具有幂等性？（重复调用效果相同）
    • 它是否与外部系统交互？（openWorldHint）
  5. 小部件支持（若选择模板字面量或React类型）：询问用户是否需要：
    • OpenAI工具调用消息（调用中/已调用状态）
    • 小部件可访问性（widgetAccessible）
    • 小部件与工具的通信

Step 2: Generate the Tool

步骤2：生成工具

Create the tool file in 
src/tools/
with the appropriate extension:
  • .ts
    for Standard and Template Literal handlers
  • .tsx
    for React Component handlers
在
src/tools/
目录下创建工具文件，并使用相应的扩展名：
  • 标准型和模板字面量处理器使用
    .ts
  • React Component处理器使用
    .tsx

File Location

文件位置

src/tools/{tool-name}.ts   # or .tsx for React
src/tools/{tool-name}.ts   # 或React组件使用.tsx

Tool Structure Reference

工具结构参考

Every xmcp tool has three main exports:
typescript
// 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) { /* ... */ }
每个xmcp工具都有三个主要导出项：
typescript
// 1. Schema（可选）- 使用Zod定义参数
export const schema = { /* ... */ };

// 2. 元数据（可选）- 工具配置
export const metadata: ToolMetadata = { /* ... */ };

// 3. 处理器（必填）- 默认导出函数
export default function handler(params) { /* ... */ }

Quick Reference

快速参考

Essential Imports

必要导入

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

Handler Types Summary

处理器类型汇总

TypeUse CaseFile Extension
Standard (string)Simple queries, calculations
.ts
Standard (async)API calls, database queries
.ts
Template LiteralHTML widgets, iframes, scripts
.ts
React ComponentInteractive stateful UIs
.tsx
No ParametersTools that don't need input
.ts
With Extra ArgsAuth/context-dependent tools
.ts
类型使用场景文件扩展名
标准型（字符串）简单查询、计算
.ts
标准型（异步）API调用、数据库查询
.ts
模板字面量HTML小部件、iframe、脚本
.ts
React Component交互式有状态UI
.tsx
无参数无需输入的工具
.ts
带额外参数依赖认证/上下文的工具
.ts

Annotations Quick Reference

注解快速参考

AnnotationUse When
readOnlyHint: true
Tool doesn't modify environment
destructiveHint: true
Tool may delete/modify data
idempotentHint: true
Repeated calls have same effect
openWorldHint: true
Tool interacts with external world
注解使用场景
readOnlyHint: true
工具不修改环境
destructiveHint: true
工具可能删除/修改数据
idempotentHint: true
重复调用效果相同
openWorldHint: true
工具与外部系统交互

Detailed Templates

详细模板

For complete code templates including:
  • Schema patterns (simple, validation, enum, optional, object)
  • Metadata patterns (basic, annotations, OpenAI widgets, MCP Apps UI)
  • All handler type templates (A through G)
  • Return value patterns
  • Type imports reference
Read: 
references/templates.md
如需完整的代码模板，包括：
  • Schema模式（简单、验证、枚举、可选、对象）
  • 元数据模式（基础、注解、OpenAI小部件、MCP Apps UI）
  • 所有处理器类型模板（A至G）
  • 返回值模式
  • 类型导入参考
请查阅：
references/templates.md

Checklist After Generation

生成后的检查清单

  1. File created in 
    src/tools/{tool-name}.ts
    (or 
    .tsx
    )
  2. Schema uses 
    .describe()
    for all parameters
  3. If using metadata, ensure it has descriptive 
    name
    and 
    description
  4. Appropriate annotations set based on tool behavior
  5. Handler matches the chosen type
  6. All imports are correct
Suggest running 
pnpm build
to verify the tool compiles correctly.
  1. 文件已创建在
    src/tools/{tool-name}.ts
    （或
    .tsx
    ）
  2. Schema为所有参数使用了
    .describe()
    方法
  3. 若使用元数据，确保其包含描述性的
    name
    和
    description
  4. 根据工具行为设置了合适的注解
  5. 处理器与所选类型匹配
  6. 所有导入均正确
建议运行
pnpm build
以验证工具是否能正确编译。