flutter_structure_mcp

Flutter Architect MCP

flutter_architect_mcp は、新しい Flutter アプリケーションのひな形作成プロセスを自動化するために設計された、Model Context Protocol（MCP）サーバーおよびコマンドラインユーティリティです。アーキテクチャ構造を設定し、必要なパッケージ依存関係を注入し、ルーティング、データベース、ネットワーク、バックエンドの設定を行い、共有ユーティリティ、ウィジェット、拡張機能の包括的なコレクションを生成されたコードベースにコピーします。

---

提供内容

このプロジェクトには、完全なテンプレートライブラリと、次のように構成されたジェネレーターパイプラインが含まれています。

├── 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 からコピーされたすべてのアセットは、新しいプロジェクトでコンパイルできるよう自動的に調整されます。

• 共通ウィジェットコンポーネント：ダイアログ、カスタムアニメーション付きドロップダウン、トーストメッセージ（flushbars）、ローダー、WebView ラッパー、カスタムボタン、テキストフィールド、リストビューローダー。
• 拡張機能：Padding、Alignment、Color の解析、String 操作、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!];

---

使用方法とアクセス方法

ジェネレーターは 3 つの方法で実行できます。

1. MCP ツールとして（AI アシスタントにおすすめ）

LLM デスクトップクライアント（Claude Desktop、Cursor、VS Code MCP プラグインなど）で flutter_architect_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 レポートを生成し、チームにメールで送信してください（任意）。"

• テクノロジーの自動検出と監査の実行：

  "/path/to/project フォルダーのコードベース全体を監査してください。プロジェクトの種類を自動検出し、個別のレポートを出力してください。"

• Flutter アプリのスキャフォールディング：

  "MVVM アーキテクチャ、Riverpod 状態管理、Drift データベース、GoRouter を使用して、/path/to/output に my_app という名前の新しい Flutter アプリを作成してください。"

• 修正の提案と適用：

  "/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

このスクリプトは、clean アーキテクチャ、bloc、hive、firebase、dio、go_router を使用した expense_tracker_with_mcp という名前の事前設定済みプロジェクトを、ローカルディレクトリに生成します。

---

実行時パフォーマンスチェックツール

実行時パフォーマンスモニターは、ローカルサーバーを起動し、稼働中の画面、HTTP API の応答時間、ヒープメモリ（RAM）、ローカルデータベースのストレージ使用量をプロファイルできる、DevTools のようなライブウェブダッシュボードを提供します。セッションを停止すると、すべてのメトリクスが書式設定済みの印刷可能な PDF HTML レポートにまとめられます。

1. ダッシュボードサーバーの起動

CLI からダッシュボードサーバーを直接起動できます。

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

• ポートフラグ： --port <number> を使ってカスタムポートを設定します（デフォルトは 8080 です）。
• ダッシュボードへのアクセス： ウェブブラウザーで http://localhost:8080 を開きます。

2. MCP サーバーへの登録

start_runtime_perf_check ツールを使って、MCP サーバーからツールを起動できます。

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

3. Flutter アプリケーションとの統合

ダッシュボードの Integration Guide タブに表示されるヘルパーコードをコピーして統合します。

• ネットワークリクエストインターセプター： カスタム Dio インターセプターを HTTP クライアントに追加して、リクエストメソッド、エンドポイント、レスポンスステータス、所要時間を記録します。
• 画面ルートオブザーバー： PerfNavigatorObserver を MaterialApp のオブザーバーに登録して、ナビゲーションの変更を追跡します。
• 定期的なメモリとストレージのストリーマー： main() 内でバックグラウンドタイマーを起動し、RAM（RSS）サイズとローカル DB ファイルサイズのデータポイントをストリーミングします。

すべてのデータストリームはダッシュボードに直接送信されます。ダッシュボードの 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. USB 接続の Android 実機

ADB を使って、デバイスからコンピューターへポート 8080 を転送できます。

1. ターミナルで次のコマンドを実行します。

   adb reverse tcp:8080 tcp:8080
   

2. これでアプリから localhost を直接使用できるようになります。
   • 接続 URL： http://localhost:8080/api/record

D. Wi-Fi 接続の iOS／Android 実機

1. 開発用コンピューターとモバイルデバイスの両方が、同じ Wi-Fi ネットワークに接続されていることを確認します。
2. コンピューターのローカル IP アドレス（例：192.168.1.45 または 10.0.0.12）を確認します。
3. Flutter アプリ内でその IP アドレスを使用します。
   • 接続 URL： http://<your-computer-ip>:8080/api/record