Flutter MCP Toolkit

MCP Toolkit Server（Dart）

v2.x からの移行

MCP のツール名には fmt_ というプレフィックスが付き、バイナリと mcpServers のキーが変更されています。**v2.x から v3.0 への移行**をご覧ください。

アーキテクチャ

このプロジェクトでは、共有コア実行レイヤーを使用するようになりました。

1. flutter-mcp-toolkit は正式なコマンドサーフェスです（接続、検査、実行、診断）。fmtk は同じ CLI エントリーポイントの短縮エイリアスです。
2. flutter-mcp-toolkit-server は、MCP のツール／リソース呼び出しを同じコア実行機能にマッピングする、軽量な MCP プロトコルアダプターです。
3. MCP の tools/list 名には fmt_ ケイパビリティプレフィックスを使用します。CLI の exec --name では、MCP の tools/call 名前空間外のコマンドカタログ名またはエイリアスを使用します。リソース URI は変更されていません。

共有コアモジュールは、このパッケージ内で flutter_mcp_core として利用できます。

推奨手順

macOS では、まず次の手順を実行してください。

1. アプリに mcp_toolkit を追加し、MCPToolkitBinding.instance.bootstrapFlutter(...) を呼び出します。
2. アプリをデバッグモードで起動します。
3. fmtk validate-runtime を実行します（または正式な長形式の flutter-mcp-toolkit validate-runtime を実行します）。
4. 次の順番で動的エントリを照会します。 fmt_list_client_tools_and_resources, fmt_client_tool, fmt_client_resource.

exec はエキスパートモードとして扱ってください。最初の確認には、validate-runtime を標準の検証コマンドとして使用します。

CLI v3 のインターフェース（破壊的変更）

CLI はエージェントファーストとなり、次の正規インターフェースを公開します。

• exec --name <command> --args <json>
• schema [--name <command>]
• capabilities
• serve（stdio 経由の JSON-RPC 2.0）
• snapshot create --name <id> [--args <json>]
• snapshot diff --from <id> --to <id>
• bundle create --from-snapshot <id> [--output <dir>]
• doctor [--json] [--target <path>] [--timeout-ms <n>]
• permissions status|request|open-settings [--kind visual_capture]

書き込みを行うコマンドで使用する安全な書き込みフラグ：

• snapshot create：--check --diff --backup --no-overwrite
• bundle create：--check --diff --backup --no-overwrite

exec の対象は、共有の CommandCatalog に含まれるコマンドです（CLI のコマンド名は --name の後にのみ指定するため、接頭辞なしで指定できます。CLI は MCP の tools/call 名前空間ではありません）。 connect、session_start、session_exec、session_end、diagnose、watch、explain_errors、status、discover_debug_apps、get_vm、get_extension_rpcs、hot_reload_flutter、hot_restart_flutter、get_active_ports、get_app_errors、get_screenshots、focus_window、get_view_details、inspect_widget_at_point、capture_ui_snapshot、debug_dump_layer_tree、debug_dump_semantics_tree、debug_dump_render_tree、debug_dump_focus_tree、fmt_list_client_tools_and_resources、fmt_client_tool、fmt_client_resource、dynamicRegistryStats、semantic_snapshot、tap_widget、long_press、enter_text、reveal_search、scroll、swipe、drag、hot_reload_and_capture、evaluate_dart_expression、get_recent_logs

MCP の名前。MCP の tools/call 経由で呼び出す場合、公開されるツールには fmt_ ケイパビリティ接頭辞が付きます（例：fmt_tap_widget、fmt_hot_reload_and_capture）。有効な場合、動的レジストリのホスト用 3 ツールは fmt_list_client_tools_and_resources、fmt_client_tool、fmt_client_resource として公開されます。dynamicRegistryStats は低レベル診断用として CLI カタログから引き続き利用できますが、デフォルトの MCP ツール群には含まれません。

