flutterflow-mcp 0.1.0

package/build/utils/page-summary/tree-walker.js

@@ -0,0 +1,55 @@
+/**
+ * Parse a page-widget-tree-outline YAML into a recursive OutlineNode tree.
+ *
+ * The outline YAML has a `node` root with named slots (body, appBar, header,
+ * collapsed, expanded) and `children` arrays. Each entry has a `key` field.
+ */
+import YAML from "yaml";
+/** Named slots that can appear on a node alongside `children`. */
+const SLOT_KEYS = [
+    "body",
+    "appBar",
+    "title",
+    "header",
+    "collapsed",
+    "expanded",
+    "floatingActionButton",
+    "drawer",
+    "endDrawer",
+    "bottomNavigationBar",
+];
+/**
+ * Parse a raw outline node (from YAML) into an OutlineNode.
+ * `slot` indicates how this node was referenced by its parent.
+ */
+function parseNode(raw, slot) {
+    const key = raw.key ?? "unknown";
+    const children = [];
+    // Named slots
+    for (const s of SLOT_KEYS) {
+        const child = raw[s];
+        if (child && typeof child === "object" && child.key) {
+            children.push(parseNode(child, s));
+        }
+    }
+    // Explicit children array
+    const rawChildren = raw.children;
+    if (Array.isArray(rawChildren)) {
+        for (const child of rawChildren) {
+            children.push(parseNode(child, "children"));
+        }
+    }
+    return { key, slot, children };
+}
+/**
+ * Parse the page-widget-tree-outline YAML string into an OutlineNode tree.
+ * Returns the root node (typically the Scaffold).
+ */
+export function parseTreeOutline(yamlContent) {
+    const doc = YAML.parse(yamlContent);
+    const root = doc.node;
+    if (!root || !root.key) {
+        throw new Error("Invalid tree outline: missing root node");
+    }
+    return parseNode(root, "root");
+}

package/build/utils/page-summary/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Types for the page summary tool.
+ */
+/** Summary of a single action in a trigger chain. */
+export interface ActionSummary {
+    type: string;
+    detail: string;
+}
+/** Summary of a trigger (event handler) on a widget. */
+export interface TriggerSummary {
+    trigger: string;
+    actions: ActionSummary[];
+}
+/** A node in the summarized widget tree. */
+export interface SummaryNode {
+    key: string;
+    type: string;
+    name: string;
+    slot: string;
+    detail: string;
+    triggers: TriggerSummary[];
+    children: SummaryNode[];
+}
+/** Parameter metadata from the top-level page YAML. */
+export interface ParamInfo {
+    name: string;
+    dataType: string;
+    defaultValue?: string;
+}
+/** State field metadata from the top-level page YAML. */
+export interface StateFieldInfo {
+    name: string;
+    dataType: string;
+    defaultValue?: string;
+}
+/** Top-level page metadata. */
+export interface PageMeta {
+    pageName: string;
+    scaffoldId: string;
+    folder: string;
+    params: ParamInfo[];
+    stateFields: StateFieldInfo[];
+}
+/** Top-level component metadata. */
+export interface ComponentMeta {
+    componentName: string;
+    containerId: string;
+    description: string;
+    params: ParamInfo[];
+}
+/** Raw tree node from the widget tree outline YAML. */
+export interface OutlineNode {
+    key: string;
+    slot: string;
+    children: OutlineNode[];
+}

package/build/utils/page-summary/types.js

@@ -0,0 +1,4 @@
+/**
+ * Types for the page summary tool.
+ */
+export {};

package/build/utils/parse-folders.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parse the FlutterFlow `folders` YAML file to build a
+ * scaffoldId → folderName mapping.
+ *
+ * The file has two sections:
+ *   rootFolders:        (nested tree of { key, name, children })
+ *   widgetClassKeyToFolderKey:   (flat Scaffold_XXX: folderKey)
+ */
+export declare function parseFolderMapping(foldersYaml: string): Record<string, string>;

