型付きツール定義ファクトリー

使用時期

• MCPまたは同様のJSONスキーマ駆動型ツールシステムを持つ多数のツールがあり、宣言スキーマとハンドラーのパラム型の間に差異がないようにしたい場合
• 一部のツールに追加セットアップ(例えば事前解決された「現在のページ」またはDBコネクション)が必要であり、毎回ハンドラーにコピー&ペーストしたくない場合
• ビルド時に同じツール定義からドキュメントやCLIを生成したい場合

動作原理

• BaseToolDefinition<Schema extends zod.ZodRawShape>をname、description、annotations、schemaで定義します。TypeScriptがzodからパラム型を推論できるようSchemaをジェネリックとして保持します。
• defineTool(def)を提供します。これは単に引数を返しますがジェネリックを絞ります。ハンドラーシグネチャは(request: { params: zod.objectOutputType<Schema, ZodTypeAny> }, response, context) => Promise<void>として型付けされます。
• 2番目のオーバーロードdefineTool(factoryFn)を提供します。これはパース済みCLI引数の関数を受け入れ、ツールを返します。これにより、ツールは起動フラグに基づいてスキーマ/動作を調整できます。
• 「ページが必要」のケースでは、definePageToolを追加します。これはpageScoped: trueをスタンプし、拡張されたハンドラーシグネチャ(request & { page: ContextPage }, response, context)を持ちます。サーバーディスパッチャーはpageScopedをチェックし、ハンドラー呼び出し前にページを解決します。
• 共通スキーマフラグメント(pageIdSchema、timeoutSchema、viewportTransformのような変換)をエクスポートします。これにより、ツール間で正確な文言と検証が共有されます。

例

export const takeSnapshot = definePageTool({
  name: 'take_snapshot',
  description: 'Take a text a11y snapshot of the selected page.',
  annotations: { category: ToolCategory.DEBUGGING, readOnlyHint: false },
  schema: {
    verbose: zod.boolean().optional().describe('Include all a11y attrs.'),
    filePath: zod.string().optional().describe('Save to file instead.'),
  },
  // `request.params.verbose` は `boolean | undefined` として型付けされます。
  // `definePageTool` により `request.page` が存在します。
  handler: async (request, response) => {
    response.includeSnapshot({
      verbose: request.params.verbose ?? false,
      filePath: request.params.filePath,
    });
  },
});

注意点

• zod.ZodRawShapeはコンパイルされたオブジェクトスキーマではなく、生のプロパティマップです。スキーマをzod.object(...)でラップするとオーバーロード一致が失われるため、ラップしないでください。
• ランタイムスキーマウォーカー(ドキュメントやテレメトリー向け)は、ZodOptional、ZodDefault、ZodEffectsを_def.innerType / _def.schemaを再帰的にアンラップして処理する必要があります。そうしないと型を誤読みします。
• ファクトリー変種ツール(args) => defは登録時にtypeof tool === 'function'で検出される必要があります。1つの配列内で遅延ツールと即座ツールを混在させると「tool.name is undefined」のバグが発生します。
• ハンドラーシグネチャはPromise<void>に保ちます。レスポンスビルダーへの副作用がコントラクトです。値を返すことはビルダー抽象化がリークしていることを示す兆候です。