インタラクションツール（カタログ名：semantic_snapshot → tap_widget / enter_text / reveal_search / scroll / swipe / long_press / drag）は、Playwright 形式の ref モデルに従います。スナップショットを取得した後、インタラクションツールに ref: "s_N"（古さを検出するための省略可能な snapshotId も指定可能）を渡します。reveal_search は、画面外にあるセマンティックターゲット用の範囲を限定したヘルパーです。スナップショットを取得し、限定的なセレクターを 1 つ照合して、maxAttempts 回までスクロールし、新しい ref / snapshotId とトレースを返します。hot_reload_and_capture は、リロード、スクリーンショット、新しいスナップショット、エラーをまとめて実行します。evaluate_dart_expression は、アプリのルートライブラリに対してアドホックな Dart 式を実行します。全インターフェースと推奨手順については、docs/start_here/cli_quick_recipes.mdx および docs/guides/interaction_cookbook.mdx を参照してください。

パッケージ版のインストールには flutter-mcp-toolkit と fmtk の両方が含まれます。以下の例では、ソースツリーでの開発に dart run を使用しています。ローカルでの短い実行サイクルには fmtk を優先し、検索しやすい正規名が役立つオンボーディング、インストール、PATH、MCP 設定のドキュメントでは flutter-mcp-toolkit を使用してください。

CLI は MCP と同じ共有コマンドカタログ／エグゼキューターを実行します。推奨されるデバッグ手順は次のとおりです。 discover_debug_apps -> capture_ui_snapshot -> inspect_widget_at_point。 get_active_ports と dynamicRegistryStats は低レベル診断用として CLI で引き続き利用できますが、意図的にデフォルトでは MCP に公開されません。

CLI の簡単な使い方（v3）

# introspection
dart run bin/flutter_mcp_toolkit.dart schema
dart run bin/flutter_mcp_toolkit.dart capabilities

# one-shot execution (machine envelope)
dart run bin/flutter_mcp_toolkit.dart exec --name status --args '{}'
dart run bin/flutter_mcp_toolkit.dart exec --name get_vm --args '{}'
dart run bin/flutter_mcp_toolkit.dart exec --name get_vm --args '{"connection":{"targetId":"ws://127.0.0.1:8181/<token>/ws"}}'
dart run bin/flutter_mcp_toolkit.dart exec --name discover_debug_apps --args '{}'
dart run bin/flutter_mcp_toolkit.dart exec --name capture_ui_snapshot --args '{"connection":{"targetId":"ws://127.0.0.1:8181/<token>/ws"}}'
dart run bin/flutter_mcp_toolkit.dart exec --name inspect_widget_at_point --args '{"x":120,"y":220,"connection":{"targetId":"ws://127.0.0.1:8181/<token>/ws"}}'

# session lifecycle
dart run bin/flutter_mcp_toolkit.dart exec --name session_start --args '{"mode":"uri","uri":"ws://127.0.0.1:8181/<token>/ws"}'
dart run bin/flutter_mcp_toolkit.dart exec --name session_exec --args '{"command":"get_app_errors","arguments":{"count":4}}'
dart run bin/flutter_mcp_toolkit.dart exec --name session_end --args '{}'

# reproducible artifacts
dart run bin/flutter_mcp_toolkit.dart snapshot create --name baseline --args '{"commands":[{"name":"status","args":{}}]}' --check --diff
dart run bin/flutter_mcp_toolkit.dart snapshot diff --from baseline --to after_fix
dart run bin/flutter_mcp_toolkit.dart bundle create --from-snapshot baseline --backup

# environment preflight
dart run bin/flutter_mcp_toolkit.dart doctor --json
dart run bin/flutter_mcp_toolkit.dart permissions status
dart run bin/flutter_mcp_toolkit.dart permissions request
dart run bin/flutter_mcp_toolkit.dart permissions open-settings
dart run bin/flutter_mcp_toolkit.dart exec --name get_extension_rpcs --args '{}'

