flutterflow-mcp 0.2.3 → 0.3.0

package/build/tools/validate-yaml.js

@@ -1,6 +1,11 @@
 import { z } from "zod";
+/** Extract widget type from a node-level fileKey, e.g. "Button" from "node/id-Button_xyz" */
+function extractWidgetTypeFromFileKey(fileKey) {
+    const match = fileKey.match(/node\/id-([A-Z][a-zA-Z]+)_/);
+    return match ? match[1] : null;
+}
 export function registerValidateYamlTool(server, client) {
-    server.tool("validate_yaml", "Validate YAML content before pushing changes to a FlutterFlow project. Always call this before update_project_yaml.", {
+    server.tool("validate_yaml", "Validate YAML content before pushing changes to a FlutterFlow project. Always call this before update_project_yaml. Tip: Call get_editing_guide or get_yaml_docs BEFORE writing YAML to understand the correct schema and field names. Validation catches syntax errors but not semantic mistakes.", {
         projectId: z.string().describe("The FlutterFlow project ID"),
         fileKey: z
             .string()
@@ -10,11 +15,23 @@ export function registerValidateYamlTool(server, client) {
             .describe("Pass YAML content as a normal multi-line string."),
     }, async ({ projectId, fileKey, fileContent }) => {
         const result = await client.validateProjectYaml(projectId, fileKey, fileContent);
+        let text = JSON.stringify(result, null, 2);
+        // Add doc hint on validation failure
+        const isFailure = result && typeof result === "object" && result.valid === false;
+        if (isFailure) {
+            const widgetType = extractWidgetTypeFromFileKey(fileKey);
+            if (widgetType) {
+                text += `\n\nHint: Use get_yaml_docs(topic: "${widgetType}") to look up the correct field schema for ${widgetType} widgets.`;
+            }
+            else {
+                text += `\n\nHint: Use get_yaml_docs to look up the correct YAML schema for the file you're editing.`;
+            }
+        }
         return {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify(result, null, 2),
+                    text,
                 },
             ],
         };

package/build/utils/batch-process.d.ts

@@ -0,0 +1,2 @@
+/** Batch-process items in groups to avoid overwhelming the file system. */
+export declare function batchProcess<T, R>(items: T[], batchSize: number, fn: (item: T) => Promise<R>): Promise<R[]>;

package/build/utils/batch-process.js

@@ -0,0 +1,10 @@
+/** Batch-process items in groups to avoid overwhelming the file system. */
+export async function batchProcess(items, batchSize, fn) {
+    const results = [];
+    for (let i = 0; i < items.length; i += batchSize) {
+        const batch = items.slice(i, i + batchSize);
+        const batchResults = await Promise.all(batch.map(fn));
+        results.push(...batchResults);
+    }
+    return results;
+}

package/build/utils/cache.d.ts

@@ -24,6 +24,11 @@ export declare function cacheWrite(projectId: string, fileKey: string, content:
  * Delete a single cached file. No-op if the file does not exist.
  */
 export declare function cacheInvalidate(projectId: string, fileKey: string): Promise<void>;
+/**
+ * Delete the entire cache directory for a project, removing all cached files
+ * and metadata. No-op if the directory does not exist.
+ */
+export declare function cacheClear(projectId: string): Promise<void>;
 /**
  * Write multiple YAML entries to the cache in one call.
  * Returns the number of entries written.

package/build/utils/cache.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, writeFile, unlink, readdir } from "node:fs/promises";
+import { mkdir, readFile, writeFile, unlink, readdir, rm } from "node:fs/promises";
 import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 // ---------------------------------------------------------------------------
@@ -73,6 +73,21 @@ export async function cacheInvalidate(projectId, fileKey) {
         throw err;
     }
 }
+/**
+ * Delete the entire cache directory for a project, removing all cached files
+ * and metadata. No-op if the directory does not exist.
+ */
+export async function cacheClear(projectId) {
+    try {
+        await rm(cacheDir(projectId), { recursive: true, force: true });
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === "ENOENT") {
+            return; // already gone — no-op
+        }
+        throw err;
+    }
+}
 /**
  * Write multiple YAML entries to the cache in one call.
  * Returns the number of entries written.

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,115 @@
+/**
+ * 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",
+    // 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

@@ -11,13 +11,14 @@ Every FlutterFlow project is a collection of YAML files accessed via file keys.
 | `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` | Permission definitions and role-based access rules |
+| `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 |
@@ -35,6 +36,34 @@ Every FlutterFlow project is a collection of YAML files accessed via file keys.
 | `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), `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-MAIN/custom-file-code.dart` contains generated Dart 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 |
 
 ---