颤振
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
<!-- @FMT_MODE_PRELUDE -->
# Flutter MCP
Golden path for agents driving a live Flutter app via the **`flutter-mcp-toolkit`** MCP server entry. Older configs may use the legacy **`flutter-inspector`** `mcpServers` registry id for the same binary (that id is **not** the Claude subagent **`flutter-mcp-toolkit-runtime`**).
## When to use
- User references a running Flutter app (debug mode) and wants to inspect, screenshot, interact with, or hot-reload it.
- User pastes a VM service URI (`ws://127.0.0.1:8181/.../ws`) or mentions port 8181.
- You need runtime proof (before/after screenshots) that a code edit took effect.
## Preflight (always first)
Before any VM-dependent call:
1. Call `doctor` (or run `flutter-mcp-toolkit doctor --json`) — parses env, ports, app reachability.
2. Confirm required toolkit extensions exist on the target:
- `ext.mcp.toolkit.app_errors`
- `ext.mcp.toolkit.view_details`
- `ext.mcp.toolkit.view_screenshots`
- `ext.mcp.toolkit.inspect_widget_at_point`
If missing, stop and report the instrumentation gap — do **not** guess:
- Add `mcp_toolkit` to `pubspec.yaml`.
- Ensure `MCPToolkitBinding.instance..initialize()..initializeFlutterToolkit();` runs before `runApp`.
- Hot **restart** (not reload) — reload is often insufficient for extension registration.
## Tool naming (v3.0.0+)
All MCP tools surface under the `fmt_` capability prefix
(`fmt_tap_widget`, `fmt_hot_reload_and_capture`, etc.). The prefix is
mandatory in `tools/call`. Skill-local references below use the bare name
for readability — when invoking, prepend `fmt_`. Dynamic-registry host
tools (`fmt_list_client_tools_and_resources`, `fmt_client_tool`,
`fmt_client_resource`) use the same prefix for a single consistent surface.
## Interaction loop (Playwright-style)
1. `fmt_semantic_snapshot` → returns `s_0..s_N` refs + `snapshot_id`.
2. `fmt_tap_widget` / `fmt_enter_text` / `fmt_scroll` / `fmt_swipe` / `fmt_long_press` / `fmt_drag` — act on a ref. **Always pass `snapshotId`** — you get a structured `stale_snapshot` error if the tree moved, instead of a silent wrong tap.
3. `fmt_evaluate_dart_expression` — read state directly (e.g. `AgentState.instance.counter`).
4. `fmt_hot_reload_and_capture` — after a code edit, returns reload status + screenshot + fresh snapshot + errors in one response. Prefer this over manual reload + separate capture.
## Error envelope contract
Errors are `{code, message, details, descriptor, recovery}`. Parse `error.descriptor` (not the top-level object) for the machine-readable shape. Strict schemas default to `additionalProperties: false` — unknown params reject.
Common codes and recovery:
- `connection_selection_required` — retry with `arguments.connection.targetId` or exact `arguments.connection.uri` from `app.debugPort.wsUri`.
- `target_not_found` — refresh targets, then prefer exact `arguments.connection.uri`.
- `stale_snapshot` — call `fmt_semantic_snapshot` again, then retry the action with the new `snapshot_id`.
- `tool_not_found` — confirm the prefixed name (`fmt_<tool>`); v3.0.0 dropped legacy unprefixed names.
- Empty screenshot output — verify the server was not started with `--no-images`.
- Missing view resource/tool — verify the server was not started with `--no-resources`.
## Visual QA
- Before/after screenshots are the proof artifact for any UI claim. Capture before with `fmt_capture_ui_snapshot` (or one of the `visual://localhost/...` resources), edit, `fmt_hot_reload_and_capture`, compare.
- For each reported visual issue, attach coordinate + `fmt_inspect_widget_at_point` output.
- Map defects to source via `fmt_get_app_errors` top stack frame (`file`, `line`, `column`) when available.
- Do **not** use `fmt_debug_dump_*` unless explicitly requested (server must be started with `--dumps`; high token cost).
## Permissions (macOS)
Screen Recording permission belongs to the process running `flutter-mcp-toolkit` (or the MCP server host). If visual capture is denied:
```bash
flutter-mcp-toolkit permissions status
flutter-mcp-toolkit permissions request
flutter-mcp-toolkit permissions open-settings
```
## Non-modifiable apps
If the target app cannot be instrumented (third-party binary, restricted env), report flutter-mcp as unavailable for that app. Do **not** claim screenshot/layout/error inspection success.
## Related
- For the dynamic-tools side (registering custom MCP tools from inside the Flutter app), see the `flutter-mcp-toolkit-custom-tools` skill.
- For routing across setup / inspect / control / debug skills, see `flutter-mcp-toolkit-guide`.
---
> Source: [Arenukvern/mcp_flutter](https://github.com/Arenukvern/mcp_flutter) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
章节与文件索引
按说明文件中的顺序排列。
何时使用
预检(始终是第一位)
工具命名(v3.0.0+)
交互循环(剧作家风格)
信封合同错误
文件/命令 -> flutter-mcp-toolkit · flutter-inspector · mcpServers · flutter-mcp-toolkit-runtime · ws://127.0.0.1:8181/.../ws · doctor · flutter-mcp-toolkit doctor --json · ext.mcp.toolkit.app_errors
内容校验值 -> a0fb1692e5c3
当前原文的自动摘译,尚未人工审校。
何时使用
用户引用正在运行的 Flutter 应用程序(调试模式)并希望对其进行检查、屏幕截图、交互或热重载。用户粘贴 VM 服务 URI (
ws://127.0.0.1:8181/.../ws) 或提及端口 8181。您需要运行时证明(屏幕截图之前/之后)来证明代码编辑已生效。预检(始终是第一位)
在任何依赖于虚拟机的调用之前:调用
doctor(或运行flutter-mcp-toolkit doctor --json)——解析环境、端口、应用程序可达性。确认目标上存在所需的工具包扩展:ext.mcp.toolkit.app_errors``ext.mcp.toolkit.view_details工具命名(v3.0.0+)
所有 MCP 工具均以
fmt_功能前缀显示(fmt_tap_widget、fmt_hot_reload_and_capture等)。该前缀在tools/call中是强制的。为了便于阅读,下面的技能本地引用使用裸名称 - 调用时,在前面添加fmt_。动态注册表主机工具(fmt_list_client_tools_and_resources、fmt_client_tool、交互循环(剧作家风格)
fmt_semantic_snapshot→返回s_0..s_N引用+snapshot_id。fmt_tap_widget/fmt_enter_text/fmt_scroll/fmt_swipe/fmt_long_press/fmt_drag— 根据参考进行操作。始终通过snapshotId——如果树移动了,你会得到一个结构化的stale_snapshot错误,而不是无声的错误点击。fmt_evaluate_dart_expression— 直接读取状态(例如AgentState.instance.counter)。fmt_hot_reload_and_capture— 代码编辑后,在一个响应中返回重新加载状态 + 屏幕截图 + 最新快照 + 错误。与手动重新加载+单独捕获相比,更喜欢这种方式。信封合同错误
错误是
{code, message, details, descriptor, recovery}。解析error.descriptor(不是顶级对象)以获取机器可读的形状。严格模式默认为additionalProperties: false——未知参数拒绝。常见代码和恢复:connection_selection_required— 使用arguments.connection.targetId重试或使用app.debugPort.wsUri中的精确arguments.connection.uri重试。target_not_found— 刷新目标,然后选择精确的arguments.connection.uri。