community-ff-mcp 0.4.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,58 @@
+/**
+ * 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;
+    componentRef?: string;
+    componentId?: 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/build/utils/resolve-data-type.d.ts

@@ -0,0 +1,2 @@
+/** Resolve a scalar/list data type to a readable string. */
+export declare function resolveDataType(dt: Record<string, unknown>): string;

package/build/utils/resolve-data-type.js

@@ -0,0 +1,18 @@
+/** Resolve a scalar/list data type to a readable string. */
+export function resolveDataType(dt) {
+    if (dt.listType) {
+        const inner = dt.listType;
+        return `List<${inner.scalarType || "unknown"}>`;
+    }
+    if (dt.scalarType === "DataStruct") {
+        const sub = dt.subType;
+        const dsi = sub?.dataStructIdentifier;
+        return dsi?.name ? `DataStruct:${dsi.name}` : "DataStruct";
+    }
+    if (dt.enumType) {
+        const en = dt.enumType;
+        const eid = en.enumIdentifier;
+        return eid?.name ? `Enum:${eid.name}` : "Enum";
+    }
+    return dt.scalarType || "unknown";
+}

package/build/utils/topic-map.d.ts

@@ -0,0 +1,7 @@
+export declare const DOCS_DIR: string;
+/** Topic-to-file mapping for fuzzy search. */
+export declare const TOPIC_MAP: Record<string, string>;
+/** List all doc files recursively. */
+export declare function listDocFiles(dir: string, prefix?: string): string[];
+/** Read a doc file. Returns null if not found. */
+export declare function readDoc(relPath: string): string | null;

package/build/utils/topic-map.js

@@ -0,0 +1,122 @@
+/**
+ * Shared TOPIC_MAP, DOCS_DIR, and doc-reading helpers.
+ * Used by get_yaml_docs and get_editing_guide tools.
+ */
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export const DOCS_DIR = path.resolve(__dirname, "../../docs/ff-yaml");
+/** Topic-to-file mapping for fuzzy search. */
+export const TOPIC_MAP = {
+    // Widgets
+    button: "04-widgets/button.md",
+    iconbutton: "04-widgets/button.md",
+    text: "04-widgets/text.md",
+    richtext: "04-widgets/text.md",
+    richtextspan: "04-widgets/text.md",
+    textfield: "04-widgets/text-field.md",
+    "text-field": "04-widgets/text-field.md",
+    input: "04-widgets/text-field.md",
+    container: "04-widgets/container.md",
+    boxdecoration: "04-widgets/container.md",
+    column: "04-widgets/layout.md",
+    row: "04-widgets/layout.md",
+    stack: "04-widgets/layout.md",
+    wrap: "04-widgets/layout.md",
+    layout: "04-widgets/layout.md",
+    image: "04-widgets/image.md",
+    form: "04-widgets/form.md",
+    validation: "04-widgets/form.md",
+    dropdown: "04-widgets/dropdown.md",
+    choicechips: "04-widgets/dropdown.md",
+    icon: "04-widgets/misc.md",
+    progressbar: "04-widgets/misc.md",
+    appbar: "04-widgets/misc.md",
+    conditionalbuilder: "04-widgets/misc.md",
+    widget: "04-widgets/README.md",
+    widgets: "04-widgets/README.md",
+    // Non-widget topics
+    actions: "05-actions.md",
+    action: "05-actions.md",
+    trigger: "05-actions.md",
+    navigate: "05-actions.md",
+    navigation: "05-actions.md",
+    ontap: "05-actions.md",
+    variables: "06-variables.md",
+    variable: "06-variables.md",
+    binding: "06-variables.md",
+    "data-binding": "06-variables.md",
+    data: "07-data.md",
+    collections: "07-data.md",
+    firestore: "07-data.md",
+    api: "07-data.md",
+    custom: "08-custom-code.md",
+    dart: "08-custom-code.md",
+    "custom-code": "08-custom-code.md",
+    theme: "09-theming.md",
+    theming: "09-theming.md",
+    color: "09-theming.md",
+    colors: "09-theming.md",
+    font: "09-theming.md",
+    typography: "09-theming.md",
+    editing: "10-editing-guide.md",
+    workflow: "10-editing-guide.md",
+    "editing-guide": "10-editing-guide.md",
+    push: "10-editing-guide.md",
+    overview: "00-overview.md",
+    structure: "00-overview.md",
+    "project-files": "01-project-files.md",
+    config: "01-project-files.md",
+    settings: "01-project-files.md",
+    pages: "02-pages.md",
+    page: "02-pages.md",
+    scaffold: "02-pages.md",
+    components: "03-components.md",
+    component: "03-components.md",
+    createcomponent: "03-components.md",
+    refactor: "03-components.md",
+    refactoring: "03-components.md",
+    isdummyroot: "03-components.md",
+    dummyroot: "03-components.md",
+    componentclasskeyref: "03-components.md",
+    parametervalues: "03-components.md",
+    callback: "03-components.md",
+    executecallbackaction: "03-components.md",
+    // Internationalization
+    translation: "01-project-files.md",
+    translations: "01-project-files.md",
+    i18n: "01-project-files.md",
+    localization: "01-project-files.md",
+    translatabletext: "01-project-files.md",
+    languages: "01-project-files.md",
+    // Universal patterns
+    inputvalue: "README.md",
+    mostrecentinputvalue: "README.md",
+    padding: "README.md",
+    "border-radius": "README.md",
+};
+/** List all doc files recursively. */
+export function listDocFiles(dir, prefix = "") {
+    const results = [];
+    if (!fs.existsSync(dir))
+        return results;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            results.push(...listDocFiles(path.join(dir, entry.name), relPath));
+        }
+        else if (entry.name.endsWith(".md")) {
+            results.push(relPath);
+        }
+    }
+    return results;
+}
+/** Read a doc file. Returns null if not found. */
+export function readDoc(relPath) {
+    const filePath = path.join(DOCS_DIR, relPath);
+    if (!fs.existsSync(filePath))
+        return null;
+    return fs.readFileSync(filePath, "utf-8");
+}

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