package/build/utils/parse-folders.js

@@ -0,0 +1,29 @@
+/**
+ * Parse the FlutterFlow `folders` YAML file to build a
+ * scaffoldId → folderName mapping.
+ *
+ * The file has two sections:
+ *   rootFolders:        (nested tree of { key, name, children })
+ *   widgetClassKeyToFolderKey:   (flat Scaffold_XXX: folderKey)
+ */
+export function parseFolderMapping(foldersYaml) {
+    // 1. Build folderKey → name from the rootFolders tree
+    const keyToName = {};
+    const keyNameRegex = /key:\s*(\w+)\s*\n\s*name:\s*(.+)/g;
+    let match;
+    while ((match = keyNameRegex.exec(foldersYaml)) !== null) {
+        keyToName[match[1]] = match[2].trim();
+    }
+    // 2. Build scaffoldId → folderName from widgetClassKeyToFolderKey
+    const scaffoldToFolder = {};
+    const widgetSection = foldersYaml.split("widgetClassKeyToFolderKey:")[1];
+    if (widgetSection) {
+        const mappingRegex = /\s+(Scaffold_\w+):\s*(\w+)/g;
+        while ((match = mappingRegex.exec(widgetSection)) !== null) {
+            const scaffoldId = match[1];
+            const folderKey = match[2];
+            scaffoldToFolder[scaffoldId] = keyToName[folderKey] || folderKey;
+        }
+    }
+    return scaffoldToFolder;
+}

package/docs/ff-yaml/00-overview.md

