create-tool

xmcp ツールの作成

新しい xmcp ツールの作成をユーザーに案内します。この対話型ワークフローに従ってください。

ステップ 1：情報を収集する

コードを生成する前に、AskUserQuestion を使用して次の質問をユーザーに尋ねます。

1. ツール名（引数として指定されていない場合）：ツール名をどうしますか？（ケバブケースを使用してください）

2. ハンドラーの種類：必要なハンドラーの種類を尋ねます。

   • 標準 - データのクエリ、計算、API 呼び出し向け（文字列／JSON を返します）
   • テンプレートリテラル（HTML） - 外部スクリプトを使用する HTML ウィジェット向け
   • React コンポーネント - インタラクティブで状態を持つウィジェット向け（.tsx ファイル）

3. スキーマのフィールド：ツールが受け取るパラメーターを尋ねます。次の項目を確認してください。

   • パラメーター名
   • 型（string、number、boolean、enum、array、object）
   • 説明
   • オプションかどうか
   • バリデーションルール

4. アノテーション：動作に関するヒントを尋ねます。

   • 読み取り専用ですか？（環境を変更しない）
   • 破壊的ですか？（データを削除または変更する可能性がある）
   • 冪等ですか？（繰り返し呼び出しても同じ効果がある）
   • 外部の世界とやり取りしますか？（openWorldHint）

5. ウィジェットのサポート（テンプレートリテラルまたは React の場合）：次の機能が必要か尋ねます。

   • OpenAI ツール呼び出しメッセージ（invoking／invoked ステータス）
   • ウィジェットのアクセシビリティ（widgetAccessible）
   • ウィジェットとツール間の通信

ステップ 2：ツールを生成する

適切な拡張子を付けて、src/tools/ にツールファイルを作成します。

• 標準およびテンプレートリテラルのハンドラーには .ts
• React コンポーネントのハンドラーには .tsx

ファイルの場所

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

ツール構造のリファレンス

すべての xmcp ツールには、主なエクスポートが 3 つあります。

// 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";

ハンドラーの種類の概要

種類	用途	ファイル拡張子
標準（文字列）	シンプルなクエリ、計算	.ts
標準（非同期）	API 呼び出し、データベースクエリ	.ts
テンプレートリテラル	HTML ウィジェット、iframe、スクリプト	.ts
React コンポーネント	インタラクティブで状態を持つ UI	.tsx
パラメーターなし	入力が不要なツール	.ts
追加の引数あり	認証／コンテキストに依存するツール	.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 の実行を提案してください。