flutterflow-mcp 0.2.5 → 0.3.1

package/build/index.js

@@ -25,8 +25,14 @@ import { registerGetAppStateTool } from "./tools/get-app-state.js";
 import { registerGetApiEndpointsTool } from "./tools/get-api-endpoints.js";
 import { registerGetDataModelsTool } from "./tools/get-data-models.js";
 import { registerGetCustomCodeTool } from "./tools/get-custom-code.js";
-import { registerGetProjectConfigTool } from "./tools/get-project-config.js";
 import { registerGetThemeTool } from "./tools/get-theme.js";
+import { registerGetEditingGuideTool } from "./tools/get-editing-guide.js";
+import { registerSearchProjectFilesTool } from "./tools/search-project-files.js";
+import { registerGetGeneralSettingsTool } from "./tools/get-general-settings.js";
+import { registerGetProjectSetupTool } from "./tools/get-project-setup.js";
+import { registerGetAppSettingsTool } from "./tools/get-app-settings.js";
+import { registerGetInAppPurchasesTool } from "./tools/get-in-app-purchases.js";
+import { registerGetIntegrationsTool } from "./tools/get-integrations.js";
 const server = new McpServer({
     name: "ff-mcp",
     version: "0.1.0",
@@ -50,8 +56,14 @@ registerGetAppStateTool(server);
 registerGetApiEndpointsTool(server);
 registerGetDataModelsTool(server);
 registerGetCustomCodeTool(server);
-registerGetProjectConfigTool(server);
 registerGetThemeTool(server);
+registerGetEditingGuideTool(server);
+registerSearchProjectFilesTool(server);
+registerGetGeneralSettingsTool(server);
+registerGetProjectSetupTool(server);
+registerGetAppSettingsTool(server);
+registerGetInAppPurchasesTool(server);
+registerGetIntegrationsTool(server);
 // Register resources
 registerResources(server, client);
 registerDocsResources(server);

package/build/prompts/generate-page.js

@@ -16,14 +16,15 @@ export function registerGeneratePagePrompt(server) {
 ## Instructions
 
 1. First, use the list_project_files tool with projectId "${projectId}" to understand the existing project structure.
-2. Then, use get_project_yaml to read a few existing pages to understand the YAML schema and conventions used in this project.
-3. Based on the following description, generate valid FlutterFlow YAML for a new page:
+2. Use \`get_editing_guide\` with a description of the page you want to create to get the correct YAML schemas, workflow steps, and critical rules.
+3. Then, use get_project_yaml to read a few existing pages to understand the YAML schema and conventions used in this project.
+4. Based on the following description, generate valid FlutterFlow YAML for a new page:
 
 **Page Description:** ${description}
 
-4. Use validate_yaml to check your generated YAML is valid.
-5. If validation passes, use update_project_yaml to push the new page to the project.
-6. If validation fails, fix the errors and try again.
+5. Use validate_yaml to check your generated YAML is valid.
+6. If validation passes, use update_project_yaml to push the new page to the project.
+7. If validation fails, fix the errors and try again.
 
 ## Important
 - Follow the exact YAML structure you observed in existing pages.

package/build/prompts/modify-component.js

@@ -19,14 +19,15 @@ export function registerModifyComponentPrompt(server) {
 ## Instructions
 
 1. Use get_project_yaml with projectId "${projectId}" and fileName "${fileName}" to read the current component YAML.
-2. Understand the current structure and widget tree.
-3. Apply the following changes:
+2. Use \`get_editing_guide\` with a description of the changes you want to make to get the correct YAML schemas and critical rules.
+3. Understand the current structure and widget tree.
+4. Apply the following changes:
 
 **Requested Changes:** ${changes}
 
-4. Use validate_yaml to verify your modified YAML is valid.
-5. If validation passes, use update_project_yaml to push the changes.
-6. If validation fails, fix the errors and try again.
+5. Use validate_yaml to verify your modified YAML is valid.
+6. If validation passes, use update_project_yaml to push the changes.
+7. If validation fails, fix the errors and try again.
 
 ## Important
 - Preserve all existing structure you are not modifying.

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.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerGetAppSettingsTool(server: McpServer): void;

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

@@ -0,0 +1,169 @@
+import { z } from "zod";
+import YAML from "yaml";
+import { cacheRead, cacheMeta, cacheAgeFooter } from "../utils/cache.js";
+async function resolvePageName(projectId, scaffoldId) {
+    const content = await cacheRead(projectId, `page/id-${scaffoldId}`);
+    if (!content)
+        return scaffoldId;
+    const nameMatch = content.match(/^name:\s*(.+)$/m);
+    return nameMatch ? nameMatch[1].trim() : scaffoldId;
+}
+export function registerGetAppSettingsTool(server) {
+    server.tool("get_app_settings", "Get App Settings — Authentication, Push Notifications, Mobile Deployment (version, build, stores), Web Deployment (SEO, title). Mirrors the FlutterFlow 'App Settings' section. Cache-based, no API calls. Run sync_project first.", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+    }, async ({ projectId }) => {
+        const meta = await cacheMeta(projectId);
+        if (!meta) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No cache found for project "${projectId}". Run sync_project first.`,
+                    },
+                ],
+            };
+        }
+        const [authRaw, appDetailsRaw, pushRaw, mobileRaw, webRaw] = await Promise.all([
+            cacheRead(projectId, "authentication"),
+            cacheRead(projectId, "app-details"),
+            cacheRead(projectId, "push-notifications"),
+            cacheRead(projectId, "mobile-deployment"),
+            cacheRead(projectId, "web-publishing"),
+        ]);
+        const sections = ["# App Settings"];
+        // --- Authentication ---
+        sections.push(`\n## Authentication`);
+        if (authRaw) {
+            const auth = YAML.parse(authRaw);
+            const active = auth.active === true;
+            if (active) {
+                let provider = "Unknown";
+                const firebaseConfigs = auth.firebaseConfigFileInfos;
+                const supabase = auth.supabase;
+                if (firebaseConfigs && firebaseConfigs.length > 0) {
+                    provider = "Firebase";
+                }
+                else if (supabase && Object.keys(supabase).length > 0) {
+                    provider = "Supabase";
+                }
+                sections.push(`Status: Active`, `Provider: ${provider}`);
+            }
+            else {
+                sections.push(`Status: Inactive`);
+            }
+        }
+        else {
+            sections.push(`Status: Inactive`);
+        }
+        // Auth page info from app-details
+        if (appDetailsRaw) {
+            const appDetails = YAML.parse(appDetailsRaw);
+            const authPageInfo = appDetails.authPageInfo;
+            if (authPageInfo) {
+                const homeRef = authPageInfo.homePageNodeKeyRef?.key;
+                const signInRef = authPageInfo.signInPageNodeKeyRef?.key;
+                if (homeRef) {
+                    const name = await resolvePageName(projectId, homeRef);
+                    sections.push(`Home page: ${name} (${homeRef})`);
+                }
+                if (signInRef) {
+                    const name = await resolvePageName(projectId, signInRef);
+                    sections.push(`Sign-in page: ${name} (${signInRef})`);
+                }
+            }
+        }
+        // --- Push Notifications ---
+        sections.push(`\n## Push Notifications`);
+        if (pushRaw) {
+            const push = YAML.parse(pushRaw);
+            const enabled = push.enabled === true;
+            const allowScheduled = push.allowScheduledNotifications === true;
+            const autoPrompt = push.autoPromptUsersForNotificationsPermission === true;
+            sections.push(`Enabled: ${enabled ? "Yes" : "No"}`, `Scheduled notifications: ${allowScheduled ? "Yes" : "No"}`, `Auto-prompt permission: ${autoPrompt ? "Yes" : "No"}`);
+            const lastNotif = push.lastNotificationSent;
+            if (lastNotif) {
+                const title = lastNotif.notificationTitle || "(untitled)";
+                const status = lastNotif.status || "unknown";
+                sections.push(`Last notification: "${title}" (${status})`);
+            }
+        }
+        else {
+            sections.push(`(not configured)`);
+        }
+        // --- Mobile Deployment ---
+        sections.push(`\n## Mobile Deployment`);
+        if (mobileRaw) {
+            const mobile = YAML.parse(mobileRaw);
+            const settingsMap = mobile.codemagicSettingsMap;
+            if (settingsMap && Object.keys(settingsMap).length > 0) {
+                // Prefer PROD, fall back to first key
+                const envKey = settingsMap.PROD
+                    ? "PROD"
+                    : Object.keys(settingsMap)[0];
+                const envSettings = settingsMap[envKey];
+                sections.push(`Environment: ${envKey}`);
+                // Build version
+                const buildVersion = envSettings.buildVersion;
+                if (buildVersion) {
+                    if (buildVersion.buildVersion) {
+                        sections.push(`Version: ${buildVersion.buildVersion}`);
+                    }
+                    if (buildVersion.buildNumber != null) {
+                        sections.push(`Build number: ${buildVersion.buildNumber}`);
+                    }
+                    if (buildVersion.lastSubmitted) {
+                        sections.push(`Last submitted: ${buildVersion.lastSubmitted}`);
+                    }
+                }
+                // Play Store
+                const playStore = envSettings.playStoreSettings;
+                if (playStore?.playTrack) {
+                    sections.push(`Play Store track: ${playStore.playTrack}`);
+                }
+                // App Store — NEVER output private keys
+                const appStore = envSettings.appStoreSettings;
+                if (appStore?.ascAppId) {
+                    sections.push(`App Store ID: ${appStore.ascAppId}`);
+                }
+            }
+            else {
+                sections.push(`(not configured)`);
+            }
+        }
+        else {
+            sections.push(`(not configured)`);
+        }
+        // --- Web Deployment ---
+        sections.push(`\n## Web Deployment`);
+        if (webRaw) {
+            const web = YAML.parse(webRaw);
+            const webSettings = web.webSettings;
+            if (webSettings && Object.keys(webSettings).length > 0) {
+                // Prefer PROD, fall back to first key
+                const envKey = webSettings.PROD
+                    ? "PROD"
+                    : Object.keys(webSettings)[0];
+                const envData = webSettings[envKey];
+                sections.push(`Environment: ${envKey}`);
+                if (envData.pageTitle) {
+                    sections.push(`Page title: ${envData.pageTitle}`);
+                }
+                if (envData.seoDescription) {
+                    sections.push(`SEO description: ${envData.seoDescription}`);
+                }
+                if (envData.orientation) {
+                    sections.push(`Orientation: ${envData.orientation}`);
+                }
+            }
+            else {
+                sections.push(`(not configured)`);
+            }
+        }
+        else {
+            sections.push(`(not configured)`);
+        }
+        return {
+            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";
 // ---------------------------------------------------------------------------
@@ -82,6 +82,24 @@ function formatAgent(agent) {
     }
     return lines.join("\n");
 }
