flutter-mcp-toolkit-setup

使用时机

在以下情况下使用此技能：

• 首次安装：flutter-mcp-toolkit 或其短别名 fmtk 尚未加入 PATH。
• doctor --json 返回的任何检查项的 "status": "fail"。
• MCP 服务连接失败，或工具返回 vm_not_connected / connect_failed。
• 视觉捕获或 toolkit-bridge 命令返回意外错误。

---

验证安装

flutter-mcp-toolkit --help
fmtk --help

预期输出：两个名称都显示命令帮助。flutter-mcp-toolkit 是规范的长名称；fmtk 是日常终端循环中使用的简短别名。

如果出现 command not found，说明二进制文件不在 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

然后使用 flutter-mcp-toolkit --help 和 fmtk --help 验证。

---

运行 doctor

在运行任何依赖 VM 的命令前，始终先运行 doctor：

fmtk doctor --json

标志：--target <ws_uri>（测试特定 URI）、全局标志 --vm-service-uri <ws_uri>（在 doctor 中省略 --target 时与之相同）、--timeout-ms <n>（默认值：2500）。

# Global URI works for doctor (same as validate-runtime)
fmtk --vm-service-uri 'ws://127.0.0.1:8181/<token>/ws' doctor --json

绿色状态输出示例：

{
  "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 }
  ]
}

问题排查：criticalFailures > 0 表示 VM/设置受阻，并不意味着所有工具都无法使用。dynamic_registry_available: pass 且 vm_target_reachable: fail 通常意味着热重启后 URI 已过期；运行 discover_debug_apps 并传入新的 targetId。

读取 error.descriptor（而非顶层内容）以查看重试策略和退出代码。每项检查都包含 fix_command，可直接运行。

---

按错误代码恢复

binary_not_found

二进制文件缺失或不在 PATH 中。重新构建并添加到 PATH：

cd /path/to/mcp_flutter && make build
export PATH="$PATH:/path/to/mcp_flutter/mcp_server_dart/build"

vm_not_connected

Flutter 应用未运行、重启后令牌已过期，或 URI 未解析：

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

成功自动重新连接后，meta.recovery.reattachedTo 会显示新的端点。

connect_failed

端口错误、应用尚未启动或令牌已过期。传入来自 app.debugPort.wsUri 的显式 URI：

fmtk exec --name get_vm --args '{"connection":{"uri":"ws://127.0.0.1:8181/<token>/ws"}}'

connection_selection_required

检测到多个调试目标。使用 discover_debug_apps 列出目标，然后将来自 details.availableTargets 的所选 URI 显式传给 get_vm。

hot_reload_failed

Dart 编译错误或 VM 已断开连接。检查错误并修复，然后重试：

fmtk exec --name get_app_errors --args '{}'

visual_capture_unsupported

未授予 macOS 屏幕录制权限，或平台不受支持：

fmtk permissions request --kind visual_capture

---

连接问题（深入排查）

端口冲突：VM 服务默认使用 8181。如果端口被其他进程占用，请更改端口：

flutter run --debug --host-vmservice-port=8182 -d macos
fmtk --dart-vm-port 8182 doctor --json

需要确切的 websocket URI 时，使用 flutter run --machine 并复制 app.debugPort.wsUri（建议用于 validate-runtime 和 exec）。

Flutter 应用未处于调试模式：Release/profile 构建不会公开 VM 服务。始终使用 flutter run --debug。

mcp_toolkit 未初始化：Doctor 的 mcp_toolkit_extensions 检查将失败。请在 runApp 前添加初始化代码，并使用 flutter-mcp-toolkit codegen-init 生成样板代码（见下方 CLI 用法）。添加后请热重启（不要热重载，因为绑定初始化需要完整重启）。

多个应用 / 目标错误：传入带有确切 websocket URI 的 --target：

fmtk doctor --json --target ws://127.0.0.1:8181/<token>/ws

---

CLI 用法

