MCP Flutter Debug Server

Flutter 开发以其跨平台能力和热重载特性深受开发者喜爱，但调试 Flutter 应用时，我们仍然需要在代码编辑器和运行中的应用之间频繁切换——查看 Widget 树、定位布局问题、分析运行时错误。MCP Flutter Debug Server 彻底改变了这一流程。它将 Flutter 应用的调试能力通过模型上下文协议（MCP）直接注入 AI 编程助手（如 Cursor、Claude、Cline），让你在编辑器中就能让 AI 分析 Widget 树、捕获截图、诊断错误，真正实现“在上下文中调试”。

项目基本信息

一、项目介绍

MCP Flutter Debug Server 是一个专为 Flutter 开发者设计的 MCP 服务器，其核心理念是将 Flutter 调试能力从独立工具迁移到 AI 对话中。它运行在你的 Flutter 应用和 MCP 客户端之间，通过 Dart VM 服务获取运行时信息，并将其转化为 AI 可以理解的工具调用。

核心工具集

动态工具注册——本项目独有的亮点

与官方 Dart MCP 服务器的最大区别在于：MCP Flutter Debug Server 支持动态工具注册。Flutter 应用在运行时可以调用 MCPToolkitBinding.instance.addEntries() 向 MCP 服务器注册自定义工具和资源。这意味着你的应用可以将任意内部状态——比如购物车内容、用户操作日志——作为 MCP 工具暴露给 AI 助手。

二、核心优势

为 AI 优化的错误诊断

get_app_errors 工具不仅仅返回原始错误日志。它会自动压缩和去重错误信息，只保留简短描述，防止大量重复堆栈信息淹没 AI 的上下文窗口。更智能的是，它在返回错误时还会提供处理建议，告诉 AI “可以尝试这样修复”。

所见即所得的调试体验

view_screenshot 工具让 AI 能够“看见”你的应用界面。结合 get_view_details 的 Widget 树信息，AI 可以对比“应该出现的效果”和“实际截图”，诊断 UI 渲染问题。例如：“按钮为什么被截断了？看看截图和 Widget 尺寸。”

可扩展的定制化工具生态

动态工具注册机制将 MCP 服务器从“固定工具箱”变成了“可编程接口”。你可以为自己的 Flutter 应用创建专属的调试和诊断工具——比如暴露数据库查询、网络请求日志、用户行为追踪——全部通过统一的 MCP 协议让 AI 访问。

MIT 开源协议，社区友好

采用完全商业友好的 MIT 协议，可以自由使用、修改和分发。

三、适用场景

AI 辅助 Widget 树调试

用户：我的登录按钮点击没反应，帮我看看 Widget 树里这个按钮是否被其他控件遮挡了。

AI 调用 get_view_details 获取 Widget 结构和布局信息，判断是否有 GestureDetector 或 InkWell 被覆盖。

运行时错误自动诊断

用户：应用启动时报了一个红色错误，帮我看看是什么问题。

AI 调用 get_app_errors 获取压缩后的错误信息，分析原因并给出修复建议。

UI 视觉回归检查

用户：帮我截个图，看看新改的这个页面和老版本有什么不同。

AI 调用 view_screenshot 获取当前页面截图，然后基于图像识别能力对比视觉差异。

自定义调试工具开发

开发者：我想让 AI 能直接查看我们应用的网络请求日志。

在 Flutter 应用中使用动态工具注册机制，注册一个 get_network_logs 工具，AI 就能在对话中直接调用了。

四、安装教程

环境要求

安装步骤

第一步：克隆仓库

git clone https://github.com/Arenukvern/mcp_flutter.git
cd mcp_flutter

第二步：安装依赖

dart pub get

第三步：启动 MCP 服务器

dart run bin/mcp_server_dart.dart

可选参数：

• --port：指定 MCP 服务器端口（默认 8181）
• --images：启用截图功能
• --dumps：启用转储类方法（如 dump_render_tree，注意会消耗大量 token）

