flutter-mcp-toolkit-maintain-web

维护 Web（Chrome + WebMCP）

Dogfood 应用：showcase/flutter_test_app。规范平台文档：showcase/flutter_test_app/INTENTCALL_PLATFORM.md。

WebMCP 与 VM MCP

路径	验证内容
VM 扩展 + fmt_* 工具	MCP 工具包 dogfood（始终可用）
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 扩展（fmt_*，即工具包）需要 Dart VM 服务——它们在 JIT Web 上可用（通过 flutter run 使用 DDC）。AOT Web 构建（flutter build web）没有 VM 服务：应通过 CDP 层级驱动——使用本仓库的 flutter_mcp_harness 中的 WebBuildTarget/FlutterWebCdp（ADR-0018），通过浏览器级原语操作（universal-automation-family ADR-0045）。要在 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+ 的“应用程序”→WebMCP 面板还需要启用 #devtools-webmcp-support / 功能 DevToolsWebMCPSupport（仅有 API 不足以显示该 UI）。

Agent WebMCP（Chrome DevTools MCP）——推荐用于实时调用

当 Agent 需要驱动页面工具时，优先使用 chrome-devtools MCP（list_webmcp_tools、execute_webmcp_tool），而不是 flutter_mcp_toolkit webmcp verify --tool-name。

安装（仅需一次）

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。

安装后重启 Agent 会话。检查命令：grok mcp doctor chrome-devtools。

实时流程

1. 应用必须正在运行（例如，通过 make web-showcase 启动，或在 VS Code 中启动 Chrome + WebMCP，并使用 :8080）。
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 可能会报告 webmcp_active_log_evidence，而 CDP hasModelContext 为 false（Flutter 执行上下文）。
3. 过期的 WS_URI — 热重启后，务必先搜索最新令牌，再执行 eval/validate。
4. 导航后 WebMCP 列表为空 — 等待 Dart 钩子/注册完成，然后再次列出。
5. Chrome 临时配置文件 — 如果不使用 --user-data-dir，Flutter 会在每次停止/启动时清除 chrome://flags。
6. 两个浏览器 — chrome-devtools MCP 配置文件 ≠ Flutter 启动的 Chrome，除非通过 --browser-url=http://127.0.0.1:<cdpPort> 连接。

相关内容

• 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+）