flutter-mcp-toolkit-debug
- Repo stars 0
- Author updated Live
- Author repo skills-registry
- Domain
- AI
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- macOS
- Runtime requirements
- No special requirements
- Permissions
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: flutter-mcp-toolkit-debug
description: Diagnose problems in a running Flutter app — read logs, evaluate Dart expressions, interpret err…
category: ai
runtime: no special runtime
---
# flutter-mcp-toolkit-debug output preview
## PART A: Task fit
- Use case: Diagnose problems in a running Flutter app — read logs, evaluate Dart expressions, interpret error envelopes. Use when something broke. Use when this capability is needed..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “When to use / Triage flow / Tool reference” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “Diagnose problems in a running Flutter app — read logs, evaluate Dart expressions, interpret error envelopes. Use when something broke. Use when this capability is needed.”.
- **02** When the source has headings, the agent prioritizes “When to use / Triage flow / Tool reference” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source does not require a stable slash command. After installation, invoke the skill by name and describe the task.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, run shell commands.
Start with a small task and check whether the result follows “When to use / Triage flow / Tool reference”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: flutter-mcp-toolkit-debug
description: Diagnose problems in a running Flutter app — read logs, evaluate Dart expressions, interpret err…
category: ai
source: tomevault-io/skills-registry
---
# flutter-mcp-toolkit-debug
## When to use
- Diagnose problems in a running Flutter app — read logs, evaluate Dart expressions, interpret error envelopes. Use when…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “When to use / Triage flow / Tool reference” and keep inference separate from source facts.
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "flutter-mcp-toolkit-debug" {
input -> user goal + target files + boundaries + acceptance criteria
context -> When to use / Triage flow / Tool reference
rules -> SKILL.md triggers / order / output contract
runtime -> no special runtime | read files, write/modify files, run shell commands | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} When to use
Use this skill when something broke and you need to understand why:
- A tool call returned an error envelope (
ok: false). - The app behaves unexpectedly and you need runtime log output.
- You need to inspect live app state without changing it (read
AgentState.instance.value). - A prior
controlaction (tap, hot_reload, navigate) completed without error but the result is wrong.
Do NOT use this skill for:
- Reading what is currently on screen — use
flutter-mcp-toolkit-inspect. - The toolkit itself failing to connect — load
flutter-mcp-toolkit-setup.
Triage flow
- Error envelope returned? Read
error.codefirst, thenerror.descriptor.retryable. Look the code up in the Error envelope playbook below. - Retryable error? Run
flutter-mcp-toolkit doctor --json. If doctor fails, loadflutter-mcp-toolkit-setup. - Need log output? Call
get_recent_logswithcount: 100and a level filter. Look for stack traces or assertion messages near the timestamp of the failure. - Need live state? Call
evaluate_dart_expressionwith a targeted expression (e.g.MyBloc.instance.state.toString()). Do this after logs, not instead of them. - Chaining with inspect? Order:
semantic_snapshot→evaluate_dart_expression→get_recent_logs. Snapshot gives you the current widget tree before expression evaluation mutates nothing; logs give trailing context. - Multiple targets? If
connection_selection_required, calldiscover_debug_apps, pick thetargetId, then passconnection: {targetId: "..."}to every subsequent call.
Tool reference
get_recent_logs
Retrieve recent print() and debugPrint() output from the running app's main isolate.
count• integer • optional, default: 50 — number of log lines to return.connection• object • optional — connection override; required when multiple debug apps are running.
get_recent_logs(count: 100)
get_recent_logs(count: 50, connection: {targetId: "ws://127.0.0.1:8181/<token>/ws"})
Returns: {"logs": ["[INFO] page loaded", "[ERROR] assertion failed: ..."], "count": 50}
Read-only; no code executed. Returns only lines buffered since last app start or hot restart. On failure see getRecentLogsFailed in the playbook.
evaluate_dart_expression
Evaluate a Dart expression in the running app's main isolate and return its string representation.
expression• string • required — Dart expression (e.g."MyClass.instance.counter").connection• object • optional — connection override.
evaluate_dart_expression(expression: "Navigator.of(context).canPop()")
evaluate_dart_expression(expression: "AgentState.instance.value.toString()")
Returns: {"result": "42"} — always a string-serialized value. Executes arbitrary code in the live isolate — avoid side-effecting expressions. Debug mode only. On failure see evaluateExpressionFailed in the playbook.
Connect / multi-app flows
When discover_debug_apps returns more than one entry (or any call returns connection_selection_required):
- Call
discover_debug_apps()— readtargets[*].targetIdfor each running app. - Identify the target by port or hostname.
- Call
connect_debug_app(connection: {targetId: "ws://127.0.0.1:<port>/<token>/ws"})to pin the session. - Pass the same
connectionobject to every subsequent tool call for the session.
Connection override pattern — pass connection on any call:
get_recent_logs(count: 50, connection: {targetId: "ws://127.0.0.1:8182/<token>/ws"})
evaluate_dart_expression(expression: "x.toString()", connection: {targetId: "ws://127.0.0.1:8182/<token>/ws"})
If the target changes (app restarted, port shifted), re-run discover_debug_apps to get the new targetId. Stale URIs return connect_failed.
Error envelope playbook
Every failure returns {code, message, details, descriptor, recovery}. Always read error.descriptor (not the top-level envelope) for retryable and exitCode. Run error.recovery.fix_command directly when provided.
unexpectedExecutorError (unexpected_executor_error)
Means: unhandled exception in the command executor. Causes: bug in the server; unexpected nil; unrecoverable VM state. Recovery:
flutter-mcp-toolkit doctor --json- If doctor passes, retry once; if it recurs, file a bug with
error.details.
connectFailed (connect_failed)
Means: connection to the VM Service WebSocket failed. Causes: wrong port, stale token, app not running. Recovery:
flutter-mcp-toolkit exec --name get_vm --args '{"connection":{"uri":"ws://127.0.0.1:8181/<token>/ws"}}'- Get the exact URI from
app.debugPort.wsUriin Flutter output.
vmNotConnected (vm_not_connected)
Means: a VM-dependent command was called before a connection was established. Recovery:
flutter-mcp-toolkit exec --name status --args '{}'- Then
flutter-mcp-toolkit doctor --json.
connectionSelectionRequired (connection_selection_required)
Means: multiple debug targets exist; an explicit target is required. Causes: more than one Flutter app running in debug mode simultaneously. Recovery:
flutter-mcp-toolkit exec --name discover_debug_apps --args '{}'- Pick the correct
targetIdfromdetails.availableTargets. - Retry the original call with
connection: {targetId: "<chosen_id>"}.
discoverDebugAppsFailed (discover_debug_apps_failed)
Means: discovery scan of local VM Service ports failed.
Recovery: flutter-mcp-toolkit doctor --json
getVmFailed (get_vm_failed)
Means: get_vm RPC to the VM Service failed.
Recovery: flutter-mcp-toolkit doctor --json
getExtensionRpcsFailed (get_extension_rpcs_failed)
Means: listing registered extension RPCs failed.
Recovery: flutter-mcp-toolkit doctor --json
hotReloadFailed (hot_reload_failed)
Means: hot reload was rejected by the Dart compiler or VM. Causes: compile error in changed files; isolate in bad state. Recovery:
flutter-mcp-toolkit exec --name get_app_errors --args '{}'- Fix the compile error, then retry.
hotRestartFailed (hot_restart_failed)
Means: full hot restart failed.
Recovery: flutter-mcp-toolkit doctor --json — if VM is unreachable, restart the app manually.
getActivePortsFailed (get_active_ports_failed)
Means: scan for active debug ports failed.
Recovery: flutter-mcp-toolkit doctor --json
getAppErrorsFailed (get_app_errors_failed)
Means: retrieving app errors from the toolkit bridge failed.
Recovery: flutter-mcp-toolkit doctor --json
getScreenshotsFailed (get_screenshots_failed)
Means: screenshot capture failed (wrong mode, host window not available, Simulator window race, etc.). Recovery:
flutter-mcp-toolkit doctor --json— checkvisual_capture_permission_deniedseparately.- For MCP /
exec, retryget_screenshotsorcapture_ui_snapshotwithscreenshotMode: flutter_layerwhendesktop_windowor host capture is flaky (macOS unfocused window, iOS Simulator). - For
validate-runtime, aflutter_layerretry runs automatically after a failed hostdesktop_windowattempt; readdata.summary.captureFallbackUsedin the result envelope.
visualCapturePermissionDenied (visual_capture_permission_denied)
Means: macOS Screen Recording permission is not granted. Recovery:
flutter-mcp-toolkit permissions request --kind visual_capture- Or open System Settings → Privacy & Security → Screen Recording.
visualCaptureUnsupported (visual_capture_unsupported)
Means: visual capture is not supported on this platform or capture mode. Not retryable.
Recovery: flutter-mcp-toolkit permissions status && flutter-mcp-toolkit doctor --json
getViewDetailsFailed (get_view_details_failed)
Means: retrieving FlutterView dimensions failed.
Recovery: flutter-mcp-toolkit doctor --json
debugDumpFailed (debug_dump_failed)
Means: a VM debug-dump RPC (render tree, semantics, layers) failed.
Recovery: flutter-mcp-toolkit doctor --json
dynamicRegistryDisabled (dynamic_registry_disabled)
Means: a dynamic tool/resource call was made but the dynamic registry is disabled. Not retryable.
Recovery: flutter-mcp-toolkit --dynamics exec --name status --args '{}' — pass --dynamics flag to enable.
dynamicRegistryListFailed (dynamic_registry_list_failed)
Means: listing dynamic tools/resources from the registry failed.
Recovery: flutter-mcp-toolkit doctor --json
missingToolName (missing_tool_name)
Means: a dynamic tool call was made without providing a tool name. Not retryable.
Recovery: include tool_name parameter in the call; flutter-mcp-toolkit schema --name fmt_client_tool.
dynamicToolFailed (dynamic_tool_failed)
Means: invocation of a dynamic tool failed.
Recovery: flutter-mcp-toolkit doctor --json
missingResourceUri (missing_resource_uri)
Means: a dynamic resource read was called without a URI. Not retryable.
Recovery: include uri parameter; flutter-mcp-toolkit schema --name fmt_client_resource.
dynamicResourceFailed (dynamic_resource_failed)
Means: reading a dynamic resource failed.
Recovery: flutter-mcp-toolkit doctor --json
sessionManagerNotConfigured (session_manager_not_configured)
Means: a session command was called but no session manager is wired. Not retryable.
Recovery: flutter-mcp-toolkit doctor --json — server config issue; reload flutter-mcp-toolkit-setup.
sessionNotFound (session_not_found)
Means: the requested session ID does not exist. Not retryable. Recovery: list active sessions; start a new session before referencing it.
invalidCommand (invalid_command)
Means: command name or argument schema is invalid. Not retryable.
Recovery: flutter-mcp-toolkit schema --name <command_name>
stateStoreReadFailed (state_store_read_failed)
Means: reading from persistent state store failed.
Recovery: flutter-mcp-toolkit doctor --json — check filesystem permissions on state directory.
stateStoreWriteFailed (state_store_write_failed)
Means: writing to persistent state store failed.
Recovery: flutter-mcp-toolkit doctor --json — check disk space and permissions.
stateLockTimeout (state_lock_timeout)
Means: acquiring the state lock timed out (concurrent agent contention). Causes: another agent or CLI call holds the lock; deadlock. Recovery: wait and retry; if recurring, kill other agent processes holding the lock.
stateLockConflict (state_lock_conflict)
Means: a conflicting state lock was detected. Causes: parallel agents writing simultaneously. Recovery: serialise calls; retry after the conflicting operation completes.
diagnoseFailed (diagnose_failed)
Means: the composite diagnose command failed.
Recovery: flutter-mcp-toolkit doctor --json
explainErrorsFailed (explain_errors_failed)
Means: the error-explanation command failed.
Recovery: flutter-mcp-toolkit doctor --json
unsupportedSummaryProvider (unsupported_summary_provider)
Means: an unrecognised summary provider was requested. Not retryable.
Recovery: flutter-mcp-toolkit schema --name diagnose — check allowed provider values.
snapshotNotFound (snapshot_not_found)
Means: the referenced snapshot ID does not exist. Not retryable.
Recovery: flutter-mcp-toolkit snapshot create --name <snapshot_id> --args '{}'
snapshotInvalid (snapshot_invalid)
Means: snapshot payload is malformed or fails validation. Not retryable. Recovery: recreate the snapshot; do not reuse corrupted files.
staleSnapshot (stale_snapshot)
Means: the provided snapshotId no longer matches the current app state.
Causes: a hot reload or interaction changed the widget tree after the snapshot was taken.
Recovery:
evaluate_dart_expression(expression: "true")— verify app is reachable.semantic_snapshot()— obtain a fresh snapshot ID, then retry the original call.
bundleBuildFailed (bundle_build_failed)
Means: bundle creation or publish failed.
Recovery: flutter-mcp-toolkit doctor --json — check build artefacts and output path.
writeBlocked (write_blocked)
Means: a write was blocked because --no-overwrite is set and the target already exists. Not retryable.
Recovery: retry without --no-overwrite, or choose a different --output/--name.
doctorCriticalFailed (doctor_critical_failed)
Means: one or more critical doctor checks failed.
Recovery: flutter-mcp-toolkit doctor --json — read checks[*] where status: "fail" and critical: true; load flutter-mcp-toolkit-setup.
interactionFailed (interaction_failed)
Means: a tap/scroll/swipe/drag/long_press/enter_text call failed.
Causes: stale ref; widget not visible or not interactive; toolkit bridge not initialized.
Recovery:
semantic_snapshot()— get fresh refs.- Retry with the new ref.
semanticSnapshotFailed (semantic_snapshot_failed)
Means: semantic_snapshot execution failed.
Recovery: flutter-mcp-toolkit doctor --json — verify MCPToolkitBinding.initialize() is called.
evaluateExpressionFailed (evaluate_expression_failed)
Means: evaluate_dart_expression execution failed.
Causes: expression syntax error; exception thrown at runtime; isolate not reachable.
Recovery: simplify the expression; check syntax; flutter-mcp-toolkit doctor --json.
getRecentLogsFailed (get_recent_logs_failed)
Means: get_recent_logs retrieval failed.
Recovery: flutter-mcp-toolkit doctor --json — verify toolkit is initialized.
waitTimeout (wait_timeout)
Means: wait_for predicate did not match before timeoutMs elapsed.
Causes: predicate condition never becomes true; app state does not change; timeoutMs too short.
Recovery:
semantic_snapshot()— verify the expected widget state.- Increase
timeoutMsor adjust the predicate.
waitForFailed (wait_for_failed)
Means: wait_for execution failed (malformed predicate or toolkit error).
Recovery: flutter-mcp-toolkit schema --name wait_for
pressKeyFailed (press_key_failed)
Means: press_key execution failed.
Recovery: flutter-mcp-toolkit schema --name press_key
handleDialogFailed (handle_dialog_failed)
Means: handle_dialog (dismiss/accept dialog) execution failed.
Causes: no dialog present; dialog already dismissed.
Recovery: semantic_snapshot() — verify a dialog is visible before calling.
navigateFailed (navigate_failed)
Means: navigate push/pop/popUntil failed.
Recovery: flutter-mcp-toolkit schema --name navigate
navigatorNotRegistered (navigator_not_registered)
Means: navigate was called but the app did not register a GlobalKey<NavigatorState>. Not retryable.
Causes: MCPToolkitBinding.instance.navigatorKey was never set in the host app.
Recovery: assign MCPToolkitBinding.instance.navigatorKey = navigatorKey in the app's main.dart and hot restart.
fillFormFailed (fill_form_failed)
Means: fill_form orchestration failed (transport or per-field error).
Recovery: flutter-mcp-toolkit schema --name fill_form
hoverFailed (hover_failed)
Means: hover execution failed.
Recovery: flutter-mcp-toolkit doctor --json
unknown (unknown_error)
Means: fallback for any unrecognised error code.
Recovery: flutter-mcp-toolkit doctor --json — inspect error.details for raw cause.
Source: Arenukvern/mcp_flutter — distributed by TomeVault.
Decide Fit First
Design Intent
How To Use It
Boundaries And Review