flutter mcp cli runtime validation
- Repo stars 0
- Author repo skills-registry
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- 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 explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
<!-- @FMT_MODE_PRELUDE -->
# 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
1. Launch the Flutter app in debug mode.
2. Run one CLI command:
```bash
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:
```bash
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-runtime` stays read/write only for visual capture and defaults to `auto_request_once`.
- `doctor` remains read-only.
- On macOS, Screen Recording permission belongs to the host process running `flutter-mcp-toolkit`.
- On web, `flutter_layer` is the only supported truth path and no OS permission prompt is expected.
- If the first `capture_ui_snapshot` attempt uses host `desktop_window` and fails (common on macOS when the window is not foregrounded, or for iOS Simulator), `validate-runtime` automatically retries once with `flutter_layer`.
- You may pass the VM URI as global `--vm-service-uri` instead of `validate-runtime --target` when only one URI is needed.
## What `validate-runtime` Must Prove
- Doctor preflight passes critical checks.
- Required toolkit extensions exist:
- `ext.mcp.toolkit.app_errors`
- `ext.mcp.toolkit.view_details`
- `ext.mcp.toolkit.view_screenshots`
- `ext.mcp.toolkit.inspect_widget_at_point`
- Screenshot capture works.
- View details (layout metadata) are available.
- App errors are retrievable.
- If `--after-reload` is enabled, post-reload screenshot also works.
## Output Handling
- Use `data.summary` as pass/fail status for automation.
- Use `data.summary.captureFallbackUsed` to see whether the `flutter_layer` retry succeeded after a failed `desktop_window` attempt.
- Use `data.steps` for per-step evidence and retries.
- Use `data.doctor.checks` to explain setup blockers.
- Use `data.summary.screenshotFiles` for saved screenshot paths when `--save-images` is enabled.
- When `--save-images` is 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_toolkit` to app dependencies
- ensure `MCPToolkitBinding.instance.bootstrapFlutter(...)` or equivalent manual initialization runs before `runApp`
- hot restart or rerun the app
- 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 status`
- `dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart permissions request`
- `dart 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_point` output.
- Map defects to source using `get_app_errors` top 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: `doctor` critical failure on `vm_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.
---
> Source: [Arenukvern/mcp_flutter](https://github.com/Arenukvern/mcp_flutter) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
Sections and files
Listed in source order.
sections -> Two-Step Flow → What validate-runtime Must Prove → Output Handling → Failure Rules → Visual QA + Source Mapping Rules → Challenge Cases (Always Call Out Explicitly)
terms -> Use this skill when you need agent-style runtime validation through flutter-mcp-toolkit with minimal operator steps. · 1. Launch the Flutter app in debug mode. · - validate-runtime stays read/write only for visual capture and defaults to autorequestonce. · - Doctor preflight passes critical checks. · - Use data.summary as pass/fail status for automation. · - Always compare before/after screenshot evidence around changes. · - No running debug app: doctor critical failure on vmtargetreachable; request app launch before continuing. · --- > Source: [Arenukvern/mcpflutter](https://github.com/Arenukvern/mcpflutter) — distributed by [TomeVault](https://tomevault.io).
files/cmd -> flutter-mcp-toolkit · validate-runtime · auto_request_once · doctor · flutter_layer · capture_ui_snapshot · desktop_window · --vm-service-uri
body sha256 -> 0ae8ff54917a
Two-Step Flow
Launch the Flutter app in debug mode. Run one CLI command: Optional skill install in the same command: Permission behavior for this flow:
validate-runtimestays read/write only for visual capture and defaults toauto_request_once.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_screenshotsOutput Handling
Use
data.summaryas pass/fail status for automation. Usedata.summary.captureFallbackUsedto see whether theflutter_layerretry succeeded after a faileddesktop_windowattempt. Usedata.stepsfor per-step evidence and retries. Usedata.doctor.checksto explain setup blockers. Usedata.summary.screenshotFilesfor saved screenshot paths when--save-imagesis enabled.Failure Rules
If toolkit extensions are missing, stop and report instrumentation gap with exact fix: add
mcp_toolkitto app dependencies ensureMCPToolkitBinding.instance.bootstrapFlutter(...)or equivalent manual initialization runs beforerunApphot restart or rerun the app If first explicit URI connect fails, retry is automatic for retryable connection errors.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 usingget_app_errorstop stack frame (file,line,column) when available. Do not usedebug_dump_*unless explicitly requested.