flutter_structure_mcp

Flutter Architect MCP

flutter_architect_mcp 是一个模型上下文协议（MCP）服务和命令行工具，旨在自动化创建新 Flutter 应用的初始搭建流程。它会设置架构结构、注入所需的软件包依赖、配置路由、数据库、网络和后端，并将一系列全面的共享工具、组件和扩展复制到生成的代码库中。

---

提供内容

该项目包含完整的模板库和生成器流水线，组织如下：

├── bin/
│   ├── server.dart                 # MCP Server entry point (communicates via stdio)
│   └── flutter_architect_mcp.dart  # Direct dart run test script
├── config/
│   ├── packages.yaml               # Map of package versions for different setup choices
│   └── architecture.yaml           # Supported architectures configuration
├── lib/
│   ├── generators/
│   │   ├── project_generator.dart      # Master orchestrator
│   │   ├── architecture_generator.dart # Clean, MVC, and MVVM template setup
│   │   ├── state_generator.dart        # Bloc, GetX, Provider, Riverpod, RxDart
│   │   ├── package_generator.dart      # Database, Router, Network, Backend setup
│   │   └── feature_generator.dart      # Generates features (login, dashboard, profile, home)
│   ├── models/
│   │   └── project_config.dart         # Encapsulates configuration parameters
│   ├── services/
│   │   ├── copy_service.dart           # Directory cloner with smart import rewriting
│   │   ├── flutter_service.dart        # Runs `flutter create` and `flutter pub get`
│   │   ├── yaml_service.dart           # YAML parser helper
│   │   └── pubspec_service.dart        # Dynamic dependency injector into pubspec.yaml
│   └── tools/
│       ├── architectures_create/
│       │   └── create_project.dart     # CLI runner script
│       └── scanners_and_audit_reports/
│           └── run_audit.dart          # Audit CLI runner script
└── templates/                      # Core template assets
    ├── architecture/               # Codebases for clean, mvc, and mvvm
    ├── state/                      # State configurations
    ├── network/                    # dio, retrofit templates
    ├── database/                   # hive, isar, drift templates
    ├── backend/                    # firebase, supabase templates
    ├── router/                     # go_router, auto_route, own_extensions templates
    ├── feature/                    # login, dashboard, profile, home templates
    └── shared/                     # Common widgets, extensions, and helpers

包含的共享资源：

从 templates/shared 复制的所有资源都会自动调整，以便在新项目中编译：

• 通用组件：对话框、自定义动画下拉菜单、Toast 消息（flushbars）、加载器、WebView 封装、自定义按钮、文本字段和列表视图加载器。
• 扩展：Padding、Alignment、颜色解析、字符串处理、DateTime 格式化、Double 格式化、Shimmer 覆盖层、Svg 集成，以及 TextStyle/BuildContext 扩展。
• 辅助工具：Shared Preferences 封装、验证辅助工具、设备连接检查器、深层链接辅助工具、通知辅助工具、图像和文档选择器、触觉反馈辅助工具，以及强制更新检查器。

---

执行流程

生成项目时，该工具会执行以下步骤：

graph TD;
    A[Start: CLI or MCP Request] --> B[Run 'flutter create' in Target Dir];
    B --> C[Replace default 'lib' folder with Architecture Template];
    C --> D[Add State Management Template & Packages];
    D --> E[Add Database Templates & Packages];
    E --> F[Add Backend Templates & Packages];
    F --> G[Add Router Templates & Packages];
    G --> H[Add Network Templates & Packages];
    H --> I[Copy Features login, dashboard, profile, home];
    I --> J[Inject Shared utils, common widgets, helpers, extensions];
    J --> K[Rewrite Hardcoded package:expense_tracker/ Imports to package:projectName/];
    K --> L[Run 'flutter pub get' in Generated Project];
    L --> M[Project Ready & Fully Compilable!];

---

使用与访问方式

你可以通过以下三种方式运行生成器：

1. 作为 MCP 工具使用（推荐用于 AI 助手）

在你的大模型桌面客户端中配置 flutter_architect_mcp（例如 Claude Desktop、Cursor 或 VS Code MCP 插件）。

Claude Desktop 配置：

将以下内容添加到你的 claude_desktop_config.json（macOS 上通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "flutter-architect": {
      "command": "dart",
      "args": [
        "run",
        "/path/to/your/project/my_mcp/flutter_architect_mcp/bin/server.dart"
      ]
    }
  }
}

提供的工具架构：

• 工具名称：create_project
• 参数：
  • projectName（String，必填）：项目名称，使用小写 snake_case 格式。
  • architecture（String，必填）：clean、mvc 或 mvvm。
  • stateManagement（String，可选）：bloc、getx、provider、riverpod 或 rxdart。
  • database（String，可选）：hive、isar 或 drift。
  • backend（String，可选）：firebase 或 supabase。
  • network（String，可选）：dio 或 retrofit。
  • router（String，可选）：go_router、auto_route 或 own_extensions。
  • targetDirectory（String，可选）：输出目录的绝对路径（默认为当前目录）。

