flutter-mcp-toolkit-setup

使用する場面

次の場合にこのスキルを使用します：

• 初回インストール時：flutter-mcp-toolkit または短縮エイリアスの fmtk がまだ PATH にありません。
• doctor --json で、いずれかのチェックが "status": "fail" を返します。
• MCP サーバーへの接続に失敗するか、ツールが vm_not_connected / connect_failed を返します。
• ビジュアルキャプチャまたは toolkit-bridge コマンドで予期しないエラーが発生します。

---

インストールを確認する

flutter-mcp-toolkit --help
fmtk --help

期待される出力：両方の名前でコマンドヘルプが表示されます。flutter-mcp-toolkit は正式な長い名前で、fmtk は日常的なターミナル操作で使う短縮エイリアスです。

command not found が表示される場合、バイナリが PATH にありません：

# Binary is built to mcp_server_dart/build/ inside the repo
export PATH="$PATH:/path/to/mcp_flutter/mcp_server_dart/build"
# Or rebuild from source
cd /path/to/mcp_flutter && make build

続いて flutter-mcp-toolkit --help と fmtk --help で確認します。

---

doctor を実行する

VM に依存するコマンドを実行する前に、必ず doctor を実行します：

fmtk doctor --json

フラグ：--target <ws_uri>（特定の URI をテストします）、グローバルな --vm-service-uri <ws_uri>（doctor で省略した場合は --target と同じです）、--timeout-ms <n>（デフォルト：2500）。

# Global URI works for doctor (same as validate-runtime)
fmtk --vm-service-uri 'ws://127.0.0.1:8181/<token>/ws' doctor --json

正常な出力例：

{
  "summary": { "criticalFailures": 0 },
  "checks": [
    { "id": "vm_target_reachable", "status": "pass", "critical": true },
    { "id": "mcp_toolkit_extensions", "status": "pass", "critical": true },
    { "id": "dynamic_registry_available", "status": "pass", "critical": false }
  ]
}

切り分け： criticalFailures > 0 は VM／セットアップがブロックされていることを意味します。すべてのツールが壊れているという意味ではありません。dynamic_registry_available: pass かつ vm_target_reachable: fail の場合、通常はホットリスタート後に URI が古くなっています。discover_debug_apps を実行し、新しい targetId を渡します。

再試行ポリシーと終了コードを確認するには、トップレベルではなく error.descriptor を読みます。各チェックには fix_command が含まれています。これをそのまま実行します。

---

エラーコード別に復旧する

binary_not_found

バイナリが見つからないか、PATH にありません。再ビルドして PATH に追加します：

cd /path/to/mcp_flutter && make build
export PATH="$PATH:/path/to/mcp_flutter/mcp_server_dart/build"

vm_not_connected

Flutter アプリが実行されていない、再起動後にトークンが古くなっている、または URI が解決されていません：

fmtk exec --name discover_debug_apps --args '{}'
fmtk exec --name status --args '{}'
fmtk doctor --json --target ws://127.0.0.1:8181/<new-token>/ws

自動再接続が成功すると、meta.recovery.reattachedTo に新しいエンドポイントが表示されます。

connect_failed

ポートが間違っている、アプリが起動していない、またはトークンが古くなっています。app.debugPort.wsUri の明示的な URI を渡します：

fmtk exec --name get_vm --args '{"connection":{"uri":"ws://127.0.0.1:8181/<token>/ws"}}'

connection_selection_required

複数のデバッグターゲットが検出されました。discover_debug_apps で一覧を表示し、details.availableTargets にある選択した URI を get_vm に明示的に渡します。

hot_reload_failed

Dart のコンパイルエラー、または VM の切断が発生しています。エラーを確認して修正し、再試行します：

fmtk exec --name get_app_errors --args '{}'

visual_capture_unsupported

macOS の画面収録権限が許可されていないか、プラットフォームがサポートされていません：

fmtk permissions request --kind visual_capture

---

接続の問題（詳細なトラブルシューティング）

ポートの競合：VM サービスのデフォルトポートは 8181 です。別のプロセスが使用している場合は変更します：

flutter run --debug --host-vmservice-port=8182 -d macos
fmtk --dart-vm-port 8182 doctor --json

正確な WebSocket URI が必要な場合（validate-runtime および exec で推奨）は、flutter run --machine を使用し、app.debugPort.wsUri をコピーします。

Flutter アプリがデバッグモードではない：リリース／プロファイルビルドでは VM サービスが公開されません。必ず flutter run --debug を使用します。

mcp_toolkit が初期化されていない：doctor の mcp_toolkit_extensions チェックが失敗します。runApp の前に追加します。flutter-mcp-toolkit codegen-init を使うと、ひな形を生成できます（以下の CLI の概要を参照）。追加後はホットリスタートします（ホットリロードではありません。バインディングの初期化には完全な再起動が必要です）。

複数のアプリ／誤ったターゲット：正確な WebSocket URI を指定して --target を渡します：

fmtk doctor --json --target ws://127.0.0.1:8181/<token>/ws

---

CLI の概要