+function formatAppAction(action) {
+    const lines = [];
+    lines.push(`### ${action.name}`);
+    lines.push(`Key: ${action.key} | File: \`${action.fileKey}\``);
+    lines.push(`Root action: ${action.rootActionType}(${action.rootActionName})`);
+    if (action.description) {
+        lines.push(`Description: "${action.description}"`);
+    }
+    return lines.join("\n");
+}
+function formatCustomFile(file) {
+    const lines = [];
+    lines.push(`### ${file.name}`);
+    lines.push(`Key: ${file.key} | File: \`${file.fileKey}\``);
+    lines.push(`Type: ${file.fileType}`);
+    lines.push(`Actions: ${file.initialCount} initial, ${file.finalCount} final`);
+    return lines.join("\n");
+}
 function resolveReturnType(returnParam) {
     if (!returnParam)
         return null;
@@ -207,14 +225,80 @@ async function processAgents(projectId, nameFilter) {
         return { name: identifierName, key: idKey, fileKey, displayName, status, provider, model, requestTypes, responseType, description };
     }).then((results) => results.filter((r) => r !== null));
 }
+async function processAppActions(projectId, nameFilter) {
+    const allKeys = await listCachedKeys(projectId, "app-action-components/id-");
+    const topKeys = allKeys.filter((k) => /^app-action-components\/id-[a-z0-9]+$/i.test(k));
+    return batchProcess(topKeys, 10, async (fileKey) => {
+        const content = await cacheRead(projectId, fileKey);
+        if (!content)
+            return null;
+        const doc = YAML.parse(content);
+        const id = doc.identifier;
+        const name = id?.name || "unknown";
+        if (nameFilter && name.toLowerCase() !== nameFilter.toLowerCase())
+            return null;
+        const idKey = id?.key || fileKey.match(/id-([a-z0-9]+)$/i)?.[1] || "unknown";
+        const description = doc.description || "";
+        // Extract root action type and name
+        let rootActionType = "unknown";
+        let rootActionName = "unknown";
+        const actions = doc.actions;
+        const rootAction = actions?.rootAction;
+        const actionObj = rootAction?.action;
+        if (actionObj) {
+            const actionKeys = Object.keys(actionObj);
+            if (actionKeys.length > 0) {
+                rootActionType = actionKeys[0];
+                const actionBody = actionObj[rootActionType];
+                if (actionBody) {
+                    // Look for a sub-key ending in "Identifier" to get the name
+                    for (const subKey of Object.keys(actionBody)) {
+                        if (subKey.endsWith("Identifier")) {
+                            const identifierObj = actionBody[subKey];
+                            rootActionName = identifierObj?.name || rootActionName;
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+        return { name, key: idKey, fileKey, rootActionType, rootActionName, description };
+    }).then((results) => results.filter((r) => r !== null));
+}
+async function processCustomFiles(projectId, nameFilter) {
+    const allKeys = await listCachedKeys(projectId, "custom-file/id-");
+    const topKeys = allKeys.filter((k) => /^custom-file\/id-[^/]+$/i.test(k) && k !== "custom-file/id-MAIN");
+    return batchProcess(topKeys, 10, async (fileKey) => {
+        const content = await cacheRead(projectId, fileKey);
+        if (!content)
+            return null;
+        const doc = YAML.parse(content);
+        const keyMatch = fileKey.match(/^custom-file\/id-(.+)$/i);
+        const key = keyMatch?.[1] || "unknown";
+        const name = key;
+        if (nameFilter && name.toLowerCase() !== nameFilter.toLowerCase())
+            return null;
+        const fileType = doc.type || "UNKNOWN";
+        const actions = doc.actions || [];
+        let initialCount = 0;
+        let finalCount = 0;
+        for (const action of actions) {
+            if (action.type === "INITIAL_ACTION")
+                initialCount++;
+            else if (action.type === "FINAL_ACTION")
+                finalCount++;
+        }
+        return { name, key, fileKey, fileType, initialCount, finalCount };
+    }).then((results) => results.filter((r) => r !== null));
+}
 // ---------------------------------------------------------------------------
 // Tool registration
 // ---------------------------------------------------------------------------
 export function registerGetCustomCodeTool(server) {
-    server.tool("get_custom_code", "Get custom actions, functions, widgets, and AI agents from local cache — signatures, arguments, return types, and optionally Dart source code. No API calls. Run sync_project first if not cached.", {
+    server.tool("get_custom_code", "Get custom actions, functions, widgets, AI agents, app action components, and custom files from local cache — signatures, arguments, return types, and optionally Dart source code. No API calls. Run sync_project first if not cached.", {
         projectId: z.string().describe("The FlutterFlow project ID"),
         type: z
-            .enum(["actions", "functions", "widgets", "agents", "all"])
+            .enum(["actions", "functions", "widgets", "agents", "app-actions", "custom-files", "all"])
             .optional()
             .default("all")
             .describe("Type of custom code to retrieve"),
@@ -240,7 +324,7 @@ export function registerGetCustomCodeTool(server) {
             };
         }
         const categories = type === "all"
-            ? ["actions", "functions", "widgets", "agents"]
+            ? ["actions", "functions", "widgets", "agents", "app-actions", "custom-files"]
             : [type];
         const sections = [];
         for (const cat of categories) {
@@ -268,6 +352,18 @@ export function registerGetCustomCodeTool(server) {
                     sections.push(`## AI Agents (${items.length})\n\n${items.map(formatAgent).join("\n\n")}`);
                 }
             }
+            else if (cat === "app-actions") {
+                const items = await processAppActions(projectId, name);
+                if (items.length > 0) {
+                    sections.push(`## App Action Components (${items.length})\n\n${items.map(formatAppAction).join("\n\n")}`);
+                }
+            }
+            else if (cat === "custom-files") {
+                const items = await processCustomFiles(projectId, name);
+                if (items.length > 0) {
+                    sections.push(`## Custom Files (${items.length})\n\n${items.map(formatCustomFile).join("\n\n")}`);
+                }
+            }
         }
         if (sections.length === 0) {
             return {
@@ -278,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-editing-guide.d.ts

@@ -0,0 +1,7 @@
+/**
+ * get_editing_guide tool — returns workflow steps, relevant YAML docs,
+ * and universal rules for a given FlutterFlow editing task.
+ * No API calls: reads from bundled docs/ff-yaml/ directory.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerGetEditingGuideTool(server: McpServer): void;