# explicit capture policy/mode
dart run bin/flutter_mcp_toolkit.dart exec --name get_screenshots --args '{"mode":"desktop_window","permissionPolicy":"auto_request_once"}'
dart run bin/flutter_mcp_toolkit.dart exec --name capture_ui_snapshot --args '{"screenshotMode":"auto","permissionPolicy":"auto_request_once"}'

# one-command runtime validation (after app launch)
dart run bin/flutter_mcp_toolkit.dart --save-images --output-dir .flutter_mcp/app validate-runtime \
  --target ws://127.0.0.1:8181/<token>/ws \
  --timeout-ms 10000 \
  --post-reload-delay-ms 500 \
  --after-reload

# same, using global VM URI (equivalent to --target when only one is passed)
dart run bin/flutter_mcp_toolkit.dart --vm-service-uri ws://127.0.0.1:8181/<token>/ws validate-runtime \
  --timeout-ms 10000

# optional: install bundled skill during runtime validation
dart run bin/flutter_mcp_toolkit.dart validate-runtime \
  --target ws://127.0.0.1:8181/<token>/ws \
  --install-skill

アプリの検査に関する CLI のランタイムゲート：

• get_extension_rpcs から ext.mcp.toolkit.app_errors、ext.mcp.toolkit.view_details、ext.mcp.toolkit.view_screenshots、ext.mcp.toolkit.inspect_widget_at_point を取得する必要があります。
• 不足している場合は、mcp_toolkit がインストールおよび初期化され、アプリがホットリスタートまたは再実行されるまで、アプリレベルのスクリーンショット／レイアウト／エラー検査はブロックされます。
• スクリーンショットで、マップ／カメラ／ウェブビューが表示されるはずの場所に黒い長方形が表示される場合は、get_view_details の captureHints またはスクリーンショットのペイロード（platformViewsDetected または weakSignalsDetected）を確認してください。flutter_layer ではなく、mode: desktop_window を使用してください（または auto のままにしてください。強いシグナルがある場合、macOS ホストでは auto が desktop_window に切り替わります）。
• ホストキャプチャでは、再試行可能な失敗が発生すると、フォーカスとキャプチャを自動で1回リカバリーします（ペイロードの desktopCaptureRetried）。focus_window を呼び出してから、desktop_window を指定して get_screenshots を再試行することもできます。
• 明示的な URI での初回接続がタイムアウトした場合は、1回再試行し、doctor --json --target <ws_uri> --timeout-ms 10000 で検証してください。
• --output-dir を設定すると、validate-runtime は JSON エンベロープを <output-dir>/validate-runtime.json にも出力し、スクリーンショットファイルは <output-dir>/.mcp_screenshots/ に書き込みます。
• auto が desktop_window を選択した場合、validate-runtime はまずホストの desktop_window を試します。エグゼキューターのリカバリーでは、フォーカスとキャプチャを1回再試行します（desktopCaptureRetried）。それでも desktop_window が失敗する場合、validate-runtime は（showcase の AppKitView など、プラットフォームビューが検出された場合も含めて）flutter_layer で1回再試行します。data.summary.capturePlatformViewsDetected、captureFocusAttempted、captureFallbackUsed を確認してください。Web の headful キャプチャオプションについては、ADR 0007 を参照してください。

ビジュアルキャプチャの権限