正式なバイナリは flutter-mcp-toolkit（mcp_server_dart/build/ にビルドされます）です。パッケージ版のインストールには、同じエントリーポイントを指す短縮エイリアス fmtk も含まれます。手早く繰り返し操作する場合は fmtk を使用し、インストール、オンボーディング、PATH、MCP 設定のドキュメントでは長い名前を使用します。

サブコマンド	目的	最小限の例
exec	VM に対して名前を指定した単一のコマンドを実行します	fmtk exec --name get_vm --args '{}'
batch	1 回の呼び出しで複数のコマンドを実行します	fmtk batch --steps '[{"name":"get_vm"},{"name":"status"}]'
schema	名前を指定したコマンドの JSON スキーマを出力します	fmtk schema --name hot_reload_flutter
capabilities	登録済みのすべての機能を一覧表示します	fmtk capabilities
serve	MCP サーバーを起動します（stdio トランスポート）	fmtk serve
snapshot create	名前を付けたスナップショットを取得して保存します	fmtk snapshot create --name baseline --args '{}'
snapshot diff	2 つのスナップショットの差分を表示します	fmtk snapshot diff --from baseline --to current
bundle create	スナップショットを公開可能なバンドルにパッケージ化します	fmtk bundle create --from-snapshot baseline --output ./out
doctor	事前チェックを実行します（VM ＋ ツールキット ＋ レジストリ）	fmtk doctor --json
permissions status	権限を確認します（例：visual_capture）	fmtk permissions status --kind visual_capture
permissions request	権限をリクエストします	fmtk permissions request --kind visual_capture
permissions open-settings	権限に関する OS の設定を開きます	fmtk permissions open-settings --kind visual_capture
validate-runtime	VM ＋ ツールキット ＋ キャプチャのエンドツーエンドのスモークテストを実行します	fmtk validate-runtime --target ws://127.0.0.1:8181/<token>/ws
init <agent>	AI エージェント向けのスキルと MCP サーバー設定をインストールします	flutter-mcp-toolkit init claude-code
codegen-init	ツールキットの依存関係を追加し、main.dart のボイラープレートを生成します	flutter-mcp-toolkit codegen-init

グローバルフラグ（サブコマンドの前に指定）：--dart-vm-port <n>、--dart-vm-host <host>、--vm-service-uri <ws_uri>、--log-level <level>、--dumps、-h/--help。

VM のターゲット指定： グローバルな --vm-service-uri は、サブコマンドの --target が省略された場合に doctor と validate-runtime に適用されます。両方が設定されていて値が異なる場合は、--target が優先されます（stderr に警告が出力されます）。

validate-runtime のスクリーンショット： 最初のキャプチャでは auto を使用します（macOS では多くの場合 desktop_window です）。このステップが再試行可能な get_screenshots_failed で失敗した場合、CLI は flutter_layer を使って 1 回再試行します。成功すると、JSON エンベロープ内の data.summary.captureFallbackUsed は true になります。 デバッグ／評価用のチェック: 繰り返し行うチェックは、まず既存のプリミティブに対するスクリプトまたは batch 呼び出しとして維持してください：--log-level debug、--output-dir、--save-images、doctor --json、validate-runtime、batch、exec --name diagnose。汎用的な MCP run_tool は公開しないでください。MCP は引き続き、型付きの fmt_* ツールインターフェースを使用します。あるフローがプロジェクト間でシナリオとして再利用できるようになったら、ツールキット専用のシナリオ言語を追加するのではなく、このリポジトリの showcase/ または packages/harness にチェックイン済みの Dart として採用してください。

---

init <agent>

AI エージェント向けに、flutter-mcp-toolkit のスキルと MCP サーバー設定をインストールします。

対象：claude-code | cursor | codex | cline | agents-skills | all。

flutter-mcp-toolkit init claude-code        # install for Claude Code (project-scoped)
flutter-mcp-toolkit init cursor --scope user # install user-globally for Cursor
flutter-mcp-toolkit init all --mode cli      # install for every detected agent in CLI mode

モードは自動検出されます（登録済みなら MCP、それ以外は CLI）。--mode mcp|cli|auto で上書きできます。

代替方法（スキルのみ、オープンなエコシステム向け）： npx skills add Arenukvern/mcp_flutter -a cursor -y を実行すると、skills.sh 経由で同じ SKILL.md バンドルをインストールできます。mcp.json は書き込まれません。後から init を実行するか、mcpServers を手動で設定してください。AI エージェントの概要を参照してください。

---

codegen-init

Flutter プロジェクトのルートから、依存関係として mcp_toolkit を追加し、 lib/main.dart 用のボイラープレートのスニペットを出力します。

cd my-flutter-app
flutter-mcp-toolkit codegen-init             # runs `flutter pub add` + prints snippet
flutter-mcp-toolkit codegen-init --no-pub-add  # snippet only, skip pub add

---

再インストール／アップグレード

インストールスクリプトは冪等です。再実行すると、バイナリがその場で置き換えられます。

curl -fsSL https://raw.githubusercontent.com/Arenukvern/mcp_flutter/main/install.sh | bash

再インストール後、flutter-mcp-toolkit --help と fmtk --help を実行して確認してください。