用于 AI 驱动开发的 Flutter Inspector MCP 服务器

GitHub 仓库

🔍 一个强大的模型上下文协议 (MCP) 服务器，可将您的 Flutter 应用程序与 Cursor、Claude 和 Cline 等 AI 编码助手连接起来。

<a href="https://glama.ai/mcp/servers/qnu3f0fa20"> <img width="380" height="200" src="https://glama.ai/mcp/servers/qnu3f0fa20/badge" alt="Flutter Inspector Server MCP server" /> </a>

本项目正在开发中，并非所有方法（主要与 Flutter Inspector 相关）都已实现。

但是，以下两种方法已通过 Flutter 测试：

• screenshot
• get_root_widget

目前，Flutter 通过转发服务器与 MCP 服务器配合使用。有关更多详细信息，请参阅 架构。

某些其他方法未经测试 - 它们可能有效，也可能无效。请谨慎使用。 稍后可能会从 MCP 服务器中删除大多数方法，以便专注于 Flutter 应用程序，也许还有 Jaspr。

!!警告!!

所有 DUMPS 工具都是非常繁重的操作，很容易使 AI 代理的上下文窗口过载。 请极其谨慎地使用它们。

🚀 快速开始

前提条件

• Node.js (v14 或更高版本)
• 以调试模式运行的 Flutter 应用程序
• 以下之一：Cursor、Claude 或 Cline AI 助手

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 Flutter Inspector：

npx -y @smithery/cli install @Arenukvern/mcp_flutter --client claude

从 GitHub 安装

对于想要为项目做出贡献或直接从源代码运行最新版本的开发人员，请按照以下步骤操作：

1. 克隆仓库：

   git clone https://github.com/Arenukvern/mcp_flutter
   cd flutter-inspector
   

2. 安装并构建依赖项：

   make install
   

   此命令安装 package.json 中列出的所有必需依赖项，然后构建 MCP 服务器和转发服务器。

3. 启动转发服务器：

   make forward
   

4. 将 DevTools Flutter 扩展添加到 Flutter 应用程序：

   flutter pub add --dev devtools_mcp_extension
   

5. 以调试模式启动您的 Flutter 应用程序

   ! 当前出于安全原因的解决方法是使用 --disable-service-auth-codes 运行。 如果您知道如何解决此问题，请告诉我！

   flutter run --debug --observatory-port=8181 --enable-vm-service --disable-service-auth-codes
   

6. 🛠️ 将 Flutter Inspector 添加到您的 AI 工具

   本地开发注意事项（GitHub 安装）：

   如果您从 GitHub 安装了 Flutter Inspector 并在本地构建了它，则需要调整 AI 工具配置中的路径，以指向您的本地 build/index.js 文件。 有关克隆和构建项目的说明，请参阅“从 GitHub 安装”部分。

   Cline 设置

   1. 添加到您的 .cline/config.json：

      {
        "mcpServers": {
          "flutter-inspector": {
            "command": "node",
            "args": [
              "/path/to/your/cloned/flutter-inspector/mcp_server/build/index.js"
            ],
            "env": {
              "PORT": "3334",
              "LOG_LEVEL": "critical"
            },
            "disabled": false
          }
        }
      }
      

   2. 重启 Cline
   3. Flutter Inspector 将自动在您的对话中可用

   Cursor 设置

   1. 打开 Cursor 的设置
   2. 转到“Features”选项卡
   3. 在“Model Context Protocol”下，添加服务器：

      {
        "mcpServers": {
          "flutter-inspector": {
            "command": "node",
            "args": [
              "/path/to/your/cloned/flutter-inspector/mcp_server/build/index.js"
            ],
            "env": {},
            "disabled": false,
            "autoApprove": []
          }
        }
      }
      

   4. 重启 Cursor
   5. 打开 Agent Panel (macOS 上 cmd + L)
   6. 准备就绪！ 尝试诸如“分析我的 Flutter 应用程序的 widget 树”之类的命令

   Claude 设置

   1. 添加到您的 Claude 配置文件：

      {
        "mcpServers": {
          "flutter-inspector": {
            "command": "node",
            "args": [
              "/path/to/your/cloned/flutter-inspector/mcp_server/build/index.js"
            ],
            "env": {
              "PORT": "3334",
              "LOG_LEVEL": "critical"
            },
            "disabled": false
          }
        }
      }
      

   2. 重启 Claude
   3. Flutter Inspector 工具将自动可用

🎯 您可以做什么（希望如此）

• 分析 Widget 树：获取有关您的 Flutter 应用程序结构的详细信息
• 检查导航：查看当前路由和导航状态
• 调试布局问题：了解 widget 关系和属性 <!-- - AI 驱动的辅助：根据您的应用程序上下文获取更智能的代码建议 -->

🔧 配置选项

环境变量 (.env)

# 将用于直接连接到 dart vm
DART_VM_PORT=8181
DART_VM_HOST=localhost

# 将用于此 MCP 服务器
MCP_SERVER_PORT=3535
MCP_SERVER_HOST=localhost

