flutter-mcp-cli-runtime-validation
Run Flutter MCP runtime validation from CLI in two steps (launch app, then run validate-runtime), including toolkit-extension gating, screenshot/layout capture, app error collection, optional reload verification, and retry handling for transient first-connect failures.
How do I install this agent skill?
npx skills add https://github.com/arenukvern/mcp_flutter --skill flutter-mcp-cli-runtime-validationIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides instructions for a Flutter development tool. It is functionally safe for development tasks but contains a vulnerability surface for indirect prompt injection as it processes data from external applications without explicit sanitization.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Flutter MCP CLI Runtime Validation
Use this skill when you need agent-style runtime validation through flutter-mcp-toolkit with minimal operator steps.
Two-Step Flow
- Launch the Flutter app in debug mode.
- Run one CLI command:
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart --save-images --output-dir .flutter_mcp/runtime_validation validate-runtime \
--target ws://127.0.0.1:8181/<token>/ws \
--timeout-ms 10000 \
--post-reload-delay-ms 500 \
--after-reload
Optional skill install in the same command:
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart validate-runtime \
--target ws://127.0.0.1:8181/<token>/ws \
--install-skill
Permission behavior for this flow:
validate-runtimestays read/write only for visual capture and defaults toauto_request_once.doctorremains read-only.- On macOS, Screen Recording permission belongs to the host process running
flutter-mcp-toolkit. - On web:
desktop_windowuses macOS ScreenCaptureKit then Chrome CDP (Page.captureScreenshot); Linux/Windows use CDP when remote debugging is reachable. Pass--web-browser-debugging-portif discovery fails. For web targets, pass--flutter-device chromeso validation does not pick macOS hostdesktop_windowby mistake. - Executor recovery retries host capture once (
desktopCaptureRetriedin screenshot payloads). Ifdesktop_windowstill fails (including when platform views are detected),validate-runtimeretries once withflutter_layer. Checkdata.summary.captureFallbackUsed. - You may pass the VM URI as global
--vm-service-uriinstead ofvalidate-runtime --targetwhen only one URI is needed.
What validate-runtime Must Prove
- Doctor preflight passes critical checks.
- Required toolkit extensions exist:
ext.mcp.toolkit.app_errorsext.mcp.toolkit.view_detailsext.mcp.toolkit.view_screenshotsext.mcp.toolkit.inspect_widget_at_point
- Screenshot capture works.
- View details (layout metadata) are available.
- App errors are retrievable.
- If
--after-reloadis enabled, post-reload screenshot also works.
Output Handling
- Use
data.summaryas pass/fail status for automation. - Use
data.summary.capturePlatformViewsDetectedandcaptureFocusAttemptedfor platform-view routing. - Use
data.summary.captureFallbackUsedto see whether aflutter_layerretry ran after a faileddesktop_windowattempt (including when platform views are detected). - Use
data.stepsfor per-step evidence and retries. - Use
data.doctor.checksto explain setup blockers. - Use
data.summary.screenshotFilesfor saved screenshot paths when--save-imagesis enabled. - When
--save-imagesis enabled, read screenshot file URLs from step data. - For visual debugging reports, also run:
exec --name capture_ui_snapshot --args '{"errorsCount":4,"compress":true,"includeViewDetails":true,"includeErrors":true}'exec --name inspect_widget_at_point --args '{"x":<int>,"y":<int>}'
Failure Rules
- If toolkit extensions are missing, stop and report instrumentation gap with exact fix:
- add
mcp_toolkitto app dependencies - ensure
MCPToolkitBinding.instance.bootstrapFlutter(...)or equivalent manual initialization runs beforerunApp - hot restart or rerun the app
- add
- If first explicit URI connect fails, retry is automatic for retryable connection errors.
- If screenshots are blank, verify app window is visible and retry.
- If macOS visual capture is denied, use:
dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart permissions statusdart run mcp_server_dart/bin/flutter_mcp_toolkit.dart permissions requestdart run mcp_server_dart/bin/flutter_mcp_toolkit.dart permissions open-settings
- If app cannot be instrumented, do not claim screenshot/layout/error inspection success.
Visual QA + Source Mapping Rules
- Always compare before/after screenshot evidence around changes.
- For each reported visual issue, provide coordinate +
inspect_widget_at_pointoutput. - Map defects to source using
get_app_errorstop stack frame (file,line,column) when available. - Do not use
debug_dump_*unless explicitly requested.
Challenge Cases (Always Call Out Explicitly)
- No running debug app:
doctorcritical failure onvm_target_reachable; request app launch before continuing. - Wrong target URI/token: treat as connection mismatch and retry with exact
app.debugPort.wsUri. - Toolkit added but still missing extensions: hot reload is often insufficient, require hot restart/full rerun.
- Non-modifiable app (cannot add toolkit): report inspection as unavailable instead of guessing.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/arenukvern/mcp_flutter/flutter-mcp-cli-runtime-validation">View flutter-mcp-cli-runtime-validation on skillZs</a>