flutter-mcp

Flutter MCP

Agent 通过 flutter-mcp-toolkit MCP 服务入口操控正在运行的 Flutter 应用的黄金路径。旧配置可能会对同一个二进制使用旧版 flutter-inspector mcpServers 注册 ID（该 ID 不是 Claude 子 Agent flutter-mcp-toolkit-runtime）。

何时使用

• 用户提到正在运行的 Flutter 应用（调试模式），并希望检查、截图、交互或热重载。
• 用户粘贴了 VM 服务 URI（ws://127.0.0.1:8181/.../ws），或提到端口 8181。
• 你需要运行时证据（操作前后的截图）来确认代码修改已生效。

预检（始终先执行）

执行任何依赖 VM 的调用之前：

1. 调用 doctor（或运行 flutter-mcp-toolkit doctor --json）——解析环境、端口和应用可访问性。
2. 确认目标上存在所需的工具包扩展：
   • ext.mcp.toolkit.app_errors
   • ext.mcp.toolkit.view_details
   • ext.mcp.toolkit.view_screenshots
   • ext.mcp.toolkit.inspect_widget_at_point

如果缺少扩展，请停止并报告插桩缺失问题——不要猜测：

• 将 mcp_toolkit 添加到 pubspec.yaml。
• 确保在 runApp 之前运行 MCPToolkitBinding.instance..initialize()..initializeFlutterToolkit();。
• 执行热重启（而非热重载）——热重载通常不足以注册扩展。

工具命名（v3.0.0+）

所有 MCP 工具都使用 fmt_ 能力前缀 （fmt_tap_widget、fmt_hot_reload_and_capture 等）。在 tools/call 中必须使用此前缀。下文技能中的引用为便于阅读而省略了前缀——调用时请加上 fmt_。动态注册表主机工具 （fmt_list_client_tools_and_resources、fmt_client_tool、fmt_client_resource）也使用相同前缀，以保持调用入口一致。

交互循环（类似 Playwright）

1. fmt_semantic_snapshot → 返回 s_0..s_N 引用和 snapshot_id。
2. fmt_tap_widget / fmt_enter_text / fmt_scroll / fmt_swipe / fmt_long_press / fmt_drag——对某个引用执行操作。始终传入 snapshotId——如果树发生变化，你会收到结构化的 stale_snapshot 错误，而不是悄无声息地误触。
3. fmt_reveal_search——针对屏幕外的语义目标，执行有界的快照/搜索/滚动，并返回新的 ref 和 snapshotId。
4. fmt_evaluate_dart_expression——直接读取状态（例如 AgentState.instance.counter）。
5. fmt_hot_reload_and_capture——代码修改后调用，一次性返回热重载状态、截图、新快照和错误。优先使用此工具，而不是手动热重载后再单独截图。

错误封装约定

错误格式为 {code, message, details, descriptor, recovery}。应解析 error.descriptor（而非顶层对象）以获取机器可读的结构。严格模式的架构默认设置为 additionalProperties: false——未知参数会被拒绝。

常见代码及恢复方法：

• connection_selection_required——使用 arguments.connection.targetId 重试，或传入从 app.debugPort.wsUri 获取的精确 arguments.connection.uri。
• target_not_found——刷新目标，然后优先使用精确的 arguments.connection.uri。
• stale_snapshot——重新调用 fmt_semantic_snapshot，然后使用新的 snapshotId 输入重试操作。
• tool_not_found——确认使用了带前缀的名称（fmt_<tool>）；v3.0.0 已移除不带前缀的旧名称。
• 截图输出为空——确认服务启动时没有使用 --no-images。
• 缺少视图资源/工具——确认服务启动时没有使用 --no-resources。

视觉 QA

• 操作前后的截图是所有 UI 声明的证明材料。先用 fmt_capture_ui_snapshot（或某个 visual://localhost/... 资源）截图，然后修改，再调用 fmt_hot_reload_and_capture 并进行比较。
• 对每个报告的视觉问题，附上坐标以及 fmt_inspect_widget_at_point 的输出。
• 在可用时，根据 fmt_get_app_errors 的顶部堆栈帧（file、line、column）将缺陷对应到源代码。
• 除非用户明确要求，否则不要使用 fmt_debug_dump_*（服务必须以 --dumps 启动；该操作会消耗大量 Token）。

权限（macOS）

屏幕录制权限属于运行 flutter-mcp-toolkit 的进程（或 MCP 服务宿主）。如果视觉捕获被拒绝：

flutter-mcp-toolkit permissions status
flutter-mcp-toolkit permissions request
flutter-mcp-toolkit permissions open-settings

不可修改的应用

如果无法为目标应用添加检测（第三方二进制文件、受限环境），请报告 flutter-mcp 无法用于该应用。不要声称已成功检查截图、布局或错误。

相关内容

• 关于动态工具方面（在 Flutter 应用内部注册自定义 MCP 工具），请参阅 flutter-mcp-toolkit-custom-tools 技能。
• 关于在 setup / inspect / control / debug 技能之间进行路由，请参阅 flutter-mcp-toolkit-guide。
• 关于以 Dart 代码形式纳入版本控制的可重复场景（不使用 MCP 进行构建/启动/附加/驱动/断言），请参阅 flutter-mcp-e2e-harness。