/flutter-mcp-toolkit-setup

name: flutter-mcp-toolkit-setup
description: Verify the flutter-mcp-toolkit install, run doctor preflight, troubleshoot connection issues. Use when the toolkit isn't responding or first-time setup.

<!-- @FMT_MODE_PRELUDE -->

When to use

Use this skill when:

• First-time install: `flutter-mcp-toolkit` or its short alias `fmtk` is not yet on PATH.
• `doctor --json` returns any check with `"status": "fail"`.
• MCP server fails to connect or tools return `vm_not_connected` / `connect_failed`.
• Visual capture or toolkit-bridge commands are returning unexpected errors.

---

Verify install

flutter-mcp-toolkit --help
fmtk --help

Expected output: command help from both names. `flutter-mcp-toolkit` is the canonical long name; `fmtk` is the compact alias for day-to-day terminal loops.

If you get `command not found`, the binary is not on PATH:

# Binary is built to mcp_server_dart/build/ inside the repo
export PATH="$PATH:/path/to/mcp_flutter/mcp_server_dart/build"
# Or rebuild from source
cd /path/to/mcp_flutter && make build

Then verify with `flutter-mcp-toolkit --help` and `fmtk --help`.

---

Run doctor

Always run doctor before any VM-dependent command:

fmtk doctor --json

Flags: `--target <ws_uri>` (test a specific URI), global `--vm-service-uri <ws_uri>` (same as `--target` when omitted on `doctor`), `--timeout-ms <n>` (default: 2500).

# Global URI works for doctor (same as validate-runtime)
fmtk --vm-service-uri 'ws://127.0.0.1:8181/<token>/ws' doctor --json

Sample green output:

{
  "summary": { "criticalFailures": 0 },
  "checks": [
    { "id": "vm_target_reachable", "status": "pass", "critical": true },
    { "id": "mcp_toolkit_extensions", "status": "pass", "critical": true },
    { "id": "dynamic_registry_available", "status": "pass", "critical": false }
  ]
}

**Triage:** `criticalFailures > 0` means VM/setup is blocked — not that every tool is broken. `dynamic_registry_available: pass` with `vm_target_reachable: fail` usually means a stale URI after hot restart; run `discover_debug_apps` and pass the new `targetId`.

Read `error.descriptor` (not top-level) for retry policy and exit codes. Each check includes `fix_command` — run it directly.

---

Recover by error code

`binary_not_found`

Binary missing or not on PATH. Rebuild and add to PATH:

cd /path/to/mcp_flutter && make build
export PATH="$PATH:/path/to/mcp_flutter/mcp_server_dart/build"

`vm_not_connected`

Flutter app not running, stale token after restart, or URI not resolved:

fmtk exec --name discover_debug_apps --args '{}'
fmtk exec --name status --args '{}'
fmtk doctor --json --target ws://127.0.0.1:8181/<new-token>/ws

After a successful auto re-attach, `meta.recovery.reattachedTo` shows the new endpoint.

`connect_failed`

Wrong port, app not started, or stale token. Pass explicit URI from `app.debugPort.wsUri`:

fmtk exec --name get_vm --args '{"connection":{"uri":"ws://127.0.0.1:8181/<token>/ws"}}'

`connection_selection_required`

Multiple debug targets detected. List with `discover_debug_apps`, then pass the chosen URI from `details.availableTargets` explicitly to `get_vm`.

`hot_reload_failed`

Dart compilation error or VM disconnected. Check errors, fix, then retry:

fmtk exec --name get_app_errors --args '{}'

`visual_capture_unsupported`

macOS screen recording permission not granted or unsupported platform:

fmtk permissions request --kind visual_capture

---

Connection issues (deeper troubleshooting)

**Port conflicts**: VM service defaults to 8181. Override if another process holds it:

flutter run --debug --host-vmservice-port=8182 -d macos
fmtk --dart-vm-port 8182 doctor --json

Use `flutter run --machine` and copy `app.debugPort.wsUri` when you need the exact websocket URI (recommended for `validate-runtime` and `exec`).

**Flutter app not in debug mode**: Release/profile builds don't expose the VM service. Always use `flutter run --debug`.

**`mcp_toolkit` not initialized**: Doctor's `mcp_toolkit_extensions` check will fail. Add before `runApp` — use `flutter-mcp-toolkit codegen-init` to generate the boilerplate (see CLI surface below). After adding, hot restart (not hot reload — binding init requires a full restart).

**Multiple apps / wrong target**: Pass `--target` with the exact websocket URI:

fmtk doctor --json --target ws://127.0.0.1:8181/<token>/ws

---

CLI surface

The canonical binary is `flutter-mcp-toolkit` (built to `mcp_server_dart/build/`). Packaged installs also include `fmtk`, a short alias to the same entrypoint. Use `fmtk` in quick loops; keep the long name in install, onboarding, PATH, and MCP configuration docs.

| Subcommand | Purpose | Minimal example | | --------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------ | | `exec` | Run a single named command against the VM | `fmtk exec --name get_vm --args '{}'` | | `batch` | Run multiple commands in one call | `fmtk batch --steps '[{"name":"get_vm"},{"name":"status"}]'` | | `schema` | Print the JSON schema for a named command | `fmtk schema --name hot_reload_flutter` | | `capabilities` | List all registered capabilities | `fmtk capabilities` | | `serve` | Start the MCP server (stdio transport) | `fmtk serve`