Built-in Tools

The Flutter MCP Toolkit comes with a set of pre-built tools and resources for common development tasks.

Notes:

• VM-dependent tools/resources resolve connection on demand. Startup does not force choosing a VM target.
• If VM service is unavailable, the tool returns an error payload.
• If multiple debug targets are discovered and no sticky/explicit target is available, the tool returns connection_selection_required.
• Error envelope and code semantics are defined in Error Code Playbook.

Core Tools

• connect_debug_app: Explicitly select/connect a debug target.
• discover_debug_apps: List active debug targets with canonical websocket URIs.
• hot_reload_flutter: Performs a hot reload of the Flutter app.
• hot_restart_flutter: Performs a hot restart of the Flutter app.
• get_vm: Returns information about the Dart VM.
• get_extension_rpcs: Lists the available extension RPCs in the Flutter app.
• capture_ui_snapshot: Captures screenshots + view details + app errors in one bundle.
• inspect_widget_at_point: Resolves global (x,y) to the deepest widget/render node.

get_active_ports remains available in CLI for low-level workflows, but discover_debug_apps is the preferred API for agent-driven target selection.

CLI Parity Quick Check

CLI and MCP use the same shared command catalog/executor. You can verify quickly:

dart run mcp_server_dart/bin/flutter_mcp_cli.dart schema --name discover_debug_apps
dart run mcp_server_dart/bin/flutter_mcp_cli.dart schema --name capture_ui_snapshot
dart run mcp_server_dart/bin/flutter_mcp_cli.dart schema --name inspect_widget_at_point
dart run mcp_server_dart/bin/flutter_mcp_cli.dart exec --name discover_debug_apps --args '{}'

Connection Targeting (Per Request)

All VM-dependent tools accept an optional nested connection object in arguments:

{
  "name": "get_vm",
  "arguments": {
    "connection": {
      "targetId": "ws://127.0.0.1:59490/<token>/ws"
    }
  }
}

Supported fields:

• targetId (full VM websocket URI)
• mode (auto, manual, uri)
• host
• port
• uri
• forceReconnect

Legacy host:port values for targetId are rejected.

Zero-mistake targeting:

1. Safest: use connection.uri with exact app.debugPort.wsUri.
2. If using connection.targetId, copy from discover_debug_apps or availableTargets.
3. If target_not_found occurs, retry with connection.uri and exact machine wsUri.

Flat top-level aliases like arguments.port, arguments.host, and arguments.uri are not supported.

The same nested object is used in CLI/daemon flows:

• one-shot exec --args
• daemon command/execute and watch/start
• snapshot step args (commands[i].args.connection)

Ambiguity Handshake

When multiple targets exist and no sticky/explicit target resolves ambiguity, the server returns:

{
  "code": "connection_selection_required",
  "details": {
    "reason": "multiple_targets",
    "availableTargets": [
      {
        "targetId": "ws://127.0.0.1:8181/<token>/ws",
        "host": "localhost",
        "port": 8181,
        "endpoint": "ws://127.0.0.1:8181/<token>/ws",
        "isSticky": false,
        "isCurrent": false
      }
    ],
    "suggestedAction": "retry_with_connection_target",
    "example": {
      "connection": {"targetId": "ws://127.0.0.1:8181/<token>/ws"}
    },
    "howToRetry": {
      "connection": {"targetId": "ws://127.0.0.1:8181/<token>/ws"}
    }
  }
}

Hot Restart Tool Usage

The server now provides a dedicated hot restart tool for situations where hot reload isn't sufficient (for example after adding service extensions or when the app state is corrupted):

{
  "name": "hot_restart_flutter",
  "arguments": {}
}

Expected result:

{
  "message": "{\"report\":{\"type\":\"Success\",\"success\":true}}"
}

Debug Dump Tools

These tools are disabled by default and can be enabled with the --dumps flag.

• debug_dump_layer_tree: Dumps the layer tree.
• debug_dump_semantics_tree: Dumps the semantics tree.
• debug_dump_render_tree: Dumps the render tree.
• debug_dump_focus_tree: Dumps the focus tree.

Resources

• visual://localhost/app/errors/latest: Gets the latest errors from the app.
• visual://localhost/view/details: Gets details about the current view.
• visual://localhost/view/screenshots: Takes a screenshot of the app.

Resource reads also support connection targeting via URI query params:

• targetId
• mode
• host
• port
• uri
• forceReconnect

Example:

• visual://localhost/view/details?targetId=ws%3A%2F%2F127.0.0.1%3A59490%2F%3Ctoken%3E%2Fws