• doctor は読み取り専用のままです。visual_capture_backend、visual_capture_permission、visual_capture_truth_mode、app_permission_bridge が報告されるようになりました。
• インタラクティブな CLI のキャプチャフローでは、exec get_screenshots、exec capture_ui_snapshot、validate-runtime のデフォルトが auto_request_once です。生のコマンドスキーマでは、引き続きデフォルトが check_only です。
• macOS で実際のキャプチャを行う場合は desktop_window を使用します（Mac ホスト上の iOS Simulator と Chrome / web を含みます）。画面収録の権限は、Flutter アプリではなく、flutter-mcp-toolkit を実行するホストプロセスに付与します。ネイティブのプロンプトを表示するには permissions request を使用し、拒否した場合は permissions open-settings を使用します。
• ネイティブプラットフォームビュー（AndroidView、UiKitView、AppKitView、HtmlElementView、PlatformViewLink）が検出されると、get_view_details と view_screenshots に captureHints が含まれます。Texture は、ソフト警告とともに weakSignalsDetected を設定します（auto へのアップグレードは行いません）。プラットフォームビューのないハイブリッドエンジンでは、アプリ内で MCPToolkitBinding.captureHintsContributor を使用できます。
• 画像のみの get_screenshots MCP レスポンスでは、captureHints または warnings がある場合、ルーティングメタデータが meta に含まれ、先頭に JSON テキストブロックが追加されます。
• Showcase の Capture セクション：macOS の AppKitView（make showcase）、Web の HtmlElementView（flutter run -d chrome）。macOS で新たに実行する前に make showcase-stop を使用してください。
• Web（chrome / web / web-server）：desktop_window は macOS ScreenCaptureKit → Chrome CDP（Page.captureScreenshot）→ flutter_layer を使用します。グローバルフラグ：--web-browser-debugging-port、--web-port。オプトインのライブテスト：RUN_WEB_CDP_INTEGRATION=1 dart test test/web_cdp_integration_test.dart。ADR 0007 を参照してください。
• iOS／Android／Linux など、アプリ所有のキャプチャ対象では、permissions または doctor がブリッジ経由の権限ツール／リソースを検証する前に、到達可能な VM ターゲットを選択する必要があります。これらのプラットフォームを調査する際は、--target <ws_uri> またはグローバルな --vm-service-uri <ws_uri> を使用してください。
• desktop_window が黙ってフォールバックすることはありません。auto は flutter_layer にフォールバックする場合がありますが、レスポンスでは常に requestedMode、actualMode、permissionStatus、fallbackReason が報告されます。

トラブルシューティング：

• macOS のキャプチャが拒否された場合は、まず flutter-mcp-toolkit permissions status を再実行してください。ステータスが引き続き denied の場合は、CLI からシステム設定を開き、使用中のターミナルまたはクライアントプロセスに画面収録を許可してください。
• macOS で doctor --json に visual_capture_truth_mode=flutter_layer と表示される場合、まだネイティブウィンドウのピクセルを取得できていません。
• Web の desktop_window が失敗した場合は、flutter_layer を使用するか、Chrome の --remote-debugging-port の値を --web-browser-debugging-port に渡してください。Web ターゲットでは、validate-runtime に --flutter-device chrome を渡してください。validate-runtime は、プラットフォームビューが検出されていても、desktop_window の失敗後に flutter_layer を再試行します。
• macOS のデスクトップウィンドウモードで、リロード後のキャプチャが一度失敗する場合、通常はアプリの障害ではなくホストキャプチャの競合です。validate-runtime は、失敗を赤として返す前に再試行し、desktop_window のスクリーンショット失敗後に flutter_layer で再試行する場合もあります。

障害マトリクス：

• missing_mcp_toolkit_wiring：アプリで必要なツールキット拡張機能が公開されていません。アプリのブートストラップを修正し、ホットリスタートしてください。
• bad_target_uri_or_unreachable_vm_service：明示的なターゲット URI が誤っているか、VM サービスに到達できません。
• permission_denied：ホストのキャプチャバックエンドに権限がありません。
• host_capture_backend_instability：デスクトップウィンドウのキャプチャ中、通常はリロードの前後で、ネイティブキャプチャバックエンドが不安定になりました。

移行（v2.x -> v3.0.0）

• エラーメタデータは error.descriptor の下に移動しました。レガシーのトップレベルフィールドは解析しないでください。
• 型付き引数は厳密に検証されます。文字列としてエンコードされたブール値／オブジェクト／リスト／整数は、検証に失敗するようになりました。
• 書き込みを行う自動化では、実際に書き込む前に --check --diff を付けて実行してください。
• --no-overwrite を使用する場合は、write_blocked を明示的に処理してください。
• VM に依存する実行の事前チェックとして、flutter-mcp-toolkit doctor --json を追加してください。

