MCP Fusion/Core concepts/ツール

ツール

VinkiusについてAIに質問

f.query、f.mutation、f.actionでAI Capabilitiesを定義します。型付きパラメータ、ミドルウェア、Resultモナド、そしてエージェントが使ってはいけないツールを除去するFSMステートゲーティング。

ツールはエージェントが呼び出す対象です。Vinkiusの用語では、コネクタのAI Capabilitiesにあたります。MCP Fusionは、3つのセマンティックなエントリーポイントを持つフルエントビルダーを提供し、そのセマンティクスはエージェントが見るMCPアノテーションに対応します。

ビルダー	意味	MCPアノテーション
`f.query()`	データの読み取り	`readOnlyHint: true`
`f.mutation()`	データの書き込み	ツールごとの破壊的ヒント
`f.action()`	副作用、外部呼び出し	ツールごとの破壊的ヒント

完全なツール

typescript

export default f.mutation('billing.refund')
  .describe('Refund an invoice by ID')
  .withString('id', 'Invoice ID')
  .withNumber('amount_cents', 'Amount to refund in CENTS')
  .withOptionalEnum('reason', ['duplicate', 'customer_request', 'fraud'],
    'Why the refund is happening')
  .returns(InvoicePresenter)
  .use(requireAuth)
  .handle(async (input, ctx) => {
    const result = await refunds.create(input, ctx.tenantId);
    if (!result.ok) return result.response;
    return result.value;
  });

パラメータ

.withString(name, description)、.withNumber、.withBoolean、.withEnumと.withOptional系のバリエーションでZod入力スキーマを構築します
Model駆動のツールは.fromModel()を使えるModelのfillableフィールドをパラメータとして再利用できます
.toonDescription()はツールの説明をパイプ形式に圧縮し、トークン消費を約半分に抑えます
.bindState('approved', 'DISCHARGE')はツールをFSMの状態に接続します。詳細は後述します

ミドルウェア

.use()は1つのツールにミドルウェアを追加します。ミドルウェアはExpressスタイルで合成され、各ミドルウェアはctxにマージされる部分コンテキストを返します。これにより、認証、テナント解決、レート制限がハンドラーの外に保たれます:

typescript

// A middleware derives context: the returned object merges into ctx,
// typed through the whole fluent chain.
const withUser = f.middleware(async (ctx) => {
  const user = await auth.verify(ctx.request);
  return { user };
});

f.query('billing.get_profile').use(withUser);

ディレクトリ内のすべてのツールに適用されるグローバルミドルウェアについてはRoutingを参照してください。

Resultモナド

失敗しうるハンドラーは例外を投げる代わりにResultを返し、フレームワークはFailureを、エージェントが対処できる構造化されたツールレスポンスへ変換します:

typescript

import { succeed, fail, toolError } from '@mcpfusion/core';

.handle(async (input) => {
  const invoice = await db.invoices.findUnique({ where: { id: input.id } });
  if (!invoice) {
    return fail(toolError('NOT_FOUND', {
      message: 'No invoice with that ID',
      availableActions: ['billing.list_invoices'],
    }));
  }
  return succeed(invoice);
});

availableActionsリストは自己修復的なコンテキストです。エージェントが誤ったIDを選んだとき、エラーそのものが代替手段を教えます。コントラクト変更時に同じ仕組みがどう機能するかはGovernanceを参照してください。

FSMステートゲーティング

特定の状態では存在してはならないツールがあります。請求書が承認される前に、dischargeツールが見えていては意味がありません。.bindState()はツールをワークフローの状態に接続し、状態が許可しない間、MCP Fusionはtools/listからそのツールを物理的に除去します:

typescript

export default f.action('billing.discharge')
  .describe('Discharge an approved invoice')
  .bindState('approved', 'DISCHARGE')
  .handle(async (input, ctx) => { /* ... */ });

状態が変わるにつれてクライアントはnotifications/tools/list_changedを受け取るため、エージェントのメニューは現実と一致します。これにより、モデルが順序外のステップを呼び出す典型的なハルシネーションが排除されます。ステートストアは差し替え可能で、RedisやエッジKVの選択肢があるため、serverless環境でもゲーティングが機能します。

ステートゲーティングはツールを隠すのではなく除去します。エージェントは呼び出せないツールを決して見ないため、試行も拒否によるターン消費も発生しません。

次のステップ

Routing: ツールをファイル単位で整理し、複数のアクションを1つのツールに集約
Models and Presenters: 各ツールの返却内容を形づくる
Testing: パイプライン全体をインメモリでテスト