flutter-mcp-toolkit-maintain-web

用途

该技能用于维护 flutter_test_app 与 intentcall 项目的 Web 目标，主要围绕 Chrome 浏览器运行环境与 WebMCP 能力展开。典型使用场景是在编辑 web/index.html、执行 Web 平台代码生成、引导 WebMCP、启动 web-showcase、或运行 webmcp 验证时使用。

Dogfood 应用为 flutter_test_app，规范平台文档位于 flutter_test_app/INTENTCALL_PLATFORM.md。

WebMCP 与 VM MCP 的区分

技能文档用表格区分两条路径各自能够证明的内容：

路径：VM extensions + fmt_* 工具 —— 证明 MCP toolkit dogfood（始终）。
路径：document.modelContext —— 证明真正的 WebMCP（需要 Chrome flag / --web-browser-flag）。

相关 ADR 记录在 decisions/0008_web_agent_invoke_js_only.mdx：JS 调用 fetch('/agent/invoke') 返回 404 是设计使然；当 modelContext 存在时，Dart 的 invokeDirect 可以正常工作。

启动方式（可重复的 WebMCP）

make web-showcase
# WS_URI 来自 .showcase/web_app.log（热重载后需重新 grep）
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，因为它在不同机器上表现不一致——应使用 webmcp chrome-args 或 make web-showcase。

代码生成与钩子

多平台代码生成同步命令：

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

平台初始化（带校验）：

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

产物与来源对应关系：

产物：web/intentcall_webmcp.generated.js —— 来源：由 web/agent_manifest.json 经 codegen sync 生成。
产物：web/index.html —— 来源：init intentcall-platform 写入的 script 标签。
Dart bootstrap：registerAgentWebMcpFromEntries，位于 mcp_toolkit_extensions.dart（debug web，在 addEntries 之后；intentcall_platform）。

运行时校验

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>。

已知问题

重复工具名：生成的 JS 与 registerAgentWebMcpFromEntries 都会调用 registerTool；需要去重或屏蔽其中一条路径（agent_web_mcp_bootstrap_web.dart 的名称缓存）。
CDP 探测：webmcp verify 可能在 CDP 的 hasModelContext 为 false 时仍报告 webmcp_active_log_evidence（Flutter 执行上下文问题）。
过期 WS_URI：热重启后务必重新 grep 获取新 token，再进行 eval/validate。

技能介绍

用途