マシンエンベロープ

ワンショットコマンドは、安定したフィールドを持つ 1 つの JSON エンベロープを返します。

{
  "ok": true,
  "data": {},
  "error": null,
  "meta": {
    "schemaVersion": "core-envelope/v1",
    "command": "status",
    "timestamp": "2026-03-03T00:00:00.000Z",
    "durationMs": 2
  }
}

失敗時は、error 内の厳密なエンベロープを使用します。 code、message、details、descriptor（category、retryable、exitCode、httpLikeStatus）、recovery。

コントラクトの全容は、docs/ai_agents/troubleshooting.mdx に記載されています。

デーモンプロトコル

serve は、stdio 上で JSON-RPC 2.0 を実行します。主なメソッドは次のとおりです。

• リクエスト：initialize、capabilities/get、schema/get、command/execute、watch/start、watch/stop、snapshot/create、snapshot/diff、bundle/create、session/start、session/end
• 通知：watch/event、session/changed

Watch 通知は NDJSON の JSON-RPC 通知で、watch ごとに単調増加する seq を持ちます。

ターゲット指定の仕様：

• command/execute：params.args.connection は任意です
• watch/start：params.args.connection は任意です（watch ループの開始前に一度適用されます）
• snapshot/create：各ステップの args.commands[i].args.connection は任意です

状態とロック

• 状態ルートのデフォルトは .flutter_mcp/ です
• 状態ファイル：.flutter_mcp/state.json
• ロックファイル：.flutter_mcp/state.lock
• スナップショット：.flutter_mcp/snapshots/
• バンドル：.flutter_mcp/bundles/

状態操作では、ロックと期限切れロックの TTL 回復機能を使用し、複数のエージェントが安全に並行動作できるようにします。

接続解決の UX

サーバーは起動時にブロックせず、VM 依存の呼び出しが実行されるまでターゲットのロックを遅らせます。

VM 依存のコマンド／リソースに対する解決ポリシー：

1. アクティブな接続が引き続き正常であれば、それを再利用します。
2. そうでない場合、現在の検出結果に存在する固定ターゲットを再利用します。
3. そうでない場合、検出されたターゲットが 1 つだけなら自動接続します。
4. 複数のターゲットが存在し、明示的なターゲットが指定されていない場合は、connection_selection_required で失敗します。

選択が必要なエラーは、エージェントがすぐに再試行できるよう、構造化 JSON として返されます。

{
  "code": "connection_selection_required",
  "message": "Multiple debug targets detected. Retry with URI connection.targetId.",
  "descriptor": {
    "category": "validation",
    "retryable": true,
    "exitCode": 64,
    "httpLikeStatus": 409
  },
  "details": {
    "reason": "multiple_targets",
    "availableTargets": [
      {
        "targetId": "ws://127.0.0.1:8181/<token>/ws",
        "host": "localhost",
        "port": 8181,
        "endpoint": "ws://127.0.0.1:8181/<token>/ws",
        "isSticky": false,
        "isCurrent": false
      }
    ],
    "suggestedAction": "retry_with_connection_target",
    "example": {
      "connection": { "targetId": "ws://127.0.0.1:8181/<token>/ws" }
    },
    "howToRetry": {
      "connection": { "targetId": "ws://127.0.0.1:8181/<token>/ws" }
    }
  },
  "recovery": {
    "summary": "Select an explicit VM target and retry the command.",
    "fix_command": "flutter-mcp-toolkit exec --name discover_debug_apps --args '{}'"
  }
}

CLI のワンショット呼び出しとデーモン呼び出しは、同じハンドシェイクの動作を使用します。複数ターゲットがあり曖昧なセッションでは、明示的なセレクターを指定して再試行してください。

{
  "connection": { "targetId": "ws://127.0.0.1:8181/<token>/ws" }
}

