flutter-mcp-toolkit-maintain-web

Web の保守（Chrome + WebMCP）

動作確認用アプリ：showcase/flutter_test_app。プラットフォームの正規ドキュメント：showcase/flutter_test_app/INTENTCALL_PLATFORM.md。

WebMCP と VM MCP

パス	検証できること
VM extensions + fmt_* tools	MCP ツールキットの動作確認（常時）
navigator.modelContext / document.modelContext	真の WebMCP（Chrome フラグ / --web-browser-flag）

ADR：decisions/0008_web_agent_invoke_js_only.mdx — JS fetch('/agent/invoke') は設計上 404 を返します。modelContext が存在する場合は Dart の invokeDirect が動作します。

JIT と AOT の Web：どの操作階層を使うか

VM extensions（fmt_*、ツールキット）には Dart VM サービスが必要です。JIT Web（flutter run 経由の DDC）では利用できます。AOT Web ビルド（flutter build web）には VM サービスがありません。そのため、ブラウザレベルのプリミティブ（universal-automation-family ADR-0045）を介して、CDP 階層の flutter_mcp_harness の WebBuildTarget/FlutterWebCdp（このリポジトリ、ADR-0018）で操作してください。AOT Web で型付きアプリインテントを使うには、window.__mcpActions ハンドラー（プレーンな JS 相互運用、AOT 対応）を公開します。CDP ドライバーの InvokeAction がこれらに処理をディスパッチします。ツールキットのツールカタログをこのレジストリに投影するためのブリッジは、追跡対象です。

起動（再現可能な WebMCP）

make web-showcase
# WS_URI from .showcase/web_app.log (re-grep after hot reload)
grep -Eo 'ws://127\.0\.0\.1:[0-9]+/[A-Za-z0-9_=-]+/ws' .showcase/web_app.log | tail -1

dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart webmcp chrome-args
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart webmcp verify --web-port 8080

停止：make showcase-stop。

マシン間で chrome://flags だけに依存しないでください。CLI フラグ / make web-showcase / VS Code の起動引数を使用してください。

VS Code / Cursor の起動

.vscode/launch.json の構成 showcase/flutter_test_app Chrome + WebMCP を使用してください。

• --web-browser-flag=--user-data-dir=${workspaceFolder}/.showcase/chrome-webmcp-profile — chrome://flags の設定が停止／起動後も保持されるようにする永続プロファイルです（Flutter の既定設定では、実行のたびに一時プロファイルが使用されます）。
• --web-browser-flag=--enable-features=WebMCPTesting,WebModelContext,DevToolsWebMCPSupport
• --web-browser-flag=--enable-experimental-web-platform-features

値にリテラルの引用符を含めないでください（"./…" という名前のディレクトリが作成されるのを防ぎます）。

Chrome 149+ の Application → WebMCP ペインでは、#devtools-webmcp-support / 機能 DevToolsWebMCPSupport も必要です（API だけではこの UI を使用できません）。

エージェント WebMCP（Chrome DevTools MCP）— ライブ呼び出しに推奨

エージェントでページのツールを操作する場合は、flutter_mcp_toolkit webmcp verify --tool-name よりも chrome-devtools MCP（list_webmcp_tools、execute_webmcp_tool）を優先してください。

インストール（初回のみ）

Grok（~/.grok/config.toml）：

[mcp_servers.chrome-devtools]
command = "npx"
args = [
  "-y",
  "chrome-devtools-mcp@latest",
  "--categoryExperimentalWebmcp",
  "--chromeArg=--enable-features=WebMCP,WebModelContext,DevToolsWebMCPSupport,WebMCPTesting",
  "--chromeArg=--enable-experimental-web-platform-features",
  "--userDataDir=/Users/YOU/.cache/chrome-devtools-mcp/chrome-profile-webmcp",
  "--no-usage-statistics",
]
enabled = true
startup_timeout_sec = 90

または：grok mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest --categoryExperimentalWebmcp ...

