ドキュメント

MCP Fusion/Core concepts/ツール公開

ツール公開

VinkiusについてAIに質問

アクションを一度定義し、ワイヤーに公開する形を選択できます。ディスクリミネーター付きのグループ化されたツールか、アクションごとのアトミックなツールに加え、タグベースの可視性とアクション別スキーマを利用できます。

コネクターの作成方法とエージェントからの見え方は、MCP Fusion では別々の決定です。公開層はその間に位置し、ビルダーを受け取ってクライアントに送る tools/list のサーフェスをコンパイルします。ハンドラーを 1 つも変更せずに戦略を切り替えられます。

名前空間: 1 つのツール、複数のアクション

作成時はドット区切りの名前を使い、最初のドットで名前空間とアクションを分けます。

記述MCP ツールアクション
f.query('billing.get_invoice')billingget_invoice
f.mutation('billing.refund')billingrefund
f.action('support.tickets.search')support.ticketssearch

ツール名に含められるドットは最大 1 つです。ネストしたプレフィックスには f.router('support.tickets') を使います。同じ名前空間を共有するビルダーはレジストリによって統合されるため、compliance.scan、compliance.report、compliance.status をそれぞれ export する 3 つのファイルから、3 つのアクションを持つ compliance ツールが生成されます。エージェントには一貫したサーフェスが見え、開発者はアクションごとのファイル構成を維持できます。

2 つの戦略

attachToServer(server, { toolExposition }) でワイヤー上の形を選択します。

グループ化は複数アクションの名前空間に対するデフォルトです。名前空間ごとに 1 つの MCP ツールを作り、デフォルトでは action となるディスクリミネーターフィールドを持たせます。.discriminator('operation') で名前を変更できます。エージェントはリソース指向 API と同じように、引数としてアクションを選択します。

フラットではアクションごとに 1 つのアトミックな MCP ツールを作り、billing_get_invoice のように名前を付けます。区切り文字は設定可能です。各ツールには専用の整理済みスキーマが与えられ、共通フィールドはそのアクションのフィールドとのみ統合され、ディスクリミネーターは除去され、固有のアノテーションが付きます。クライアントのツール選択が弱い場合や、アクション間の共通点がほとんどない場合にフラットを使います。

フラットなツールでは HATEOAS のアフォーダンスも直接的になります。フラットなサーフェスからの .suggest('billing.remind') は、クライアントがすでに一覧表示しているツールです。

アノテーションの正確さ

意味を持つ動詞が MCP アノテーションを設定し、公開層はそれをアクションごとに保持します。

ビルダーアノテーション
f.query()readOnlyHint: true
f.mutation()destructiveHint: true
f.action()中立
.idempotent()idempotentHint: true

フラットモードでは各アトミックなツールが固有のヒントを持ちます。グループ化モードではツールが最も安全な集約値を持ち、アクションごとのヒントは各アクションのスキーマ説明に含まれます。破壊的なミューテーションが読み取り専用だと名乗るのは、クライアントがその情報をもとに動くため問題です。したがってフレームワークは、宣言されていない安全性を推測しません。

パラメーターアノテーションが説明を担います

グループ化されたスキーマは共通パラメーターとアクション固有のパラメーターを統合します。各フィールドの説明には、アクションそのものから生成された必須性のアノテーションが加わります。

アノテーション意味
(always required)ツールのすべてのアクションで必須
Required for: refund, void記載されたすべてのアクションで必須
Required for: refund. For: get一部で必須、他では任意
For: get, list必須ではないが、該当アクションで使用

エージェントはエラーからこのマトリクスを学ぶ必要がありません。スキーマが示すからです。ディスクリミネーターの enum と組み合わせることで、グループ化されたツールは自己記述型 API になります。

タグによる可視性

.tags('billing', 'finance') でツールをマークし、attachToServer(server, { filter }) で公開対象を決めます。

typescript
attachToServer(server, {
  filter: {
    tags: ['finance'],          // AND: must carry every tag
    anyTag: ['public'],         // OR: at least one
    exclude: ['internal'],      // NOT
  },
});

タグを使うと、1 つのコードベースで複数のプロダクトに対応できます。無料プランでは公開ツールを公開し、エンタープライズ環境では内部ツールを公開し、ハンドラーのコードは同一のままです。同じ考え方をリクエスト単位で適用する方法は マルチテナントコネクター をご覧ください。

トークン戦略としてのグループ化

すべてのツール名、説明、スキーマは毎ターンのコンテキストを消費します。フラットなツールが 100 個あると、モデルは計画前に 100 個の説明を読みます。10 個のアクションをディスクリミネーター enum 付きの 1 つのツールにまとめると、スキーマサイズとプロンプトサイズを交換でき、通常は約 10 アクションを超えると大きな効果があります。.toonDescription() は説明をさらに圧縮し、compactDescription() は FSM の段階的開示に短い形式を提供します。詳しくは トークンエコノミーで説明します。

次のステップ