community-ff-mcp

前提条件

このスキルを使用するには、community-ff-mcp MCP サーバーがインストールされ、接続されている必要があります。先に、list_projects ツールが利用可能か確認してください。利用できない場合は、まずユーザーが MCP サーバーをセットアップする必要があります。

1. FlutterFlow > Profile > Account Settings > API Token から FlutterFlow API トークンを取得します（FlutterFlow の有料サブスクリプションが必要です）。
2. MCP サーバーを AI クライアントに追加します。

   # Claude Code
   claude mcp add flutterflow -e FLUTTERFLOW_API_TOKEN=<token> -- npx -y community-ff-mcp
   
   # Other clients (Claude Desktop, Cursor, Windsurf) — add to MCP config:
   # { "command": "npx", "args": ["-y", "community-ff-mcp"], "env": { "FLUTTERFLOW_API_TOKEN": "<token>" } }
   

3. AI クライアントを再起動し、list_projects を呼び出して確認します。

概要

FlutterFlow MCP は、YAML を介して FlutterFlow プロジェクトを読み取り、調査、編集するための 25 個のツールを提供します。AI アシスタントを FlutterFlow Project API に接続し、ページ、コンポーネント、テーマ、アクション、データモデル、設定にプログラムからアクセスできるようにします。すべてのプロジェクトデータは YAML ファイルとして表現され、取得、ローカルへのキャッシュ、検証後、プッシュバックできます。

ツールカタログ

検出と探索

ツール	目的
list_projects	API トークンからアクセスできるすべての FF プロジェクトを一覧表示します
list_project_files	プロジェクト内の YAML ファイルキーを一覧表示します（プレフィックスフィルターに対応）
list_pages	人が読める名前、スキャフォールド ID、フォルダーとともにページを一覧表示します
search_project_files	キーワード、プレフィックス、または正規表現でファイルキーを検索します
sync_project	すべてのプロジェクト YAML をローカルキャッシュにダウンロードし、高速な読み取りを可能にします

読み取りと理解

ツール	目的
get_page_by_name	人が読める名前を指定して、ページの完全な YAML を取得します
get_project_yaml	ファイルキーを指定して、特定の YAML ファイルを取得します
get_page_summary	ページの概要をすばやく確認します：ウィジェットツリー、アクション、パラメーター（キャッシュベース）
get_component_summary	コンポーネントの概要をすばやく確認します：ウィジェットツリー、パラメーター（キャッシュベース）
find_component_usages	指定したコンポーネントを使用しているページとコンポーネントをすべて検索します
find_page_navigations	指定したページに遷移するアクションをすべて検索します

構成と設定

ツール	目的
get_theme	テーマの色、タイポグラフィ、ブレークポイント、ウィジェットのデフォルト設定
get_app_state	アプリの状態変数、定数、環境設定
get_api_endpoints	API エンドポイントの定義（メソッド、URL、ヘッダー、レスポンス）
get_data_models	データ構造体、列挙型、Firestore コレクション、Supabase テーブル
get_custom_code	カスタムアクション、関数、ウィジェット、AI エージェント（読み取り専用）
get_general_settings	アプリの詳細、アプリアセット、ナビゲーションバーとアプリバー
get_project_setup	Firebase、言語、プラットフォーム、権限、依存関係
get_app_settings	認証、プッシュ通知、デプロイ設定
get_in_app_purchases	Stripe、Braintree、RevenueCat、Razorpay の設定
get_integrations	Supabase、SQLite、GitHub、Algolia、Google Maps、AdMob など

編集とドキュメント

ツール	目的
get_editing_guide	特定の編集タスクに推奨されるワークフローとドキュメントを取得します
get_yaml_docs	トピックまたはファイルパスで YAML リファレンスドキュメントを検索／取得します
validate_yaml	変更をプッシュする前に YAML コンテンツを検証します
update_project_yaml	検証済みの YAML 変更を FF プロジェクトにプッシュします

主なワークフロー

プロジェクトの検出と探索

FlutterFlow プロジェクトに初めて接続するときや、その構造を把握する必要があるときに、このワークフローを使用します。