# 将用于转发服务器
FORWARDING_SERVER_PORT=8143
FORWARDING_SERVER_HOST=localhost

# 日志配置
LOG_LEVEL=critical

# 开发配置
NODE_ENV=development

命令行参数

--port, -p     # 服务器端口
--stdio        # 以 stdio 模式运行（默认：true）
--log-level    # 设置日志级别（debug、info、notice、warning、error、critical、alert、emergency），根据 https://spec.modelcontextprotocol.io/specification/2025-03-26/server/utilities/logging/#log-levels
--help         # 显示帮助

端口配置

所有 Flutter Inspector 工具都会自动连接到默认的 Flutter 调试端口 (8181)。 只有在以下情况下才需要指定端口：

• 您正在不同的端口上运行 Flutter
• 您正在运行多个 Flutter 实例
• 您已配置自定义调试端口

用法示例：

// 默认端口 (8181)
{
  "name": "debug_dump_render_tree"
}

// 自定义端口
{
  "name": "debug_dump_render_tree",
  "arguments": {
    "port": 8182
  }
}

🔧 故障排除

1. 连接问题

   • 确保您的 Flutter 应用程序以调试模式运行
   • 验证 Flutter 应用程序和 Inspector 中的端口是否匹配
   • 检查端口是否被另一个进程使用

2. AI 工具未检测到 Inspector

   • 在配置更改后重启 AI 工具
   • 验证配置 JSON 语法
   • 检查工具的日志中是否存在连接错误

📚 可用工具

如果未指定端口，所有工具默认使用端口 8181。 您可以通过提供特定的端口号来覆盖此设置。

实用程序方法（非直接 RPC 调用）

这些是辅助方法，提供超出直接 Flutter RPC 调用的附加功能：

• get_active_ports：列出所有在端口上侦听的 Flutter/Dart 进程
• get_supported_protocols：从 Flutter 应用程序检索支持的协议
• get_vm_info：从正在运行的 Flutter 应用程序获取详细的 VM 信息
• get_extension_rpcs：列出 Flutter 应用程序中所有可用的扩展 RPC

调试方法 (ext.flutter.debug*)

用于调试 Flutter 应用程序的直接 RPC 方法：

• debug_dump_render_tree：转储渲染树结构
• debug_dump_layer_tree：转储用于渲染分析的图层树
• debug_dump_semantics_tree：转储用于辅助功能分析的语义树
• debug_paint_baselines_enabled：切换基线绘制调试
• debug_dump_focus_tree：转储用于输入处理分析的焦点树

Inspector 方法 (ext.flutter.inspector.*)

用于检查 Flutter widget 树和布局的直接 RPC 方法：

• inspector_screenshot：拍摄 Flutter 应用程序的屏幕截图 <!-- - inspector_get_layout_explorer_node：获取特定 widget 的布局信息 -->

DartIO 方法 (ext.dart.io.*)

用于 Dart I/O 操作的直接 RPC 方法：

• dart_io_get_version：获取 Flutter 版本信息

方法类别

1. 直接 RPC 方法 这些方法直接映射到 Flutter 的扩展 RPC：

   • 所有以 debug_、inspector_ 或 dart_io_ 为前缀的方法
   • 每种方法对应于特定的 Flutter RPC 端点
   • 参数和返回值与 Flutter 的规范匹配

2. 实用程序方法 这些是辅助方法，提供附加功能：

   • 进程发现 (get_active_ports)
   • 协议检查 (get_supported_protocols)
   • VM 交互 (get_vm_info)
   • RPC 发现 (get_extension_rpcs)

方法命名约定

所有方法都遵循一致的命名模式：

• 实用程序方法：descriptive_name
• 调试方法：debug_*
• Inspector 方法：inspector_*
• DartIO 方法：dartio*
• 流方法：stream_*

每个方法名称都指示其类别和功能，从而更容易理解其目的和功能。

方法文档格式

每种方法都包括：

• 功能的清晰描述
• 必需和可选参数
• 返回值格式
• 类别指示（RPC 与实用程序）
• 相应的 Flutter RPC 端点（如果适用）

有关详细的实施说明，请参阅“实施新的 RPC 方法”部分。

🔧 实施新的 RPC 方法

分步指南

1. 添加 RPC 方法定义

   // 在 src/index.ts 中，添加到 FlutterRPC 中的相应组
   const FlutterRPC = {
     GroupName: {
       METHOD_NAME: createRPCMethod(RPCPrefix.GROUP, "methodName"),
       // ... 其他方法
     },
   };
   

2. 添加工具定义

   // 在 ListToolsRequestSchema 处理程序中
   {
     name: "method_name",
     description: "方法作用的清晰描述",
     inputSchema: {
       type: "object",
       properties: {
         port: {
           type: "number",
           description: "Flutter 应用程序正在运行的端口号（默认为 8181）",
         },
         // 如果需要，添加其他参数
         paramName: {
           type: "string", // 或 boolean、number 等
           description: "参数描述",
         }
       },
       required: ["paramName"], // 列出必需参数
     }
   }
   

