community-ff-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Prerequisites

前提条件

This skill requires the community-ff-mcp MCP server to be installed and connected. Before proceeding, check if the

list_projects

tool is available. If not, the user needs to set up the MCP server first:

Get a FlutterFlow API token from FlutterFlow > Profile > Account Settings > API Token (requires a paid FlutterFlow subscription)

Add the MCP server to your AI client:

bash

# 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>" } }

Restart your AI client, then verify by calling
```
list_projects
```

本技能要求安装并连接community-ff-mcp MCP服务器。在开始前，请检查

list_projects

工具是否可用。如果不可用，用户需要先设置MCP服务器：

从FlutterFlow > 个人资料 > 账户设置 > API令牌获取FlutterFlow API令牌（需要付费FlutterFlow订阅）

将MCP服务器添加到你的AI客户端：

bash

# Claude Code
claude mcp add flutterflow -e FLUTTERFLOW_API_TOKEN=<token> -- npx -y community-ff-mcp

# 其他客户端（Claude Desktop、Cursor、Windsurf）——添加到MCP配置：
# { "command": "npx", "args": ["-y", "community-ff-mcp"], "env": { "FLUTTERFLOW_API_TOKEN": "<token>" } }

重启AI客户端，然后通过调用
```
list_projects
```
验证

Overview

概述

The FlutterFlow MCP provides 25 tools for reading, inspecting, and editing FlutterFlow projects through YAML. It connects AI assistants to the FlutterFlow Project API, enabling programmatic access to pages, components, themes, actions, data models, and settings. All project data is represented as YAML files that can be fetched, cached locally, validated, and pushed back.

FlutterFlow MCP提供25个工具，可通过YAML读取、检查和编辑FlutterFlow项目。它将AI助手连接到FlutterFlow项目API，支持以编程方式访问页面、组件、主题、动作、数据模型和设置。所有项目数据都以YAML文件形式呈现，可被获取、本地缓存、验证并推送回平台。

Tool Catalog

工具目录

Discovery & Exploration

发现与探索

Tool	Purpose
`list_projects`	List all FF projects accessible to your API token
`list_project_files`	List YAML file keys in a project (supports prefix filter)
`list_pages`	List pages with human-readable names, scaffold IDs, and folders
`search_project_files`	Search file keys by keyword, prefix, or regex
`sync_project`	Download all project YAML to local cache for fast reads

工具	用途
`list_projects`	列出API令牌可访问的所有FF项目
`list_project_files`	列出项目中的YAML文件键（支持前缀过滤）
`list_pages`	列出包含可读名称、脚手架ID和文件夹的页面
`search_project_files`	按关键词、前缀或正则表达式搜索文件键
`sync_project`	下载所有项目YAML到本地缓存以实现快速读取

Reading & Understanding

读取与理解

Tool	Purpose
`get_page_by_name`	Fetch full page YAML by human-readable name
`get_project_yaml`	Fetch specific YAML file(s) by file key
`get_page_summary`	Quick page overview: widget tree, actions, params (cache-based)
`get_component_summary`	Quick component overview: widget tree, params (cache-based)
`find_component_usages`	Find all pages/components that use a given component
`find_page_navigations`	Find all actions that navigate to a given page

工具	用途
`get_page_by_name`	通过可读名称获取完整页面YAML
`get_project_yaml`	通过文件键获取特定YAML文件
`get_page_summary`	快速页面概览：组件树、动作、参数（基于缓存）
`get_component_summary`	快速组件概览：组件树、参数（基于缓存）
`find_component_usages`	查找使用指定组件的所有页面/组件
`find_page_navigations`	查找导航到指定页面的所有动作

Configuration & Settings

配置与设置

Tool	Purpose
`get_theme`	Theme colors, typography, breakpoints, widget defaults
`get_app_state`	App state variables, constants, environment settings
`get_api_endpoints`	API endpoint definitions (method, URL, headers, response)
`get_data_models`	Data structs, enums, Firestore collections, Supabase tables
`get_custom_code`	Custom actions, functions, widgets, AI agents (read-only)
`get_general_settings`	App Details, App Assets, Nav Bar & App Bar
`get_project_setup`	Firebase, Languages, Platforms, Permissions, Dependencies
`get_app_settings`	Authentication, Push Notifications, Deployment settings
`get_in_app_purchases`	Stripe, Braintree, RevenueCat, Razorpay config
`get_integrations`	Supabase, SQLite, GitHub, Algolia, Google Maps, AdMob, etc.