规范的二进制文件名为 flutter-mcp-toolkit（构建在 mcp_server_dart/build/ 中）。打包安装还包含 fmtk，它是指向同一入口点的短别名。快速循环中使用 fmtk；在安装、入门、PATH 和 MCP 配置文档中保留长名称。

子命令	用途	最简示例
exec	对 VM 运行单个指定命令	fmtk exec --name get_vm --args '{}'
batch	一次调用运行多个命令	fmtk batch --steps '[{"name":"get_vm"},{"name":"status"}]'
schema	打印指定命令的 JSON 架构	fmtk schema --name hot_reload_flutter
capabilities	列出所有已注册的能力	fmtk capabilities
serve	启动 MCP 服务（stdio 传输）	fmtk serve
snapshot create	捕获并保存命名快照	fmtk snapshot create --name baseline --args '{}'
snapshot diff	比较两个快照	fmtk snapshot diff --from baseline --to current
bundle create	将快照打包为可发布的包	fmtk bundle create --from-snapshot baseline --output ./out
doctor	运行预检（VM + 工具包 + 注册表）	fmtk doctor --json
permissions status	检查一项权限（例如 visual_capture）	fmtk permissions status --kind visual_capture
permissions request	请求一项权限	fmtk permissions request --kind visual_capture
permissions open-settings	打开操作系统中该权限的设置	fmtk permissions open-settings --kind visual_capture
validate-runtime	端到端 VM + 工具包 + 捕获冒烟测试	fmtk validate-runtime --target ws://127.0.0.1:8181/<token>/ws
init <agent>	为 AI Agent 安装技能和 MCP 服务配置	flutter-mcp-toolkit init claude-code
codegen-init	添加工具包依赖并生成 main.dart 样板代码	flutter-mcp-toolkit codegen-init

全局标志（位于子命令之前）：--dart-vm-port <n>、--dart-vm-host <host>、--vm-service-uri <ws_uri>、--log-level <level>、--dumps、-h/--help。

VM 目标设置： 如果未指定子命令的 --target，全局 --vm-service-uri 将应用于 doctor 和 validate-runtime。如果两者都已设置但值不同，则以 --target 为准（并在 stderr 输出警告）。

validate-runtime 截图： 首次捕获使用 auto（在 macOS 上通常为 desktop_window）。如果该步骤因可重试的 get_screenshots_failed 错误而失败，CLI 会使用 flutter_layer 重试一次。成功时，JSON 信封中的 data.summary.captureFallbackUsed 为 true。 **调试/评估套件：**首先将重复检查保留为脚本，或使用现有基础功能进行 batch 调用：--log-level debug、--output-dir、--save-images、doctor --json、validate-runtime、batch 和 exec --name diagnose。不要公开通用的 MCP run_tool；MCP 仍然采用类型化的 fmt_* 工具接口。如果某个流程成为可在多个项目中重复使用的场景，请将其纳入本仓库 showcase/ 或 packages/harness 中，并以 Dart 代码提交，而不是添加仅供工具包使用的场景语言。

---

init <agent>

为 AI Agent 安装 flutter-mcp-toolkit 技能和 MCP 服务配置。

目标：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

模式会自动检测（已注册 MCP 则使用 MCP，否则使用 CLI）。使用 --mode mcp|cli|auto 可覆盖。

替代方案（仅安装技能，开放生态）：npx skills add Arenukvern/mcp_flutter -a cursor -y 通过 skills.sh 安装相同的 SKILL.md 文件包；此命令不会写入 mcp.json——请随后运行 init，或手动配置 mcpServers。参见 AI Agent 概览。

---

codegen-init

在 Flutter 项目根目录中，将 mcp_toolkit 添加为依赖项，并生成 用于 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

---

重新安装 / 升级

安装脚本具有幂等性——重新运行会原位替换二进制文件：

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

重新安装后，使用 flutter-mcp-toolkit --help 和 fmtk --help 验证。