flutterflow-mcp 0.3.0 → 0.3.2

package/README.md

@@ -2,21 +2,71 @@
 
 MCP server for the FlutterFlow Project API. Enables AI-assisted FlutterFlow development through Claude and other MCP-compatible clients.
 
+## What This MCP Does Best
+
+This MCP excels at **reading, exploring, and understanding** your FlutterFlow projects. Here's what it's great at:
+
+- **Project exploration** — Browse your projects, pages, components, and file structure
+- **Understanding functionality** — Get clear summaries of what a page or component does, including its widget tree, actions, parameters, and state
+- **Tracing usage** — Find everywhere a component is used, or every navigation action that leads to a page
+- **Inspecting configuration** — View theme settings, API endpoints, data models, custom code, app state, integrations, and more
+- **Searching** — Search project files by keyword, prefix, or regex to find exactly what you need
+- **YAML reference** — Built-in documentation for FlutterFlow's YAML schema, so your AI assistant can understand and generate valid YAML
+- **Guided editing** — A workflow guide (`get_editing_guide`) that walks through the correct steps before making any YAML changes
+
+> **In short:** Think of it as giving your AI assistant full read access to your FlutterFlow project, plus careful write access when needed.
+
 ## Quick Start
 
-### 1. Get your FlutterFlow API token
+### 1. Get Your FlutterFlow API Token
+
+You need a FlutterFlow API token to authenticate. Here's how to get one:
 