第四步：在 Flutter 应用中集成

在你的 Flutter 应用的 pubspec.yaml 中添加依赖：

dependencies:
  mcp_toolkit: ^latest_version

然后在应用代码中初始化并注册自定义工具：

void main() {
  MCPToolkitBinding.instance.addEntries([
    // 注册你的自定义工具
  ]);
  runApp(MyApp());
}

第五步：配置 MCP 客户端

以 Cursor 为例，在 MCP 配置中添加：

{
  "mcpServers": {
    "flutter-debug": {
      "command": "dart",
      "args": ["run", "bin/mcp_server_dart.dart"],
      "env": {}
    }
  }
}

保存配置后重启 MCP 客户端。

快速实验

你可以直接让 AI 助手帮你完成安装。在 Cursor 或 Cline 中发送以下提示词：

请通过此链接安装 MCP 服务端：https://github.com/Arenukvern/mcp_flutter/blob/main/llm_install.md

五、使用示例

示例一：诊断运行时错误

用户：我的 Flutter 应用运行时出现了错误，帮我看看是什么问题。

AI 调用 get_app_errors，获取压缩后的错误列表，分析后回复：“检测到 NoSuchMethodError，发生在 _LoginScreenState.build 中。你可能在调用一个 null 对象的 text 属性。建议检查传递给 CustomButton 的 label 参数是否为 null。”

示例二：检查 Widget 布局

用户：为什么我的列表项被截断了？帮我看看 Widget 树。

AI 调用 get_view_details，获取 Widget 结构和布局约束信息，回复：“你的 ListView 被一个固定高度 200px 的 Container 包裹，导致剩余列表项不可见。建议将 Container 改为 Expanded 或者移除固定高度。”

示例三：截图对比

用户：截个图，看看首页改完后是什么样子。

AI 调用 view_screenshot，返回当前应用截图。如果 AI 支持多模态输入，它还能描述截图中看到的内容。

示例四：热重启应用

用户：我已经修改了代码，帮我热重启一下应用。

AI 调用 hot_restart_flutter，触发 Flutter 的 VM 服务热重启，保持应用状态重置。

六、常见问题

问：连接失败，提示“无法连接到 Flutter 应用”怎么办？

答：请检查：

1. Flutter 应用是否以调试模式运行（不是发布模式）。
2. MCP 服务器端口（默认 8181）是否与配置一致。
3. 端口是否被其他进程占用。可以用 lsof -i :8181 检查。

问：截图功能无法使用，返回空白或报错？

答：确保启动 MCP 服务器时添加了 --images 标志。没有这个标志，view_screenshot 工具不会被注册。

问：get_app_errors 返回的错误太简略，想查看完整堆栈怎么办？

答：默认行为是压缩和去重错误信息以适应 AI 上下文窗口。如果需要完整堆栈，可以在应用代码中使用标准 Dart 调试方法查看详情。此工具的定位是“快速诊断”，而非“完整日志”替代。

问：动态注册的工具在 AI 客户端中看不到？

答：请确认：

1. Flutter 应用正确初始化了 mcp_toolkit 包。
2. 通过 MCPToolkitBinding.instance.addEntries() 正确注册了工具。
3. 注册工具后执行了热重载（hot reload）。
4. 可以在 AI 客户端中使用 listClientToolsAndResources 验证注册状态。

七、总结

MCP Flutter Debug Server 是 Flutter 调试工作流与 AI 辅助编程深度结合的一次创新实践。它不仅提供了 Widget 树分析、错误诊断、截图捕获等核心调试工具，更通过独树一帜的动态工具注册机制，赋予了开发者构建个性化调试体验的能力。

对于 Flutter 开发者来说，这个项目意味着“调试”不再是需要切换到独立工具的独立步骤，而是成为了 AI 编程助手的原生能力。花十几分钟完成配置，你将获得一位能够“看到”你的应用、“诊断”你的错误，甚至能按照你的需求扩展调试能力的 AI 搭档。