flutter-mcp-toolkit-inspect

适用场景

当你需要只读检查正在运行的 Flutter 应用状态时，可使用此技能：查看屏幕上显示的内容、最近的错误、可用的调试目标、VM 元数据和 widget 树详情。请勿用于驱动交互——那是 interact 技能的用途。尚未确定连接目标时，请从 discover_debug_apps 开始。需要了解屏幕上有哪些 widget 时，请从 semantic_snapshot 开始。

操作指南

快速检查流程（优先使用 batch）

flutter-mcp-toolkit batch --steps '[
  {"name":"semantic_snapshot"},
  {"name":"get_app_errors","args":{"count":5}},
  {"name":"get_screenshots","args":{"mode":"flutter_layer","compress":true}}
]'

在 macOS 上对 get_screenshots 使用 mode: flutter_layer，以避免屏幕录制权限失败。capture_ui_snapshot 使用单独的 screenshotMode 字段。

截取当前可见 UI

1. 调用 semantic_snapshot()。
2. 查看 interactionSurface：flutter_widgets（可通过 ref 点击）、hybrid（语义信息稀疏）、game_canvas（使用 evaluate_dart_expression 和截图）。
3. 每个可交互节点都有一个稳定的 ref（s_0、s_1……），响应中还包含 snapshot_id。
4. 将 ref 传递给交互工具；将 snapshot_id 值作为 snapshotId 传递，以检测信息是否过期。

修改代码后

优先使用 hot_reload_and_capture，而不是分别调用重新加载、快照和截图工具。

按消息查找错误

1. 调用 get_app_errors(count: 10)。
2. 检查 errors 数组——每个条目都包含消息、堆栈跟踪和时间戳。
3. 根据消息文本匹配以查找来源。

列出调试模式下的应用

1. 调用 discover_debug_apps()。
2. 查看每个活动目标的 targetId（规范的 WebSocket URI）。
3. 在后续工具调用中，将选定的 URI 作为 connection.targetId 传递。

获取指定坐标处的 widget

1. 调用 inspect_widget_at_point(x: 200, y: 400)。
2. 响应会标识这些全局逻辑像素坐标处最深层的 widget 和渲染节点。

将截图保存到文件

1. 调用 get_screenshots()。
2. 如果 meta.fileUrls 不为空，截图已保存在这些路径中。否则，响应会包含 base64 ImageContent 块——请手动提取并写入。
3. 如需强制输出到文件，请在调用前为服务配置图像输出目录。

工具参考

discover_debug_apps

列出所有活动 Flutter 调试目标及其规范的 WebSocket URI。

• connection（对象，可选）——架构接受此参数，但执行器会忽略；发现操作始终在本地进行。

discover_debug_apps()

返回：{"targets": [{"targetId": "ws://127.0.0.1:8181/<token>/ws", "host": "...", "port": 8181}]}

• vm_service_unavailable — 未找到处于调试模式的 Flutter 进程。
• tool_not_found — 二进制文件版本早于 v3.0.0；请运行 make build。

get_app_errors

从 Dart VM 获取最近的应用错误。

• count（整数，可选，默认值：4）——要返回的错误数量。
• connection（对象，可选）——连接覆盖设置。

get_app_errors(count: 5)

返回：{"message": "2 errors found", "errors": [{"message": "...", "stack": "..."}]}

• vm_service_unavailable — 无法访问应用。
• connection_selection_required — 存在多个目标；请提供 connection.targetId。

get_screenshots

截取所有视图的屏幕截图。

• compress（布尔值，可选，默认值：true）——压缩 PNG 输出。
• mode（字符串，可选，默认值：auto）——auto、flutter_layer 或 desktop_window。
• permissionPolicy（字符串，可选，默认值：check_only）——check_only、auto_request_once 或 request_always。
• connection（对象，可选）——连接覆盖设置。

get_screenshots(mode: "flutter_layer", compress: false)

返回：未配置输出目录时返回 ImageContent 块（base64 PNG）；启用文件输出时返回 TextContent URL 引用和 meta.fileUrls。

• permission_denied — 使用 permissionPolicy: "auto_request_once" 重试。
• vm_service_unavailable — 无法访问应用。

get_view_details

获取所有视图的尺寸、设备像素比和显示 ID。

• connection（object，可选）— 连接覆盖项。

get_view_details()

返回：{"views": [{"id": 0, "width": 1280, "height": 800, "devicePixelRatio": 2.0}]}

• vm_service_unavailable — 应用未运行。
• connection_selection_required — 存在多个目标；请提供 connection.targetId。

get_vm

返回 Dart VM 元数据：版本、隔离区列表、pid 和架构。

• connection（object，可选）— 连接覆盖项。

get_vm()

返回：{"type": "VM", "name": "vm", "version": "3.x.x", "isolates": [...]}

• vm_service_unavailable — 无法连接到应用。
• connection_selection_required — 存在多个活动目标。

get_extension_rpcs

列出运行中应用内所有已注册的 VM 服务扩展 RPC。

• isolateId（string，可选）— 模式中声明但执行器不会读取；省略时检查所有隔离区。
• isRawResponse（boolean，可选）— 模式中声明但执行器不会读取。
• connection（object，可选）— 连接覆盖项。