すべての VM 依存 MCP ツールで、任意の arguments.connection を指定できるようになりました。

{
  "connection": {
    "targetId": "ws://127.0.0.1:8181/<token>/ws",
    "mode": "auto",
    "host": "localhost",
    "port": 8181,
    "uri": "ws://127.0.0.1:8181/<token>/ws",
    "forceReconnect": false
  }
}

注意：

• targetId は推奨されるセレクターで、完全な VM WebSocket URI である必要があります。
• レガシーの host:port 形式のターゲット ID は拒否されます。URI 形式のターゲット ID または connection.uri を使用してください。
• 最も安全なセレクターは、Flutter マシンの app.debugPort.wsUri と完全に一致する connection.uri です。
• targetId の検索に失敗し、URI が完全なトークン付き VM パス（/<token>/ws）の場合、サーバーは直接接続へのフォールバックを試みます。
• CLI の exec --args とデーモンの command/execute／watch/start では、同じ任意のネストされた connection オブジェクトを指定できます。
• connect_debug_app でも同じ形式の connection を使用できます。
• 動的レジストリツール（fmt_list_client_tools_and_resources、fmt_client_tool、fmt_client_resource）でも、同じ任意の connection を指定できます。
• リソースの読み取りでは、クエリによるターゲット指定（targetId、mode、host、port、uri、forceReconnect）もサポートされます。
• ツール引数で、トップレベルにフラットに指定する host／port／uri などの接続エイリアスは、厳密なスキーマによって意図的に拒否されます。
• connect と session_start では、ネイティブのセレクター引数（mode、targetId、host、port、uri、force）とネストされた connection を併用できません。

間違いを防ぐ手順：

1. マシンの app.debugPort.wsUri を読み取ります。
2. {"connection":{"uri":"<that exact wsUri>"}} を使用します。
3. targetId を使用する場合は、availableTargets／discover_debug_apps から正確にコピーします。

Flutter Web の検出

検出順序は次のとおりです。

1. Flutter によるマシン検出（flutter attach --machine）
2. ポートスキャンによるフォールバック

CLI と MCP サーバーの両方で、次のオプションを指定できます。

• --flutter-project-dir
• --flutter-device（例：chrome）
• --flutter-discovery-timeout-ms
• --scan-ports（例：8765-8767,9100）
• --prefer-target-label（例：staging）

ポートスキャンでは、dart／flutter プロセスを検出します。デスクトップアプリは VM サービスを独自のネイティブプロセス内でホストします。また、--no-dds を指定して起動したアプリには Dart プロセスがないため、どちらも名前による検出はできません。このようなアプリは、VM サービスのポートを固定して起動し（flutter run -d macos --device-vmservice-port=8765）、そのポートを --scan-ports=8765 でスキャナーに渡してください。

複数のデバッグアプリが同時に実行されている場合は、それぞれに MCPToolkitBinding.instance.setAppIdentity(label: 'my_app · staging') を設定して名前を付けます。検出結果では各ターゲットにラベルが表示され、--prefer-target-label を指定すると、呼び出し元がエンドポイントを指定しなくても自動接続で対象を選択できます。このラベルで候補が絞り込まれるのは自動接続の段階のみのため、アクティブな接続と明示的に接続されたターゲットが引き続き優先されます。実行中のアプリに一致する値がない場合は無視されるため、ラベルを指定しない場合と同じように検出が行われます。

手動でのフォールバックも引き続き利用できます。

• CLI：--vm-service-uri ws://127.0.0.1:59490/<token>/ws
• MCP ツール／リソースの呼び出し：arguments.connection.uri

クイックスタート

📦 GitHub からのインストール（現在推奨）

プロジェクトへの貢献や、ソースから直接最新版を実行したい開発者は、次の手順に従ってください。

1. リポジトリをクローンします：

   git clone https://github.com/Arenukvern/mcp_flutter
   cd mcp_flutter
   