工具	用途
`get_theme`	主题颜色、排版、断点、组件默认值
`get_app_state`	应用状态变量、常量、环境设置
`get_api_endpoints`	API端点定义（方法、URL、请求头、响应）
`get_data_models`	数据结构、枚举、Firestore集合、Supabase表
`get_custom_code`	自定义动作、函数、组件、AI Agent（只读）
`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等集成

Editing & Documentation

编辑与文档

Tool	Purpose
`get_editing_guide`	Get recommended workflow and docs for a specific editing task
`get_yaml_docs`	Search/retrieve YAML reference docs by topic or file path
`validate_yaml`	Validate YAML content before pushing changes
`update_project_yaml`	Push validated YAML changes to the FF project

工具	用途
`get_editing_guide`	获取特定编辑任务的推荐工作流和文档
`get_yaml_docs`	按主题或文件路径搜索/检索YAML参考文档
`validate_yaml`	在推送更改前验证YAML内容
`update_project_yaml`	将经过验证的YAML更改推送到FF项目

Core Workflows

核心工作流

Discover & Explore a Project

发现与探索项目

Use this workflow when first connecting to a FlutterFlow project or when you need to understand its structure.

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

After syncing, all cache-based tools (

get_page_summary

get_component_summary

get_theme

get_app_state

, etc.) work without additional API calls.

首次连接到FlutterFlow项目或需要了解其结构时，使用此工作流。

1. list_projects → 选择目标projectId
2. sync_project(projectId) → 将所有YAML缓存到本地以实现快速读取
3. list_pages(projectId) → 查看所有包含可读名称、脚手架ID和文件夹的页面
4. get_page_summary(projectId, pageName) → 查看任意感兴趣页面的组件树概览

同步后，所有基于缓存的工具（

get_page_summary

、

get_component_summary

、

get_theme

、

get_app_state

等）无需额外API调用即可使用。

Read / Inspect a Page or Component

读取/检查页面或组件

Use this workflow to understand what a page contains, how it is structured, and how it connects to the rest of the app.

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

For components, use

get_component_summary

instead of

get_page_summary

. Component summaries resolve nested component references so you can see the full hierarchy.

需要了解页面包含内容、结构以及与应用其他部分的连接方式时，使用此工作流。

1. get_page_summary(projectId, pageName) → 快速概览组件树、动作、参数
2. get_page_by_name(projectId, pageName) → 获取完整YAML以查看详细信息
3. find_page_navigations(projectId, pageName) → 发现哪些动作会导航到此页面
4. find_component_usages(projectId, componentName) → 查找组件的所有使用位置

对于组件，使用

get_component_summary

替代

get_page_summary

。组件摘要会解析嵌套组件引用，以便查看完整层级结构。

Edit an Existing Widget

编辑现有组件

Use this workflow to modify a specific widget on a page without affecting the rest of the page.

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

Always edit at the node level. Editing the full page YAML for a single widget change risks overwriting unrelated content and is more error-prone.

需要修改页面上的特定组件而不影响页面其他部分时，使用此工作流。

1. get_page_by_name(projectId, pageName) → 获取完整页面YAML
2. 确定目标组件的节点文件键（格式：page/id-Scaffold_XXX/page-widget-tree-outline/node/id-Widget_YYY）
3. get_project_yaml(projectId, fileName: "page/id-.../node/id-Widget_XXX") → 获取单个节点YAML
4. 修改YAML —— 保持inputValue和mostRecentInputValue同步
5. validate_yaml(projectId, fileKey, content) → 推送前检查错误
6. update_project_yaml(projectId, {fileKey: content}) → 推送更改

始终在节点级别进行编辑。为单个组件更改编辑完整页面YAML可能会覆盖无关内容，且更容易出错。

Add a New Widget to a Page

向页面添加新组件

Use this workflow when you need to add new widgets to an existing page.

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

Pushing the tree outline and node files in a single call is critical. The server strips inline widget children from the tree outline, so nodes must be separate files.

需要向现有页面添加新组件时，使用此工作流。

1. get_page_by_name(projectId, pageName) → 了解当前组件树结构
2. get_yaml_docs(topic: "WidgetType") → 查找要添加的组件的YAML schema
3. 更新page-widget-tree-outline以包含新组件键的引用
4. 为每个新组件创建单独的节点文件（每个组件一个文件）
5. validate_yaml → 先验证树大纲，再验证每个节点文件
6. update_project_yaml → 在一次调用中同时推送树大纲和所有节点文件

在一次调用中推送树大纲和节点文件至关重要。服务器会从树大纲中剥离内联组件子项，因此节点必须是单独的文件。

Create a Reusable Component

创建可复用组件

Use this workflow to build a new component from scratch.

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

Remember: the root node of a component must have

isDummyRoot: true

. Callback triggers use

triggerType: CALLBACK

with a separate

parameterIdentifier

field. WidgetProperty params use

widgetProperty

in parameterPasses, not

inputValue

需要从头构建新组件时，使用此工作流。

1. get_yaml_docs(topic: "create component") → 获取完整指南和所需文件结构
2. 设计组件参数：每个参数的名称、dataType、isNullable
3. 创建以下文件：组件元数据、widget-tree-outline、根节点（设置isDummyRoot: true）、子节点
4. validate_yaml → 推送前验证所有文件
5. update_project_yaml → 在一次调用中推送所有组件文件

注意：组件的根节点必须设置

isDummyRoot: true

。回调触发器使用

triggerType: CALLBACK

和单独的

parameterIdentifier

字段。WidgetProperty参数在parameterPasses中使用

widgetProperty

，而非

inputValue

。

Critical YAML Rules

关键YAML规则

Sync inputValue and mostRecentInputValue -- Both fields must always contain the same value when you set or update them. If you change one, change both. Exceptions:
```
fontWeightValue
```
and
```
fontSizeValue
```
only accept
```
inputValue
```
(they have no
```
mostRecentInputValue
```
field).
Use node-level file keys for edits -- Target
```
page/id-Scaffold_XXX/page-widget-tree-outline/node/id-Widget_YYY
```
for individual widget edits. Never edit the full page YAML (
```
page/id-Scaffold_XXX
```
) just to change a single widget. Full-page edits risk overwriting unrelated content and are harder to validate.
Always validate before pushing -- Call
```
validate_yaml
```
before every
```
update_project_yaml
```
call. Validation catches missing node files, unknown fields, invalid enum values, and structural problems. Skipping validation risks corrupting the project.
Push tree outline and node files together -- When adding new widgets, include the updated
```
page-widget-tree-outline
```
AND all individual node files in a single
```
update_project_yaml
```
call. Widget children embedded inline in the tree outline will be silently stripped by the FlutterFlow server.
Column has no mainAxisSize field -- To achieve shrink-to-content behavior (equivalent to
```
MainAxisSize.min
```
in Flutter), use
```
minSizeValue: { inputValue: true }
```
on the Column widget instead.
AppBar templateType -- Only
```
LARGE_HEADER
```
is a confirmed valid value. Do not use
```
STANDARD
```
as it may cause unexpected behavior. Control the AppBar height through the
```
toolbarHeight
```
property instead.
Custom code is read-only -- Custom actions, functions, widgets, and AI agents cannot be created or edited through the MCP API. Use
```
get_custom_code
```
to read their signatures and source code, but any modifications must be made directly in the FlutterFlow UI. Attempting to push custom code changes will silently corrupt or be ignored.

同步inputValue和mostRecentInputValue —— 当你设置或更新这两个字段时，它们必须始终包含相同的值。如果修改其中一个，必须同时修改另一个。例外情况：
```
fontWeightValue
```
和
```
fontSizeValue
```
仅接受
```
inputValue
```
（它们没有
```
mostRecentInputValue
```
字段）。
使用节点级文件键进行编辑 —— 针对单个组件编辑，使用
```
page/id-Scaffold_XXX/page-widget-tree-outline/node/id-Widget_YYY
```
。切勿仅为更改单个组件而编辑完整页面YAML（
```
page/id-Scaffold_XXX
```
）。全页面编辑可能会覆盖无关内容，且更难验证。
推送前始终验证 —— 在每次调用
```
update_project_yaml
```
前调用
```
validate_yaml
```
。验证会捕获缺失的节点文件、未知字段、无效枚举值和结构问题。跳过验证可能会损坏项目。
同时推送树大纲和节点文件 —— 添加新组件时，在一次
```
update_project_yaml
```
调用中同时包含更新后的
```
page-widget-tree-outline
```
和所有单独的节点文件。嵌入在树大纲中的组件子项会被FlutterFlow服务器静默剥离。
Column组件无mainAxisSize字段 —— 要实现收缩至内容的行为（相当于Flutter中的
```
MainAxisSize.min
```
），请在Column组件上使用
```
minSizeValue: { inputValue: true }
```
。
AppBar的templateType —— 仅
```
LARGE_HEADER
```
是已确认的有效值。不要使用
```
STANDARD
```
，否则可能导致意外行为。请通过
```
toolbarHeight
```
属性控制AppBar高度。
自定义代码为只读 —— 无法通过MCP API创建或编辑自定义动作、函数、组件和AI Agent。使用
```
get_custom_code
```
读取其签名和源代码，但任何修改必须直接在FlutterFlow UI中进行。尝试推送自定义代码更改会被静默损坏或忽略。

Anti-Patterns

反模式

Don't use
list_project_files
to find pages -- It returns raw file keys without human-readable names. Use
```
list_pages
```
instead, which gives you page names, scaffold IDs, and folder assignments.
Don't fetch pages one-by-one to browse a project -- This is slow and wastes API calls. Use
```
sync_project
```
to cache everything locally first, then use
```
get_page_summary
```
for quick overviews of any page.
Don't edit full page YAML for a single widget change -- Full-page edits can overwrite other widgets, actions, or parameters. Always use node-level file keys for targeted, safe edits.
Don't guess YAML field names or enum values -- FlutterFlow YAML has specific field names and valid values that are not always intuitive. Use
```
get_yaml_docs(topic)
```
or
```
get_editing_guide(task)
```
to look up the correct schema before writing YAML.
Don't embed widget children inline in the tree outline -- The FlutterFlow server silently strips inline children from the
```
page-widget-tree-outline
```
file. Always create separate node files for each widget.
Don't push custom code changes through the API -- The API silently corrupts or ignores Dart code edits for custom actions, functions, and widgets. These must be edited in the FlutterFlow UI.

不要使用
list_project_files
查找页面 —— 它返回的是原始文件键，而非可读名称。请改用
```
list_pages
```
，它会提供页面名称、脚手架ID和文件夹分配。
不要逐个获取页面以浏览项目 —— 这速度慢且浪费API调用。请先使用
```
sync_project
```
将所有内容缓存到本地，然后使用
```
get_page_summary
```
快速查看任意页面的概览。
不要为单个组件更改编辑完整页面YAML —— 全页面编辑可能会覆盖其他组件、动作或参数。始终使用节点级文件键进行针对性的安全编辑。
不要猜测YAML字段名称或枚举值 —— FlutterFlow YAML有特定的字段名称和有效值，这些并不总是直观的。在编写YAML前，请使用
```
get_yaml_docs(topic)
```
或
```
get_editing_guide(task)
```
查找正确的schema。
不要在树大纲中嵌入组件子项 —— FlutterFlow服务器会从
```
page-widget-tree-outline
```
文件中静默剥离内联子项。始终为每个组件创建单独的节点文件。
不要通过API推送自定义代码更改 —— API会静默损坏或忽略针对自定义动作、函数和组件的Dart代码编辑。这些必须在FlutterFlow UI中编辑。

Documentation Lookup

文档查找

The MCP server ships with 21 built-in reference documents. Use these tools to look up schemas, patterns, and conventions before writing YAML:

When you need...	Call
Widget schema (Button, Text, Container, etc.)	`get_yaml_docs(topic: "Button")`
Action chains, triggers, navigation	`get_yaml_docs(topic: "actions")`
Data binding, variable sources	`get_yaml_docs(topic: "variables")`
Colors, typography, dimensions	`get_yaml_docs(topic: "theming")`
Creating components from scratch	`get_yaml_docs(topic: "create component")`
Editing workflows and anti-patterns	`get_yaml_docs(topic: "editing")`
Data structs, enums, collections	`get_yaml_docs(topic: "data")`
Full docs index	`get_yaml_docs()`
Guided workflow for a specific task	`get_editing_guide(task: "change the button color")`

Always consult the docs before writing YAML. They contain validated schemas, field references, enum values, and real examples.

MCP服务器附带21个内置参考文档。在编写YAML之前，请使用这些工具查找schema、模式和约定：

当你需要...	调用
组件schema（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前请务必查阅文档。它们包含经过验证的schema、字段参考、枚举值和实际示例。