get_extension_rpcs()

返回：{"extensionRPCs": ["ext.flutter.inspector.getRootWidget", "ext.mcp.toolkit.semantic_snapshot"]}

• vm_service_unavailable — 应用未运行。
• connection_selection_required — 存在多个目标。

semantic_snapshot

返回交互式控件的精简无障碍树，其中包含稳定的 ref 字符串和 snapshot_id。如果节点能够读取（标签、值）、执行操作（按钮、文本字段、点击、滚动……）或带有 Semantics(identifier:)，就会列出该节点。

• identifierPrefix（string，可选）— 仅保留标识符以此前缀开头的节点（例如，用 "nav." 筛选一个导航栏）。
• subtreeOf（string，可选）— 仅保留一个节点及其后代；可以使用最新快照中的 ref 或标识符，优先尝试 ref。
• fields（array of strings，可选）— 要返回的节点键；始终保留 ref。可用名称：ref id type identifier label value hint enabled focused checked toggled selected bounds actions children visibleInViewport centerInViewport center。
• connection（object，可选）— 连接覆盖项。

始终遍历整棵树，因此从筛选快照中读取的 ref 与完整快照中的 ref 相同，并且可用于所有交互工具。筛选后的响应会添加 totalNodeCount 并回显 filter；children 仅列出保留的 ref。

semantic_snapshot()
semantic_snapshot(identifierPrefix: "nav.", fields: ["identifier", "selected"])
semantic_snapshot(subtreeOf: "panel.tabs")

返回：{"snapshot_id": 3, "nodeCount": 1, "viewport": {...}, "nodes": [{"ref": "s_0", "label": "Increment", "actions": ["tap"], "bounds": {...}, "visibleInViewport": true, "centerInViewport": true, "center": {...}}]} — 视口信息只会在外层结构中声明一次，不会在每个节点上重复声明。

• subtree_root_not_found — subtreeOf 既不是最新快照中的 ref，也不是树中的标识符；未获取快照，ref 和 snapshot_id 均未更改。
• unknown_field — fields 中的名称不是节点键；acceptedFields 会列出可用名称。通过 MCP 和 CLI 调用时，会在边界处拒绝该名称：如果 fields 参数无效（应使用可用键名），则不会调用应用。
• vm_service_unavailable — 应用未运行，或未调用 MCPToolkitBinding.initialize()。
• connection_selection_required — 存在多个目标；请提供 connection.targetId。

inspect_widget_at_point

识别全局逻辑坐标处最深层的控件和渲染节点。

• x（integer，必需）— 全局逻辑 X 坐标。
• y（integer，必需）— 全局逻辑 Y 坐标。
• viewId（integer，可选）— 多视图应用的 FlutterView ID。
• connection（object，可选）— 连接覆盖项。

inspect_widget_at_point(x: 200, y: 400)

返回：{"widget": {"type": "ElevatedButton", "rect": {"left": 180, "top": 380, "right": 280, "bottom": 420}}}

• vm_service_unavailable — 无法连接到应用。
• invalid_argument — 坐标超出视图边界。

capture_ui_snapshot

在一个打包响应中截取屏幕截图、查看详细信息和应用错误。

• errorsCount（整数，可选，默认值：4）— 要包含的错误数。
• compress（布尔值，可选，默认值：true）— 压缩屏幕截图。
• includeViewDetails（布尔值，可选，默认值：true）— 包含视图数据。
• includeErrors（布尔值，可选，默认值：true）— 包含应用错误。
• screenshotMode（字符串，可选，默认值：auto）— auto、flutter_layer 或 desktop_window。
• permissionPolicy（字符串，可选，默认值：check_only）— check_only、auto_request_once 或 request_always。
• connection（对象，可选）— 连接覆盖设置。

capture_ui_snapshot(errorsCount: 2, includeViewDetails: false)

返回：包含 screenshots、viewDetails 和 errors 键的 TextContent JSON 块。当 screenshots.images 中包含内嵌的 base64 数据时，每个数据都会提取到同级的图像块中，JSON 会报告 screenshots.imagesDeliveredAs: "image_blocks"；此时清空后的 images 列表是正常格式，并不表示捕获失败。通过 screenshots.fileUrls 传递的捕获内容会保留在 JSON 中，不会生成图像块。

• vm_service_unavailable — 应用未运行。
• permission_denied — 使用 permissionPolicy: "auto_request_once" 重试。

connect_debug_app

显式选择并连接到 Flutter 调试 VM 目标。当有多个应用正在运行，或要为当前会话固定特定目标时使用。

• connection（对象，可选）— 通过 discover_debug_apps 提供的 WebSocket URI 设置 connection.targetId。

connect_debug_app(connection: {targetId: "ws://127.0.0.1:8181/<token>/ws"})

返回：{"connected": true, "targetId": "ws://127.0.0.1:8181/<token>/ws", "isolates": [...]}

• target_not_found — URI 与正在运行的应用不匹配；重新运行 discover_debug_apps 获取准确的 URI。
• connection_failed — VM 拒绝了连接；确认应用仍在调试模式下运行。