2. 依存関係をインストールしてビルドします：

   make install
   

   このコマンドは、pubspec.yaml に記載されているすべての依存関係をインストールし、その後 MCP サーバーをビルドします。

3. Flutter アプリに mcp_toolkit パッケージを追加します：

   mcp_toolkit パッケージは、Flutter アプリケーション内で必要なサービス拡張機能を提供します。アプリの pubspec.yaml に追加する必要があります。

   Flutter アプリのディレクトリで次のコマンドを実行し、mcp_toolkit パッケージを追加します。

   flutter pub add mcp_toolkit
   

   または、手動で pubspec.yaml に追加します。

   dependencies:
     flutter:
       sdk: flutter
     # ... other dependencies
     mcp_toolkit: ^3.0.0
   

   その後、Flutter アプリのディレクトリで flutter pub get を実行します。

4. アプリを初期化します： Flutter アプリケーションの main.dart ファイル（または同等のエントリーポイント）で、ブリッジバインディングを初期化します。

   import 'package:flutter/material.dart';
   import 'package:mcp_toolkit/mcp_toolkit.dart'; // Import the package
   import 'dart:async';
   
   Future<void> main() async {
     runZonedGuarded(
       () async {
         WidgetsFlutterBinding.ensureInitialized();
         MCPToolkitBinding.instance
            ..initialize() // Initializes the Toolkit
            ..initializeFlutterToolkit(); // Adds Flutter related methods to the MCP server
         runApp(const MyApp());
       },
       (error, stack) {
         // You can place it in your error handling tool, or directly in the zone. The most important thing is to have it - otherwise the errors will not be captured and MCP server will not return error results.
         MCPToolkitBinding.instance.handleZoneError(error, stack);
       },
     );
   }
   
   // ... rest of your app code
   

5. Flutter アプリをデバッグモードで起動します

   flutter run --debug --machine --host-vmservice-port=8181 -d macos
   

   デバイスに合わせて -d を調整してください。マシン出力に含まれる正確な app.debugPort.wsUri を、arguments.connection.uri または connection.targetId で指定することをおすすめします。