-Go to **FlutterFlow > Account Settings > API Token** and copy your token.
+1. Open [FlutterFlow](https://app.flutterflow.io/) and log in
+2. Click your **profile picture** (bottom-left corner)
+3. Go to **Account Settings**
+4. Scroll to the **API Token** section
+5. Click **Copy** to copy your token
 
-### 2. Add to your MCP client
+> **Note:** The API token requires a **paid FlutterFlow subscription** (Standard plan or above). Free-tier accounts do not have API access.
 
-**Claude Code:**
+### 2. Add to Your MCP Client
+
+Choose your AI client below and follow the setup instructions.
+
+<details>
+<summary><strong>Claude Code (CLI)</strong></summary>
+
+Run this command to add the MCP server:
 
 ```bash
-claude mcp add flutterflow -- npx -y flutterflow-mcp
+claude mcp add flutterflow -e FLUTTERFLOW_API_TOKEN=your_token_here -- npx -y flutterflow-mcp
+```
+
+Replace `your_token_here` with the token you copied in step 1.
+
+This adds the server to your project's `.claude/settings.json`. You can also manually edit the config:
+
+```json
+{
+  "mcpServers": {
+    "flutterflow": {
+      "command": "npx",
+      "args": ["-y", "flutterflow-mcp"],
+      "env": {
+        "FLUTTERFLOW_API_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
 ```
 
-Then set your token in the MCP config (`~/.claude/settings.json` or project `.claude/settings.json`):
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Open **Settings > Developer > Edit Config** and add:
 
 ```json
 {
@@ -32,9 +82,14 @@ Then set your token in the MCP config (`~/.claude/settings.json` or project `.cl
 }
 ```
 
-**Other MCP clients (Cursor, Windsurf, etc.):**
+Replace `your_token_here` with your token. Restart Claude Desktop after saving.
 
-Add to your MCP configuration:
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Open **Settings > MCP** and add a new server with this configuration:
 
 ```json
 {
@@ -50,27 +105,107 @@ Add to your MCP configuration:
 }
 ```
 
-### 3. Start building
+</details>
 
-Ask your AI assistant to list your FlutterFlow projects, inspect pages, or modify widgets — it handles the rest.
+<details>
+<summary><strong>Windsurf / Other MCP Clients</strong></summary>
+
+Add the following to your MCP configuration file (check your client's docs for the exact location):
+
+```json
+{
+  "mcpServers": {
+    "flutterflow": {
+      "command": "npx",
+      "args": ["-y", "flutterflow-mcp"],
+      "env": {
+        "FLUTTERFLOW_API_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+### 3. Start Building
+
+Ask your AI assistant to list your FlutterFlow projects, inspect pages, or explore your app — it handles the rest.
+
+**Example prompts to get started:**
+- *"List my FlutterFlow projects"*
+- *"Show me all the pages in project X"*
+- *"What does the HomePage do? Walk me through its widget tree"*
+- *"Where is the PaywallCard component used?"*
+- *"What API endpoints are configured?"*
+- *"Show me the theme colors"*
+
+## Important: Limitations and Cautions
+
+### Editing Requires Care
+
+While this MCP can push YAML changes to your FlutterFlow project, **edits should be treated with caution**:
+
+- **Always validate first** — Use `validate_yaml` before every `update_project_yaml` call. Validation catches syntax errors but cannot catch all semantic mistakes.
+- **Review before pushing** — Ask your AI assistant to show you the exact YAML changes before they are pushed. Understand what will change.
+- **FlutterFlow has no undo for API changes** — Changes pushed through the API are applied immediately. There is no built-in undo button for API-pushed edits. You can revert using FlutterFlow's version history, but it's better to prevent bad edits than to fix them.
+- **Start with read-only exploration** — Get comfortable using the read tools (`get_page_summary`, `find_component_usages`, etc.) before attempting edits.
+- **Node-level edits are safer** — Edit individual widgets via node-level file keys instead of replacing entire page YAML. This reduces the blast radius of mistakes.
+
+### Known Technical Limitations
+
+- **Large pages may fail** — Some large pages can exceed buffer limits during ZIP decode. Use node-level sub-files for these pages instead.
+- **Full project YAML fetch can be slow** — Fetching all YAML without a `fileName` parameter may exceed buffer/transport limits on large projects. Use `sync_project` to cache everything locally first.
+- **Rate limiting** — `list_pages` batches requests 5 at a time to avoid FlutterFlow API rate limits. Pages that fail to fetch still appear with scaffold ID and folder info.
+- **Cache staleness** — Cache-based tools (`get_page_summary`, `get_component_summary`, etc.) depend on a local cache created by `sync_project`. If your project has been edited in FlutterFlow since the last sync, re-run `sync_project` with `force: true` to refresh.
+- **No real-time sync** — This is a snapshot-based tool. It reads and writes YAML at a point in time. It does not watch for live changes in the FlutterFlow editor.
 
 ## Tools
 
+### Discovery and Exploration
+
 | Tool | Description |
 |------|-------------|
-| `list_projects` | List all FlutterFlow projects |
-| `list_project_files` | List YAML files in a project |
-| `list_pages` | List all pages with names, scaffold IDs, and folders |
-| `get_page_by_name` | Fetch a page by human-readable name |
-| `get_project_yaml` | Download project YAML files |
-| `validate_yaml` | Validate YAML before pushing |
-| `update_project_yaml` | Push YAML changes to a project |
-| `sync_project` | Bulk download all YAML to local cache |
-| `get_page_summary` | Quick page overview from cache (widget tree, actions, params) |
-| `get_component_summary` | Quick component overview from cache |
-| `find_component_usages` | Find all pages/components using a given component |
+| `list_projects` | List all FlutterFlow projects for your account |
+| `list_project_files` | List YAML file keys in a project (supports prefix filter) |
+| `list_pages` | List all pages with human-readable names, scaffold IDs, and folders |
+| `search_project_files` | Search file keys by keyword, prefix, or regex |
+| `sync_project` | Bulk download all project YAML to local cache for fast offline reads |
+
+### Reading and Understanding
+
+| Tool | Description |
+|------|-------------|
+| `get_page_by_name` | Fetch a page by its human-readable name |
+| `get_project_yaml` | Download specific YAML files by file key |
+| `get_page_summary` | Quick page overview from cache — widget tree, actions, params, state |
+| `get_component_summary` | Quick component overview from cache — widget tree, actions, params |
+| `find_component_usages` | Find all pages and components where a given component is used |
 | `find_page_navigations` | Find all actions that navigate to a given page |
+
+### Project Configuration
+
+| Tool | Description |
+|------|-------------|
+| `get_theme` | Theme colors, typography, breakpoints, and widget defaults |
+| `get_app_state` | App state variables, constants, and environment settings |
+| `get_api_endpoints` | API endpoint definitions — method, URL, variables, headers, response |
+| `get_data_models` | Data structs, enums, Firestore collections, and Supabase tables |
+| `get_custom_code` | Custom actions, functions, widgets, AI agents, and app-action components |
+| `get_general_settings` | App Details, App Assets, Nav Bar & App Bar settings |
+| `get_project_setup` | Firebase, Languages, Platforms, Permissions, Dependencies |
+| `get_app_settings` | Authentication, Push Notifications, Mobile/Web Deployment |
+| `get_in_app_purchases` | Stripe, Braintree, RevenueCat, Razorpay configuration |
+| `get_integrations` | Supabase, SQLite, GitHub, Algolia, Google Maps, AdMob, and more |
+
+### Editing
+
+| Tool | Description |
+|------|-------------|
+| `get_editing_guide` | Get the recommended workflow and docs for an editing task — **call this before modifying any YAML** |
 | `get_yaml_docs` | Search/retrieve FlutterFlow YAML reference docs by topic or file |
+| `validate_yaml` | Validate YAML content before pushing — **always call before `update_project_yaml`** |
+| `update_project_yaml` | Push YAML changes to a project |
 
 ## Resources
 

package/build/tools/find-component-usages.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta, listCachedKeys, } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter, listCachedKeys, } from "../utils/cache.js";
 import { resolveComponent } from "./get-component-summary.js";
 import { batchProcess } from "../utils/batch-process.js";
 // ---------------------------------------------------------------------------
@@ -210,7 +210,7 @@ export function registerFindComponentUsagesTool(server) {
             }
         }
         return {
-            content: [{ type: "text", text: lines.join("\n") }],
+            content: [{ type: "text", text: lines.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/find-page-navigations.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta, listCachedKeys, } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter, listCachedKeys, } from "../utils/cache.js";
 import { resolvePage } from "./get-page-summary.js";
 import { batchProcess } from "../utils/batch-process.js";
 // ---------------------------------------------------------------------------
@@ -214,7 +214,7 @@ export function registerFindPageNavigationsTool(server) {
             }
         }
         return {
-            content: [{ type: "text", text: lines.join("\n") }],
+            content: [{ type: "text", text: lines.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-api-endpoints.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta, listCachedKeys } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter, listCachedKeys } from "../utils/cache.js";
 import { batchProcess } from "../utils/batch-process.js";
 function parseEndpoint(content) {
     const doc = YAML.parse(content);
@@ -120,7 +120,7 @@ export function registerGetApiEndpointsTool(server) {
             endpoints = filtered;
         }
         return {
-            content: [{ type: "text", text: formatEndpoints(endpoints) }],
+            content: [{ type: "text", text: formatEndpoints(endpoints) + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-app-settings.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter } from "../utils/cache.js";
 async function resolvePageName(projectId, scaffoldId) {
     const content = await cacheRead(projectId, `page/id-${scaffoldId}`);
     if (!content)
@@ -163,7 +163,7 @@ export function registerGetAppSettingsTool(server) {
             sections.push(`(not configured)`);
         }
         return {
-            content: [{ type: "text", text: sections.join("\n") }],
+            content: [{ type: "text", text: sections.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-app-state.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter } from "../utils/cache.js";
 import { resolveDataType } from "../utils/resolve-data-type.js";
 export function registerGetAppStateTool(server) {
     server.tool("get_app_state", "Get app state variables, constants, and environment settings from local cache. No API calls. Run sync_project first if not cached.", {
@@ -90,7 +90,7 @@ export function registerGetAppStateTool(server) {
             }
         }
         return {
-            content: [{ type: "text", text: sections.join("\n") }],
+            content: [{ type: "text", text: sections.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-component-summary.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta, listCachedKeys, } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter, listCachedKeys, } from "../utils/cache.js";
 import { parseTreeOutline } from "../utils/page-summary/tree-walker.js";
 import { extractNodeInfo } from "../utils/page-summary/node-extractor.js";
 import { summarizeTriggers } from "../utils/page-summary/action-summarizer.js";
@@ -189,7 +189,7 @@ export function registerGetComponentSummaryTool(server) {
         // Format output
         const summary = formatComponentSummary(componentMeta, enrichedTree);
         return {
-            content: [{ type: "text", text: summary }],
+            content: [{ type: "text", text: summary + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-custom-code.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta, listCachedKeys } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter, listCachedKeys } from "../utils/cache.js";
 import { batchProcess } from "../utils/batch-process.js";
 import { resolveDataType } from "../utils/resolve-data-type.js";
 // ---------------------------------------------------------------------------
@@ -374,7 +374,7 @@ export function registerGetCustomCodeTool(server) {
         }
         const output = `# Custom Code\n\n${sections.join("\n\n")}`;
         return {
-            content: [{ type: "text", text: output }],
+            content: [{ type: "text", text: output + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-data-models.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta, listCachedKeys } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter, listCachedKeys } from "../utils/cache.js";
 import { batchProcess } from "../utils/batch-process.js";
 import { resolveDataType } from "../utils/resolve-data-type.js";
 async function readStructs(projectId, nameFilter) {
@@ -260,7 +260,7 @@ export function registerGetDataModelsTool(server) {
         }
         const output = formatOutput(structs, enums, collections, supabaseTables, name);
         return {
-            content: [{ type: "text", text: output }],
+            content: [{ type: "text", text: output + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-general-settings.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter } from "../utils/cache.js";
 async function resolvePageName(projectId, scaffoldId) {
     const content = await cacheRead(projectId, `page/id-${scaffoldId}`);
     if (!content)
@@ -110,7 +110,7 @@ export function registerGetGeneralSettingsTool(server) {
             sections.push(`\n## Nav Bar & App Bar`, `(not configured)`);
         }
         return {
-            content: [{ type: "text", text: sections.join("\n") }],
+            content: [{ type: "text", text: sections.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-in-app-purchases.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter } from "../utils/cache.js";
 const PROVIDERS = [
     { key: "stripe", label: "Stripe" },
     { key: "braintree", label: "Braintree" },
@@ -45,7 +45,7 @@ export function registerGetInAppPurchasesTool(server) {
             }
         }
         return {
-            content: [{ type: "text", text: sections.join("\n") }],
+            content: [{ type: "text", text: sections.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-integrations.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter } from "../utils/cache.js";
 /**
  * Fields that should never be output — API keys, secrets, tokens, etc.
  * Only IDs and non-sensitive configuration are shown.
@@ -131,7 +131,7 @@ export function registerGetIntegrationsTool(server) {
             sections.push(lines.join("\n"));
         }
         return {
-            content: [{ type: "text", text: sections.join("\n") }],
+            content: [{ type: "text", text: sections.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-page-summary.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta, listCachedKeys, } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter, listCachedKeys, } from "../utils/cache.js";
 import { parseFolderMapping } from "../utils/parse-folders.js";
 import { parseTreeOutline } from "../utils/page-summary/tree-walker.js";
 import { extractNodeInfo } from "../utils/page-summary/node-extractor.js";
@@ -199,7 +199,7 @@ export function registerGetPageSummaryTool(server) {
         // Format output
         const summary = formatPageSummary(pageMeta, enrichedTree);
         return {
-            content: [{ type: "text", text: summary }],
+            content: [{ type: "text", text: summary + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-project-setup.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter } from "../utils/cache.js";
 import { resolveDataType } from "../utils/resolve-data-type.js";
 export function registerGetProjectSetupTool(server) {
     server.tool("get_project_setup", "Get Project Setup settings — Firebase services, Languages, Platforms, Permissions, Project Dependencies, Dev Environments. Mirrors the FlutterFlow 'Project Setup' settings section. Cache-based, no API calls. Run sync_project first.", {
@@ -206,7 +206,7 @@ export function registerGetProjectSetupTool(server) {
             sections.push(`(not configured)`);
         }
         return {
-            content: [{ type: "text", text: sections.join("\n") }],
+            content: [{ type: "text", text: sections.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-theme.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter } from "../utils/cache.js";
 function argbToHex(argbStr) {
     const n = parseInt(argbStr, 10);
     if (isNaN(n))
@@ -122,7 +122,7 @@ export function registerGetThemeTool(server) {
             }
         }
         return {
-            content: [{ type: "text", text: sections.join("\n") }],
+            content: [{ type: "text", text: sections.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/list-files.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { listCachedKeys, cacheMeta } from "../utils/cache.js";
+import { listCachedKeys, cacheMeta, cacheAgeFooter } from "../utils/cache.js";
 export function registerListFilesTool(server, client) {
     server.tool("list_project_files", "List all YAML file names in a FlutterFlow project. Supports optional prefix filter (e.g. 'page/', 'component/') to narrow results.", {
         projectId: z.string().describe("The FlutterFlow project ID"),
@@ -15,7 +15,7 @@ export function registerListFilesTool(server, client) {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify({ value: { file_names: keys }, source: "cache", syncedAt: meta.lastSyncedAt }, null, 2),
+                        text: JSON.stringify({ value: { file_names: keys }, source: "cache", syncedAt: meta.lastSyncedAt }, null, 2) + cacheAgeFooter(meta),
                     },
                 ],
             };

package/build/tools/search-project-files.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { cacheMeta, listCachedKeys } from "../utils/cache.js";
+import { cacheMeta, listCachedKeys, cacheAgeFooter } from "../utils/cache.js";
 const MAX_RESULTS = 100;
 export function registerSearchProjectFilesTool(server) {
     server.tool("search_project_files", "Search cached project file keys by keyword, prefix, or regex. Returns matching file keys for use with get_project_yaml. Cache-only, no API calls. Run sync_project first.", {
@@ -63,7 +63,7 @@ export function registerSearchProjectFilesTool(server) {
             lines.push(`- ${key}`);
         }
         return {
-            content: [{ type: "text", text: lines.join("\n") }],
+            content: [{ type: "text", text: lines.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/utils/cache.d.ts

@@ -51,3 +51,8 @@ export declare function cacheWriteMeta(projectId: string, meta: CacheMeta): Prom
  * the path relative to the project cache dir.
  */
 export declare function listCachedKeys(projectId: string, prefix?: string): Promise<string[]>;
+/**
+ * Format a human-readable footer indicating cache age.
+ * Appended to cache-based tool responses so the AI can judge staleness.
+ */
+export declare function cacheAgeFooter(meta: CacheMeta): string;

package/build/utils/cache.js

@@ -148,6 +148,28 @@ export async function listCachedKeys(projectId, prefix) {
     return yamlKeys;
 }
 // ---------------------------------------------------------------------------
+// Cache age footer
+// ---------------------------------------------------------------------------
+/**
+ * Format a human-readable footer indicating cache age.
+ * Appended to cache-based tool responses so the AI can judge staleness.
+ */
+export function cacheAgeFooter(meta) {
+    const syncedAt = new Date(meta.lastSyncedAt);
+    const diffMs = Date.now() - syncedAt.getTime();
+    const diffMin = Math.floor(diffMs / 60_000);
+    let ago;
+    if (diffMin < 1)
+        ago = "just now";
+    else if (diffMin < 60)
+        ago = `${diffMin} min ago`;
+    else if (diffMin < 1440)
+        ago = `${Math.floor(diffMin / 60)}h ${diffMin % 60}m ago`;
+    else
+        ago = `${Math.floor(diffMin / 1440)}d ago`;
+    return `\n\n---\n_Synced: ${meta.lastSyncedAt} (${ago}). Call sync_project to refresh._`;
+}
+// ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flutterflow-mcp",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "MCP server for the FlutterFlow Project API — AI-assisted FlutterFlow development through Claude and other MCP-compatible clients",
   "type": "module",
   "main": "build/index.js",