3. 实施处理程序

   // 在 CallToolRequestSchema 处理程序中
   case "method_name": {
     const port = handlePortParam();
     // 获取并验证参数（如果有）
     const { paramName } = request.params.arguments as { paramName: string };
     if (!paramName) {
       throw new McpError(
         ErrorCode.InvalidParams,
         "paramName 参数是必需的"
       );
     }
     // 调用 RPC 方法
     return wrapResponse(
       this.invokeFlutterExtension(port, FlutterRPC.GroupName.METHOD_NAME, {
         paramName,
       })
     );
   }
   

实施清单

1. 方法定义

   • [ ] 添加到 FlutterRPC 中的相应组
   • [ ] 使用正确的 RPCPrefix
   • [ ] 遵循命名约定

2. 工具定义

   • [ ] 添加清晰的描述
   • [ ] 定义所有参数
   • [ ] 标记必需参数
   • [ ] 添加端口参数
   • [ ] 记录参数类型

3. 处理程序实施

   • [ ] 在 switch 语句中添加 case
   • [ ] 处理端口参数
   • [ ] 验证所有参数
   • [ ] 添加错误处理
   • [ ] 使用正确的类型
   • [ ] 返回包装的响应

4. 测试

   • [ ] 验证方法在调试模式下是否有效
   • [ ] 使用不同的参数值进行测试
   • [ ] 测试错误情况
   • [ ] 使用默认端口进行测试

实施示例

// 1. 添加 RPC 方法
const FlutterRPC = {
  Inspector: {
    GET_WIDGET_DETAILS: createRPCMethod(RPCPrefix.INSPECTOR, "getWidgetDetails"),
  }
};

// 2. 添加工具定义
{
  name: "get_widget_details",
  description: "获取有关特定 widget 的详细信息",
  inputSchema: {
    type: "object",
    properties: {
      port: {
        type: "number",
        description: "Flutter 应用程序正在运行的端口号（默认为 8181）",
      },
      widgetId: {
        type: "string",
        description: "要检查的 widget 的 ID",
      }
    },
    required: ["widgetId"],
  }
}

// 3. 实施处理程序
case "get_widget_details": {
  const port = handlePortParam();
  const { widgetId } = request.params.arguments as { widgetId: string };
  if (!widgetId) {
    throw new McpError(
      ErrorCode.InvalidParams,
      "widgetId 参数是必需的"
    );
  }
  await this.verifyFlutterDebugMode(port);
  return wrapResponse(
    this.invokeFlutterExtension(port, FlutterRPC.Inspector.GET_WIDGET_DETAILS, {
      widgetId,
    })
  );
}

常见模式

1. 参数验证

   • 始终验证必需参数
   • 使用 TypeScript 类型以确保类型安全
   • 抛出带有清晰消息的 McpError

2. 错误处理

   • 对异步操作使用 try-catch 块
   • 在需要时验证 Flutter 调试模式
   • 处理连接错误

3. 响应包装

   • 使用 wrapResponse 以实现一致的格式
   • 处理成功和错误情况
   • 适当地格式化响应数据

4. 端口处理

   • 使用 handlePortParam() 进行端口管理
   • 如果未指定，则默认为 8181
   • 验证端口号

AI 代理注意事项

在实施来自 todo.yaml 的方法时：

1. 遵循上述分步指南
2. 使用实施示例作为模板
3. 确保完成所有清单项目
4. 添加适当的错误处理和参数验证
5. 遵循常见模式部分
6. 彻底测试实施

对于每种新方法：

1. 检查方法的组（UI、DartIO、Inspector 等）
2. 从方法名称和上下文中确定必需参数
3. 按照标准模式实施
4. 添加适当的错误处理
5. 遵循现有的代码样式

Smithery 集成

Flutter Inspector 已在 Smithery 的注册表中注册，使其可以通过标准化接口被其他 AI 工具发现和使用。

集成架构

┌─────────────────┐     ┌──────────────┐     ┌──────────────┐     ┌─────────────────┐     ┌─────────────┐
│                 │     │              │     │              │     │                 │     │             │
│  Flutter App    │<--->│  DevTools    │<--->│  Forwarding  │<--->│   MCP Server   │<--->│  Smithery   │
│  (Debug Mode)   │     │  Extension   │     │  Server      │     │   (Registered) │     │  Registry   │
│                 │     │              │     │              │     │                 │     │             │
└─────────────────┘     └──────────────┘     └──────────────┘     └─────────────────┘     └─────────────┘

🤝 贡献

欢迎贡献！ 请随时提交拉取请求或在 GitHub 仓库 上报告问题。

📖 了解更多

• Flutter DevTools 文档
• Dart VM 服务协议
• Flutter DevTools RPC 常量（我猜并且希望它们是正确的：））

📄 许可证

MIT - 随意在您的项目中使用！

---

Flutter 和 Dart 是 Google LLC 的商标。