@@ -0,0 +1,137 @@
+# FlutterFlow Project Structure
+
+Every FlutterFlow project is a collection of YAML files accessed via file keys. This document maps every file type and explains how file keys work.
+
+---
+
+## File taxonomy
+
+| File key pattern | Purpose |
+|---|---|
+| `app-details` | App metadata: name, routing config, initial page, auth pages, theme mode, platform settings |
+| `authentication` | Firebase/Supabase auth configuration, providers, login/signup page refs |
+| `theme` | Typography definitions, color palette, breakpoints, widget defaults |
+| `folders` | Page and component folder organization (scaffold-to-folder mapping) |
+| `app-state` | App-wide persisted state variables (shared across all pages) |
+| `app-constants` | Read-only constants available app-wide |
+| `app-assets` | Uploaded asset references (images, fonts, files) |
+| `nav-bar` | Bottom navigation bar configuration (pages, icons, labels) |
+| `app-bar` | App bar configuration |
+| `permissions` | Permission definitions and role-based access rules |
+| `revenue-cat` | RevenueCat paywall and entitlement configuration |
+| `languages` | Internationalization strings and locale mappings |
+| `page/id-Scaffold_XXX` | Page metadata: name, params, classModel (state fields), route config |
+| `page/id-Scaffold_XXX/page-widget-tree-outline` | Widget tree hierarchy for the page (key refs only, no props) |
+| `page/id-Scaffold_XXX/page-widget-tree-outline/node/id-Widget_YYY` | Individual widget node: type, props, parameterValues, valueKey |
+| `page/.../node/id-Widget_YYY/trigger_actions/id-TRIGGER/action/id-ZZZ` | Action definition attached to a widget trigger |
+| `component/id-Container_XXX` | Component metadata: name, params, classModel |
+| `component/id-Container_XXX/component-widget-tree-outline` | Component widget tree hierarchy |
+| `component/id-Container_XXX/component-widget-tree-outline/node/id-Widget_YYY` | Component widget node |
+| `api-endpoint/id-XXX` | API endpoint: URL, method, headers, body, response schema |
+| `custom-actions/id-XXX` | Custom Dart action: name, params, return type, code |
+| `custom-functions/id-XXX` | Custom Dart function: name, params, return type, code |
+| `custom-widgets/id-XXX` | Custom Flutter widget: name, params, code |
+| `data-structs/id-XXX` | Data structure (struct/class) definition with typed fields |
+| `enums/id-XXX` | Enum definition with named values |
+| `collections/id-XXX` | Firestore collection schema: fields, types, subcollections |
+| `agent/id-XXX` | AI agent configuration |
+
+---
+
+## File key patterns
+
+File keys are hierarchical paths used with the `get_project_yaml` and `update_project_yaml` MCP tools.
+
+### Anatomy of a file key
+
+```
+page/id-Scaffold_tjgkshke/page-widget-tree-outline/node/id-Button_7c3kwr61
+|    |                     |                         |    |
+|    |                     |                         |    └─ Widget ID
+|    |                     |                         └─ node segment (fixed)
+|    |                     └─ Sub-file type
+|    └─ Page scaffold ID (prefixed with id-)
+└─ Top-level category
+```
+
+### Depth levels
+
+| Level | Example key | What it returns |
+|---|---|---|
+| 0 | `app-details` | Entire config file |
+| 1 | `page/id-Scaffold_XXX` | Page metadata only (name, params, state, route) |
+| 2 | `page/id-Scaffold_XXX/page-widget-tree-outline` | Widget tree structure (key refs, no props) |
+| 3 | `page/.../page-widget-tree-outline/node/id-Widget_YYY` | Single widget with all props |
+| 4 | `page/.../node/id-Widget_YYY/trigger_actions/id-ON_TAP/action/id-ZZZ` | Single action definition |
+
+### Component keys follow the same pattern
+
+```
+component/id-Container_XXX
+component/id-Container_XXX/component-widget-tree-outline
+component/id-Container_XXX/component-widget-tree-outline/node/id-Widget_YYY
+```
+
+Note: Components use `component-widget-tree-outline` (not `page-widget-tree-outline`).
+
+---
+
+## Critical rule: Node-level files
+
+Widget children **must** be pushed as individual node files. They cannot be embedded inline in the page-level YAML.
+
+### Why
+
+The FlutterFlow API strips inline children from `page/id-Scaffold_XXX`. The page file only stores metadata (name, params, classModel, route). Widget data lives exclusively in the widget tree outline and node sub-files.
+
+### What this means in practice
+
+To add or modify widgets, you always push **multiple files** in a single `update_project_yaml` call:
+
+```
+update_project_yaml(projectId, {
+  "page/id-Scaffold_XXX/page-widget-tree-outline":                    <tree outline YAML>,
+  "page/id-Scaffold_XXX/page-widget-tree-outline/node/id-Column_YYY": <column node YAML>,
+  "page/id-Scaffold_XXX/page-widget-tree-outline/node/id-Text_ZZZ":   <text node YAML>,
+  "page/id-Scaffold_XXX/page-widget-tree-outline/node/id-Button_AAA": <button node YAML>
+})
+```
+
+### Tree outline format
+
+The widget tree outline defines hierarchy via key references:
+
+```yaml
+node:
+  key: Scaffold_XXX
+  body:
+    key: Column_YYY
+    children:
+      - key: Text_ZZZ
+      - key: Button_AAA
+```
+
+Each `key` referenced here must have a corresponding `node/id-<key>` file pushed alongside it.
+
+### Validation shortcut
+
+Call `validate_yaml` on the tree outline first. It returns `"File is referenced but is empty"` for any node that is referenced but has no corresponding file -- telling you exactly which node files you need to create.
+
+---
+
+## ID generation
+
+When creating new widgets, pages, or other entities, generate IDs following this pattern:
+
+```
+<TypePrefix>_<8 lowercase alphanumeric characters>
+```
+
+Examples:
+- `Scaffold_k7m2x9p1`
+- `Column_ab3def45`
+- `Button_zz9wq2r8`
+- `Text_mn4kp7s6`
+- `Container_xy1abc23`
+
+The prefix must match the widget/entity type exactly. The suffix should be unique within the project.