1. list_projects → pick the target projectId
2. sync_project(projectId) → cache all YAML locally for fast reads
3. list_pages(projectId) → see all pages with human-readable names, scaffold IDs, folders
4. get_page_summary(projectId, pageName) → widget tree overview for any page of interest

同期後は、キャッシュベースのすべてのツール（get_page_summary、get_component_summary、get_theme、get_app_state など）が、追加の API 呼び出しなしで動作します。

ページまたはコンポーネントの読み取り／調査

ページの内容、構造、アプリの他の部分とのつながりを把握するには、このワークフローを使用します。

1. get_page_summary(projectId, pageName) → quick overview of widget tree, actions, params
2. get_page_by_name(projectId, pageName) → full YAML if you need complete details
3. find_page_navigations(projectId, pageName) → discover what actions navigate here
4. find_component_usages(projectId, componentName) → find everywhere a component is used

コンポーネントの場合は、get_page_summary の代わりに get_component_summary を使用します。コンポーネントの概要では、ネストされたコンポーネント参照が解決されるため、階層全体を確認できます。

既存のウィジェットを編集する

ページのほかの部分に影響を与えずに、ページ上の特定のウィジェットを変更するには、このワークフローを使用します。

1. get_page_by_name(projectId, pageName) → get the full page YAML
2. Identify the node file key for the target widget (format: page/id-Scaffold_XXX/page-widget-tree-outline/node/id-Widget_YYY)
3. get_project_yaml(projectId, fileName: "page/id-.../node/id-Widget_XXX") → fetch the individual node YAML
4. Modify the YAML — keep inputValue and mostRecentInputValue in sync
5. validate_yaml(projectId, fileKey, content) → check for errors before pushing
6. update_project_yaml(projectId, {fileKey: content}) → push changes

必ずノードレベルで編集してください。1つのウィジェットを変更するためにページ全体の YAML を編集すると、無関係なコンテンツを上書きするリスクがあり、エラーも発生しやすくなります。

ページに新しいウィジェットを追加する

既存のページに新しいウィジェットを追加する必要がある場合は、このワークフローを使用します。

1. get_page_by_name(projectId, pageName) → understand the current widget tree structure
2. get_yaml_docs(topic: "WidgetType") → look up the YAML schema for the widget you want to add
3. Update the page-widget-tree-outline to include a reference to the new widget key
4. Create individual node files for each new widget (one file per widget)
5. validate_yaml → validate the tree outline first, then each node file
6. update_project_yaml → push tree outline + all node files together in one call

ツリーアウトラインとノードファイルを1回の呼び出しでプッシュすることが重要です。サーバーはツリーアウトラインからインラインのウィジェットの子要素を削除するため、ノードは個別のファイルにする必要があります。

再利用可能なコンポーネントを作成する

新しいコンポーネントを一から作成するには、このワークフローを使用します。

1. get_yaml_docs(topic: "create component") → get the full walkthrough and required file structure
2. Design component parameters: name, dataType, isNullable for each param
3. Create these files: component metadata, widget-tree-outline, root node (with isDummyRoot: true), child nodes
4. validate_yaml → validate all files before pushing
5. update_project_yaml → push all component files in one call

コンポーネントのルートノードには、isDummyRoot: true を指定する必要があります。コールバックのトリガーには triggerType: CALLBACK を使用し、別途 parameterIdentifier フィールドを指定します。WidgetProperty のパラメーターでは、parameterPasses に inputValue ではなく widgetProperty を使用します。

重要な YAML ルール

1. inputValue と mostRecentInputValue を同期する -- これらのフィールドを設定または更新するときは、必ず両方に同じ値を指定してください。一方を変更した場合は、もう一方も変更します。例外として、fontWeightValue と fontSizeValue は inputValue のみを受け付けます（mostRecentInputValue フィールドはありません）。

2. 編集にはノードレベルのファイルキーを使用する -- 個別のウィジェットを編集する場合は、page/id-Scaffold_XXX/page-widget-tree-outline/node/id-Widget_YYY を対象にします。単一のウィジェットを変更するために、ページ全体の YAML（page/id-Scaffold_XXX）を編集しないでください。ページ全体を編集すると、無関係なコンテンツを上書きするリスクがあり、検証も難しくなります。

