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 提供 25 个工具，用于通过 YAML 读取、检查和编辑 FlutterFlow 项目。它将 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 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 等

编辑与文档

工具	用途
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_component_summary，而非 get_page_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

始终在节点级别进行编辑。仅为修改单个组件而编辑整页 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. 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 中使用 widgetProperty，而不是 inputValue。

关键 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. 同时推送树大纲和节点文件——添加新组件时，在一次 update_project_yaml 调用中同时包含更新后的 page-widget-tree-outline 和所有单独的节点文件。嵌入树大纲的组件子节点会被 FlutterFlow 服务器静默剥离。

5. Column 没有 mainAxisSize 字段——若要实现内容收缩行为（相当于 Flutter 中的 MainAxisSize.min），请在 Column 组件上使用 minSizeValue: { inputValue: true }。

6. AppBar 的 templateType——目前确认有效的值只有 LARGE_HEADER。不要使用 STANDARD，否则可能导致意外行为。请改用 toolbarHeight 属性控制 AppBar 的高度。

7. 自定义代码为只读——无法通过 MCP API 创建或编辑自定义操作、函数、组件和 AI Agent。可使用 get_custom_code 读取其签名和源代码，但所有修改都必须直接在 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) 查找正确的架构。

• 不要在树形大纲中内联嵌入组件子项 —— 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 前，请务必查阅文档。其中包含经过验证的架构、字段参考、枚举值和真实示例。