@@ -0,0 +1,166 @@
+# 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 |
+| `theme/color-scheme` | Full color palette: core, background, text, accent, semantic colors with dark mode variants |
+| `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` | Platform permission declarations (CAMERA, LOCATION, etc.) — abstraction layer that FF maps to AndroidManifest.xml and Info.plist at build time |
+| `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 |
+| `custom-file/id-<TYPE>` | Custom file configs for native platform files. Known types: `MAIN` (main.dart startup actions), `ANDROID_MANIFEST` (XML injection hooks for AndroidManifest.xml), `INFO_PLIST` (plist property injection for Info.plist), `ENTITLEMENTS` (iOS capability entitlements for Runner.entitlements), `APP_DELEGATE` (Swift code injection for AppDelegate.swift), `PROGUARD` (ProGuard rule injection for proguard-rules.pro), `BUILD_GRADLE` (Gradle plugin/dependency/repository injection for build.gradle). Only appear after enabled in FF editor. Sub-file `custom-file/id-<TYPE>/custom-file-code.dart` contains generated source. |
+| `environment-settings` | Per-environment configuration values (API URLs, keys) |
+| `dependencies` | FlutterFlow library package dependencies |
+| `custom-code-dependencies` | Dart/Flutter pub dependencies for custom code |
+| `supabase` | Supabase connection config and database schema |
+| `firebase-analytics` | Firebase Analytics settings |
+| `firebase-crashlytics` | Firebase Crashlytics settings |
+| `firebase-performance-monitoring` | Firebase Performance Monitoring settings |
+| `firebase-app-check` | Firebase App Check configuration and debug token |
+| `firebase-remote-config` | Firebase Remote Config — field definitions with default values |
+| `firestore-settings` | Firestore security rules (per-collection CRUD permissions), storage rules, validation hashes |
+| `push-notifications` | Push notification configuration |
+| `google-maps` | Google Maps API keys per platform |
+| `ad-mob` | AdMob advertising configuration |
+| `algolia` | Algolia search integration — app ID, API key, indexed collections |
+| `app-assets` | App icon, splash screen, error image settings |
+| `platforms` | Platform enablement flags (web, etc.) |
+| `mobile-deployment` | Codemagic CI/CD settings — App Store Connect credentials, build version/number, Play Store track, signing config |
+| `web-publishing` | Web platform settings — SEO description, page title, status bar color, orientation |
+| `library-values` | Values passed to FlutterFlow library dependencies |
+| `library-configurations/id-<projectId>` | Route overrides for library pages |
+| `download-code-settings` | Code download/GitHub push settings |
+| `tests` | FlutterFlow test runner configuration |
+| `app-query-cache` | Named database request cache managers |
+| `date-picker` | Date picker style toggle (legacy vs modern Material date picker) |
+| `material-theme` | Material Design version toggle (Material 2 vs Material 3) |
+| `storyboard` | Editor-only page positions on the FF storyboard canvas (no functional impact) |
+| `miscellaneous` | Misc app-level settings and feature flags |
+
+---
+
+## 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.