6. 🛠️ AI クライアントに Flutter MCP Toolkit を追加します

   推奨（スキル＋MCP 設定）：

   flutter-mcp-toolkit init claude-code   # or: cursor | codex | cline | agents-skills
   

   オープンな Agent Skills エコシステムを利用したスキルのみの設定：

   npx skills add Arenukvern/mcp_flutter -a cursor -y
   

   インストール先、ロックファイル、skills.sh については、docs/ai_agents/overview.mdx を参照してください。

   手動での mcpServers JSON 設定（上級者向け — init を利用できない場合に使用）：

   mcpServers のレジストリキーには、標準の flutter-mcp-toolkit を使用してください。設定の名前変更前から使っている場合は、旧式のキー flutter-inspector も引き続き使用できます。この文字列は mcpServers の ID のみを指し、Claude Code のサブエージェント名ではありません。同梱のランタイムサブエージェントは flutter-mcp-toolkit-runtime（plugin/agents/flutter-mcp-toolkit-runtime.md）です。

   推奨サーバー引数：--resources、--images、--dynamics（リソース／画像はデフォルトで有効です。動的レジストリを有効にするには --dynamics を指定します）。

   ローカル開発の場合の注意（GitHub からのインストール）：

   GitHub からインストールしてローカルでビルドした場合は、command に mcp_server_dart/build/flutter-mcp-toolkit-server を指定してください。上記のGitHub からのインストールを参照してください。

   Cline のセットアップ

   1. .cline/config.json に追加します：

      {
        "mcpServers": {
          "flutter-mcp-toolkit": {
            "command": "/path/to/your/cloned/mcp_flutter/mcp_server_dart/build/flutter-mcp-toolkit-server",
            "args": [
              "--dart-vm-host=localhost",
              "--dart-vm-port=8181",
              "--resources",
              "--images",
              "--dynamics"
            ],
            "env": {},
            "disabled": false,
            "autoApprove": []
          }
        }
      }
      

   2. Cline を再起動します
   3. Flutter MCP toolkit のツールが会話で利用できるようになります
   4. 「アプリのスクリーンショットを撮ってください」と試してみてください（MCP ツールでは fmt_ プレフィックスが使われます。例：fmt_get_screenshots）

   Cursor のセットアップ

   バッジ

   サーバーをインストールします（クリックした後、Cursor でパスを編集してください）：

   

   注：インストール後に command のパスを修正してください。

   手動でのセットアップ

   1. Cursor の設定を開きます

   2. Features タブに移動します

   3. 「Model Context Protocol」の下で、サーバーを追加します：

      {
        "mcpServers": {
          "flutter-mcp-toolkit": {
            "command": "/path/to/your/cloned/mcp_flutter/mcp_server_dart/build/flutter-mcp-toolkit-server",
            "args": [
              "--dart-vm-host=localhost",
              "--dart-vm-port=8181",
              "--resources",
              "--images",
              "--dynamics"
            ],
            "env": {},
            "disabled": false,
            "autoApprove": []
          }
        }
      }
      

   4. Cursor を再起動します

   5. Agent Panel を開きます（macOS では cmd + L）

   6. ツール呼び出しでは、MCP の通信に fmt_* という名前を使用します（例：fmt_capture_ui_snapshot）。

   Claude のセットアップ

   1. Claude の設定ファイルに追加します：

      {
        "mcpServers": {
          "flutter-mcp-toolkit": {
            "command": "/path/to/your/cloned/mcp_flutter/mcp_server_dart/build/flutter-mcp-toolkit-server",
            "args": [
              "--dart-vm-host=localhost",
              "--dart-vm-port=8181",
              "--resources",
              "--images",
              "--dynamics"
            ],
            "env": {},
            "disabled": false,
            "autoApprove": []
          }
        }
      }
      

   2. Claude を再起動します
   3. Flutter MCP toolkit のツールが利用できるようになります
   4. 「アプリのスクリーンショットを撮ってください」と試してみてください

開発

コマンドラインオプション

./build/flutter-mcp-toolkit-server [options]

Options:
  --dart-vm-host                Host for Dart VM connection (default: localhost)
  --dart-vm-port                Port for Dart VM connection (default: 8181)
  --resources                   Enable resources support (default: true)
  --images                      Enable images support (default: true)
  --save-images        Save captured images as files in temporal folder instead of returning base64 data (default: false)
  --dumps                       Enable dumps support (default: false)
  --await-dnd                   Wait until DND connection is established (default: false). Do not use with Windsurf. Workaround for MCP Clients which don't support tools updates. Important: some clients doesn't support it. Use with caution. (disable for Windsurf, works with Cursor)
  --log-level                   Logging level (default: critical)
  --environment                 Environment (default: production)
  -h, --help                    Show usage text

画像ファイル保存モード

--save-images を有効にすると、サーバーは次の処理を行います：

• キャプチャしたすべてのスクリーンショットを、現在の作業ディレクトリ内の .mcp_screenshots フォルダーに PNG ファイルとして保存します
• base64 エンコードされた画像データの代わりに、ファイル URL（file://）を返します
• 24 時間より古いスクリーンショットを自動的に削除します
• screenshot-2025-01-27T10-30-15.123Z.png のようなタイムスタンプ付きのファイル名を使用します

このモードは、次の場合に便利です：

• base64 データよりもファイル参照を優先する AI ツールを使用する場合
• 後で分析できるようにスクリーンショットを保存しておく必要がある場合
• 応答内の大きな base64 文字列を避けて、メモリ使用量を削減する場合

基本的な使い方

1. Flutter アプリをデバッグモードで起動します：

   flutter run --debug --dart-vm-host=localhost --dart-vm-port=8181
   

2. MCP サーバーを実行します：

   ./build/flutter-mcp-toolkit-server