客户端提示词示例（自然语言命令）：

• 审计代码库（Flutter、Node、Vue、Laravel、Python）：

  "请对位于 /path/to/project 的项目进行全面审计。生成 HTML/PDF 报告，并发送电子邮件至 [email protected]（可选）。"

• 自动检测技术并运行审计：

  "对文件夹 /path/to/project 中的代码库进行全面审计。自动检测项目类型，并分别输出报告。"

• 搭建 Flutter 应用：

  "在 /path/to/output 创建一个名为 my_app 的新 Flutter 应用，采用 MVVM 架构、Riverpod 状态管理、Drift 数据库和 GoRouter。"

• 建议并应用修复：

  "为 /path/to/project 生成建议的修复，并安全地应用这些修复。"

• 启动性能监控服务：

  "在端口 8080 上启动性能监控仪表板服务。"

---

2. 通过命令行界面（CLI）

你可以使用标准参数直接调用独立 CLI 工具：

dart run lib/tools/architectures_create/create_project.dart \
  --name my_awesome_app \
  --arch clean \
  --state bloc \
  --db hive \
  --backend firebase \
  --network dio \
  --router go_router \
  --target /path/to/output/folder

CLI 标志：

• --name：项目名称（必填）
• --arch：架构风格：clean、mvc、mvvm（必填）
• --state：状态管理：bloc、getx、provider、riverpod、rxdart
• --db：本地数据库：hive、isar、drift
• --backend：后端服务：firebase、supabase
• --network：网络客户端：dio、retrofit
• --router：路由方案：go_router、auto_route、own_extensions
• --target：父文件夹的绝对路径（默认为当前路径）

---

3. 直接运行程序脚本

运行预配置的 flutter_architect_mcp.dart 脚本，即可快速测试或启动默认工作区设置：

dart run bin/flutter_architect_mcp.dart

此脚本会在本地目录中生成一个名为 expense_tracker_with_mcp 的预配置项目，使用 clean 架构、bloc、hive、firebase、dio 和 go_router。

---

运行时性能检查工具

运行时性能监控器会启动一个本地服务，托管类似 DevTools 的实时 Web 仪表板，用于分析运行中的屏幕、HTTP API 耗时、堆内存（RAM）以及本地数据库存储占用。停止会话后，会将所有指标汇总为格式化且可打印的 PDF HTML 报告。

1. 启动仪表板服务

你可以直接通过 CLI 启动仪表板服务：

dart run lib/tools/scanners_and_audit_reports/run_runtime_perf.dart --port 8080

• 端口标志： 使用 --port <number> 设置自定义端口（默认值为 8080）。
• 访问仪表板： 在 Web 浏览器中打开 http://localhost:8080。

2. 在 MCP 服务中注册

你可以通过 MCP 服务使用 start_runtime_perf_check 工具启动该工具：

{
  "name": "start_runtime_perf_check",
  "arguments": {
    "port": 8080
  }
}

3. 集成到 Flutter 应用中

复制仪表板 Integration Guide 标签页中显示的辅助代码集成：

• 网络请求拦截器： 将自定义 Dio 拦截器添加到 HTTP 客户端，以记录请求方法、端点、响应状态和耗时。
• 屏幕路由观察器： 在 MaterialApp 的观察器中注册 PerfNavigatorObserver，以跟踪导航变化。
• 定时内存与存储数据流： 在 main() 中启动后台计时器，以持续发送 RAM（RSS）大小和本地数据库文件大小数据点。

所有数据都会直接流向仪表板。点击仪表板上的 Stop & Save PDF 按钮，即可导出包含修复步骤的详细工程评审报告！

---

4. 连接模拟器、仿真器和真实设备

若要让正在运行的移动应用将指标发送回本地性能服务，请根据目标设备环境配置连接 URL：

A. iOS 模拟器（macOS 主机）

由于 iOS 模拟器直接运行在主机 Mac 上，因此可以通过 localhost 连接：

• 连接 URL： http://localhost:8080/api/record

B. Android 仿真器（虚拟设备）

Android 仿真器运行在虚拟环回环境中。要访问主机的 localhost，请使用特殊 IP 地址 10.0.2.2：

• 连接 URL： http://10.0.2.2:8080/api/record

C. 物理 Android 设备（通过 USB 连接）

你可以使用 ADB 将设备的 8080 端口转发到计算机：

1. 在终端中运行以下命令：

   adb reverse tcp:8080 tcp:8080
   

2. 现在，你的应用可以直接使用 localhost：
   • 连接 URL： http://localhost:8080/api/record

D. 物理 iOS / Android 设备（通过 Wi-Fi 连接）

1. 确保开发计算机和移动设备都连接到同一个 Wi-Fi 网络。
2. 查找计算机的本地 IP 地址（例如 192.168.1.45 或 10.0.0.12）。
3. 在 Flutter 应用中使用该 IP 地址：
   • 连接 URL： http://<your-computer-ip>:8080/api/record