flutter-mcp-toolkit-setup

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.