3. プッシュする前に必ず検証する -- update_project_yaml を呼び出す前に、必ず validate_yaml を呼び出してください。検証により、ノードファイルの欠落、不明なフィールド、無効な列挙値、構造上の問題を検出できます。検証を省略すると、プロジェクトが破損するおそれがあります。

4. ツリーアウトラインとノードファイルをまとめてプッシュする -- 新しいウィジェットを追加するときは、更新後の page-widget-tree-outline とすべての個別のノードファイルを、1回の update_project_yaml 呼び出しに含めます。ツリーアウトラインにインラインで埋め込まれたウィジェットの子要素は、FlutterFlow サーバーによって通知なく削除されます。

5. Column に mainAxisSize フィールドはありません -- Flutter の MainAxisSize.min と同等のコンテンツに合わせて縮小する動作を実現するには、代わりに Column ウィジェットで minSizeValue: { inputValue: true } を使用します。

6. AppBar の templateType -- 有効であることが確認されている値は LARGE_HEADER のみです。予期しない動作を引き起こす可能性があるため、STANDARD は使用しないでください。代わりに toolbarHeight プロパティで AppBar の高さを調整します。

7. カスタムコードは読み取り専用です -- カスタムアクション、関数、ウィジェット、AI エージェントは、MCP API を通じて作成または編集できません。get_custom_code を使用してシグネチャとソースコードを読み取れますが、変更は FlutterFlow UI で直接行う必要があります。カスタムコードの変更をプッシュしようとすると、通知なく破損するか、無視されます。

アンチパターン

• ページを探すために list_project_files を使わないでください — 人間が読み取れる名前ではなく、生のファイルキーが返されます。代わりに list_pages を使うと、ページ名、スキャフォールド ID、フォルダーの割り当てを確認できます。

• プロジェクトを閲覧するためにページを1つずつ取得しないでください — 時間がかかり、API 呼び出しを無駄にします。まず sync_project を使ってすべてをローカルにキャッシュし、その後 get_page_summary で任意のページの概要をすばやく確認してください。

• 単一のウィジェットを変更するために、ページ全体の YAML を編集しないでください — ページ全体の編集では、他のウィジェット、アクション、パラメーターが上書きされる可能性があります。対象を絞った安全な編集には、必ずノードレベルのファイルキーを使ってください。

• YAML のフィールド名や列挙値を推測しないでください — FlutterFlow YAML には固有のフィールド名と有効な値があり、直感的とは限りません。YAML を記述する前に、get_yaml_docs(topic) または get_editing_guide(task) を使って正しいスキーマを確認してください。

• ツリーアウトライン内にウィジェットの子要素をインラインで埋め込まないでください — FlutterFlow サーバーは page-widget-tree-outline ファイル内のインラインの子要素を警告なしに削除します。各ウィジェットについて、必ず個別のノードファイルを作成してください。

• API 経由でカスタムコードの変更をプッシュしないでください — API はカスタムアクション、関数、ウィジェットの Dart コード編集を警告なしに破損させたり、無視したりします。これらは FlutterFlow UI で編集する必要があります。

ドキュメントの参照

MCP サーバーには、組み込みのリファレンスドキュメントが21件含まれています。YAML を記述する前に、これらのツールを使ってスキーマ、パターン、規約を確認してください。

必要な情報...	呼び出すツール
ウィジェットのスキーマ（Button、Text、Container など）	get_yaml_docs(topic: "Button")
アクションチェーン、トリガー、ナビゲーション	get_yaml_docs(topic: "actions")
データバインディング、変数ソース	get_yaml_docs(topic: "variables")
色、タイポグラフィ、寸法	get_yaml_docs(topic: "theming")
コンポーネントをゼロから作成する方法	get_yaml_docs(topic: "create component")
編集ワークフローとアンチパターン	get_yaml_docs(topic: "editing")
データ構造体、列挙型、コレクション	get_yaml_docs(topic: "data")
ドキュメントの全索引	get_yaml_docs()
特定のタスク向けのガイド付きワークフロー	get_editing_guide(task: "change the button color")

YAML を記述する前に、必ずドキュメントを参照してください。検証済みのスキーマ、フィールドのリファレンス、列挙値、実例が記載されています。