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.

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
snapshot create	Capture and save a named snapshot	fmtk snapshot create --name baseline --args '{}'
snapshot diff	Diff two snapshots	fmtk snapshot diff --from baseline --to current
bundle create	Package a snapshot into a publishable bundle	fmtk bundle create --from-snapshot baseline --output ./out
doctor	Run preflight checks (VM + toolkit + registry)	fmtk doctor --json
permissions status	Check a permission (e.g. visual_capture)	fmtk permissions status --kind visual_capture
permissions request	Request a permission	fmtk permissions request --kind visual_capture
permissions open-settings	Open OS settings for a permission	fmtk permissions open-settings --kind visual_capture
validate-runtime	End-to-end VM + toolkit + capture smoke test	fmtk validate-runtime --target ws://127.0.0.1:8181/<token>/ws
init <agent>	Install skills + MCP server config for an AI agent	flutter-mcp-toolkit init claude-code
codegen-init	Add toolkit dependency and emit main.dart boilerplate	flutter-mcp-toolkit codegen-init

Global flags (before the subcommand): --dart-vm-port <n>, --dart-vm-host <host>, --vm-service-uri <ws_uri>, --log-level <level>, --dumps, -h/--help.

VM targeting: Global --vm-service-uri applies to doctor and validate-runtime when subcommand --target is omitted. If both are set and differ, --target wins (stderr warning).

validate-runtime screenshots: the first capture uses auto (often desktop_window on macOS). If that step fails with a retryable get_screenshots_failed, the CLI retries once with flutter_layer. On success, data.summary.captureFallbackUsed is true in the JSON envelope.

Debug/eval batteries: keep repeated checks as scripts or batch calls over existing primitives first: --log-level debug, --output-dir, --save-images, doctor --json, validate-runtime, batch, and exec --name diagnose. Do not expose a generic MCP run_tool; MCP remains the typed fmt_* tool surface. If a flow becomes reusable across projects as a scenario, graduate it to checked-in Dart in this repo's showcase/ or packages/harness instead of adding a toolkit-only scenario language.

---

init <agent>

Install the flutter-mcp-toolkit skills + MCP server config for an AI agent.

Targets: claude-code | cursor | codex | cline | agents-skills | all.

flutter-mcp-toolkit init claude-code        # install for Claude Code (project-scoped)
flutter-mcp-toolkit init cursor --scope user # install user-globally for Cursor
flutter-mcp-toolkit init all --mode cli      # install for every detected agent in CLI mode

Mode auto-detects (MCP if registered, else CLI). Override with --mode mcp|cli|auto.

Alternative (skills only, open ecosystem): npx skills add Arenukvern/mcp_flutter -a cursor -y installs the same SKILL.md bundles via skills.sh; it does not write mcp.json — run init afterward or configure mcpServers manually. See AI agent overview.

---

codegen-init

From a Flutter project root, add mcp_toolkit as a dependency and emit the boilerplate snippet for lib/main.dart.

cd my-flutter-app
flutter-mcp-toolkit codegen-init             # runs `flutter pub add` + prints snippet
flutter-mcp-toolkit codegen-init --no-pub-add  # snippet only, skip pub add

---

Reinstall / upgrade

The install script is idempotent — re-running it replaces the binary in place:

curl -fsSL https://raw.githubusercontent.com/Arenukvern/mcp_flutter/main/install.sh | bash

After reinstall, verify with flutter-mcp-toolkit --help and fmtk --help.