flutter-mcp-toolkit-intentcall-migration

IntentCall の移行 — MCPCallEntry → AgentCallEntry

MCPCallEntry は mcp_toolkit から削除されました。アプリのコードでは AgentCallEntry（intentcall_core から提供され、mcp_toolkit によって再エクスポートされます）を使用してください。

標準の移行ガイド：migration_mcp_call_entry_to_agent_call_entry.md

このスキルを使用するタイミング

• mcp_toolkit のアップグレード後、dart analyze で MCPCallEntry が未定義と報告される
• ユーザーからカスタムツールやリソースを新しい API に移行するよう依頼された
• mcp_toolkit のメジャーアップデートを利用者にリリースする前

CLI（推奨）

# Preview (exit 1 if changes pending)
flutter-mcp-toolkit migrate agent-entries --check lib/

# Apply
flutter-mcp-toolkit migrate agent-entries --write lib/
flutter-mcp-toolkit migrate agent-entries --write --namespace my_app lib/main.dart

エイリアス：migrate mcp-call-entry（同じ動作です）。

移行後 — 登録

• MCPToolkitBinding.addEntries(entries: Set<AgentCallEntry>)
• bootstrapFlutter(runApp: ...) の前に addEntries(entries: { ... })
• addMcpTool(AgentCallEntry) — 単一のエントリー用のショートカットとして引き続き使用できます

ハンドラーは**AgentResult（AgentResult.success ／ AgentResult.failure）を返す必要があります。 従来の MCPCallResult と MCPToolDefinition を使用するハンドラーには、mcpToolkitTool** ／ mcpToolkitResource を使用してください（flutter-mcp-toolkit-custom-tools を参照）。

従来のパターン（変更前 — 新しいコードでは使用しないでください）

// BEFORE (removed in Phase 6b)
final tool = MCPCallEntry.tool(
  handler: (request) async => MCPCallResult(
    message: 'ok',
    parameters: {'n': request['n']},
  ),
  definition: MCPToolDefinition(
    name: 'my_tool',
    description: 'Example',
    inputSchema: {'type': 'object', 'properties': {}},
  ),
);

目標のパターン（変更後）

import 'package:mcp_toolkit/mcp_toolkit.dart';

final tool = AgentCallEntry.tool(
  namespace: 'app',
  name: 'my_tool',
  description: 'Example',
  inputSchema: const {
    'type': 'object',
    'additionalProperties': false,
    'properties': {'n': {'type': 'string'}},
    'required': ['n'],
  },
  handler: (final args) async {
    final n = args['n']?.toString() ?? '';
    return AgentResult.success(
      message: 'ok',
      data: {'n': n},
    );
  },
);

await MCPToolkitBinding.instance.addEntries(entries: {tool});

プラットフォームとの同期（任意）

ツールのインターフェースがコンパイルできたら、次を実行します。

flutter-mcp-toolkit codegen sync --platform web
flutter-mcp-toolkit codegen sync --platform android,ios,macos --check

Xiaomi／Huawei については docs/platform-notes/android-oem.md を参照してください（AOSP と同じショートカット XML を使用します）。

MCP 移行ツール

fmt_migrate_agent_entries は提供済みです（デフォルトではレポートのみを出力し、書き換えるには apply: true を指定します）。CLI での同等のコマンド：flutter-mcp-toolkit migrate agent-entries。

メンテナー向けチェックリスト（リポジトリ内の製品リリース条件）

1. showcase/flutter_test_app/lib に対して flutter-mcp-toolkit migrate agent-entries --check を実行する
2. plugin/skills/ を編集したら make sync-skills を実行する
3. cd mcp_server_dart && dart test test/contract/ を実行する
4. grep を実行し、このファイルの変更前の例を除き、スキル内に MCPCallEntry が存在しないことを確認する

ホスト型 IntentCall パッケージ

IntentCall は現在、このリポジトリの外部にあります。通常の利用者向け構成では、ホスト型の intentcall_* パッケージを使用します。

1. コミットする利用者向け構成では、ホスト型の intentcall_*: ^0.6.0 依存関係を使用します。
2. ローカルの IntentCall チェックアウトを対象に、リポジトリをまたいだ開発を意図的に行う場合に限り、ローカルパスのオーバーライドを使用します。
3. 依存関係を変更した後、flutter pub get と migrate agent-entries --check を再度実行します。
4. CI では、ホスト型の mcp_flutter の検証に make check-intentcall-hosted-consumer を使用します。意図的にローカルの IntentCall チェックアウトを使うマトリックス検証には、make check-intentcall-sibling-matrix のみを使用します。従来の make check-intentcall-integration ターゲットは、sibling-matrix レーンの互換性エイリアスであり、新規利用者向けのホスト型ゲートではありません。

関連スキル

• flutter-mcp-toolkit-custom-tools — AgentCallEntry のインターフェースを作成する
• flutter-mcp-toolkit-repo-maintainer — CHANGELOG、バージョンの固定、sync-skills