Cursor — ~/.cursor/mcp.json の mcpServers.chrome-devtools に同じ command/args を設定します。

インストール後、エージェントのセッションを再起動してください。診断：grok mcp doctor chrome-devtools。

ライブフロー

1. アプリを配信しておきます（例：make web-showcase または :8080 で VS Code Chrome + WebMCP）。
2. list_pages — chrome-devtools が独自のブラウザー（about:blank）を起動する場合があります。
3. navigate_page → http://localhost:8080/（またはアプリの URL）。
4. Flutter/Dart のブートストラップが完了するまで待ちます（最初の list_webmcp_tools の結果が空の場合があります）。
5. list_webmcp_tools — IntentCall ツールと、多くの場合 modelContext に登録された mcp_* ツールキットのツールが表示されます。
6. 必要に応じて、toolName と JSON 文字列の input を指定して execute_webmcp_tool を実行します。

IntentCall ツールの例：app_enable_switch（引数なし）、app_set_greeting（{"text":"…"}）、app_intentcall_bridge_ping（{"echo":"…"}）、app_get_agent_showcase_state。

execute_webmcp_tool
  toolName: app_enable_switch
  input: {}

フォールバック（CLI、chrome-devtools MCP なし）

dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart webmcp verify --web-port 8080 \
  --tool-name app_enable_switch --tool-args '{}'

コード生成とフック

dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart codegen sync \
  --platform web,android,ios,macos,linux,windows \
  --project-dir showcase/flutter_test_app

dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart init intentcall-platform \
  --project-dir showcase/flutter_test_app --check

成果物	ソース
web/intentcall_webmcp.generated.js	web/agent_manifest.json からの codegen sync
web/index.html	init intentcall-platform スクリプトタグ
Dart ブートストラップ	アプリが登録する投影 — showcase では ShowcaseWebMcpProjection（intentcall_showcase_bootstrap.dart 内）で、intentcall_platform_sync の projectEntriesToWebMcp をラップします。MCPToolkitBinding.addEntryListener（ADR-0016）経由で接続されています。

ランタイムの検証

dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart --save-images \
  --output-dir .showcase/web_iter validate-runtime \
  --target "$WS_URI" \
  --flutter-device chrome \
  --timeout-ms 45000

CDP の検出に失敗する場合は、--web-browser-debugging-port <cdp> を渡してください。

既知の問題

1. ツール名の重複 — 生成された JS と WebMCP のプロジェクション（projectEntriesToWebMcp）がどちらも registerTool を呼び出します。一方を重複排除するか、無効にしてください（agent_web_mcp_bootstrap_web.dart の名前キャッシュ）。
2. CDP のプローブ — webmcp verify は、CDP の hasModelContext が false（Flutter の実行コンテキスト）であっても、webmcp_active_log_evidence を報告することがあります。
3. 古い WS_URI — ホットリスタートの後、評価／検証の前に必ず最新のトークンを grep してください。
4. ナビゲーション直後の WebMCP リストが空 — Dart フック／登録が完了するまで待ってから、再度リストを取得してください。
5. 一時的な Chrome プロファイル — --user-data-dir がない場合、Flutter は停止／起動のたびに chrome://flags を消去します。
6. 2 つのブラウザー — --browser-url=http://127.0.0.1:<cdpPort> で接続しない限り、chrome-devtools MCP のプロファイルと Flutter が起動した Chrome は別のものです。

関連情報

• docs/superpowers/evals/2026-05-26-webmcp-verification.md
• flutter-mcp-cli-runtime-validation — ランタイム検証の詳細
• flutter-mcp-toolkit-dogfood-iterations — スコア付きのイテレーション
• flutter-mcp-e2e-harness — このショーケースを対象とするプログラムによるシナリオ（packages/harness、--web --detach バリアント）
• Chrome DevTools MCP：https://github.com/ChromeDevTools/chrome-devtools-mcp（WebMCP ツールには --categoryExperimentalWebmcp と Chrome 149 以降が必要です）