flutterflow-mcp 0.2.3 → 0.3.0

package/build/tools/get-editing-guide.js

@@ -0,0 +1,185 @@
+import { z } from "zod";
+import { TOPIC_MAP, readDoc } from "../utils/topic-map.js";
+// ---------------------------------------------------------------------------
+// Keyword sets for edit-type detection
+// ---------------------------------------------------------------------------
+const ADD_WIDGET_KEYWORDS = ["add", "new", "insert", "append", "place", "put"];
+const COMPONENT_KEYWORDS = [
+    "component",
+    "reusable",
+    "refactor",
+    "extract",
+];
+const EDIT_KEYWORDS = [
+    "change",
+    "modify",
+    "update",
+    "edit",
+    "fix",
+    "set",
+    "remove",
+    "delete",
+    "hide",
+    "show",
+    "toggle",
+    "enable",
+    "disable",
+    "move",
+    "replace",
+    "rename",
+    "resize",
+    "restyle",
+];
+const CONFIG_KEYWORDS = [
+    "configure",
+    "settings",
+    "config",
+    "theme",
+    "auth",
+    "permission",
+    "navigation",
+    "nav",
+    "environment",
+];
+function detectEditType(words) {
+    const hasComponent = words.some((w) => COMPONENT_KEYWORDS.includes(w));
+    const hasAdd = words.some((w) => ADD_WIDGET_KEYWORDS.includes(w));
+    const hasConfig = words.some((w) => CONFIG_KEYWORDS.includes(w));
+    // Priority 1: component + (add/create/refactor)
+    if (hasComponent &&
+        (hasAdd || words.includes("create") || words.includes("refactor"))) {
+        return "create-component";
+    }
+    // Priority 2: config keywords
+    if (hasConfig) {
+        return "configure-project";
+    }
+    // Priority 3: add widget keywords
+    if (hasAdd) {
+        return "add-widget";
+    }
+    // Default
+    return "edit-existing";
+}
+// ---------------------------------------------------------------------------
+// Workflow templates
+// ---------------------------------------------------------------------------
+function getWorkflow(editType, projectId) {
+    const pid = projectId ?? "projectId";
+    switch (editType) {
+        case "edit-existing":
+            return `## Workflow: Editing Existing Widgets
+
+1. \`list_pages(${pid})\` — find the page
+2. \`get_page_by_name(${pid}, "PageName")\` — read the page, find the widget key
+3. \`get_project_yaml(${pid}, "page/id-Scaffold_XXX/.../node/id-Widget_YYY")\` — fetch node-level YAML
+4. Modify the YAML (keep both \`inputValue\` and \`mostRecentInputValue\` in sync)
+5. \`validate_yaml(${pid}, fileKey, yaml)\` — validate before pushing
+6. \`update_project_yaml(${pid}, { fileKey: yaml })\` — push changes`;
+        case "add-widget":
+            return `## Workflow: Adding New Widgets
+
+1. \`list_pages(${pid})\` — find the page
+2. \`get_page_by_name(${pid}, "PageName")\` — read the page structure
+3. Construct three types of files:
+   - Widget tree outline (\`page/id-Scaffold_XXX/page-widget-tree-outline\`)
+   - Parent node file (Column, Row, etc.)
+   - Individual child node files for each new widget
+4. \`validate_yaml\` for each file
+5. \`update_project_yaml(${pid}, { ...allFiles })\` — push ALL files in one call`;
+        case "create-component":
+            return `## Workflow: Creating/Refactoring Components
+
+1. Read the existing page/component with \`get_page_by_name\` or \`get_component_summary\`
+2. Construct component files:
+   - Component metadata (\`component/id-Container_XXX\`)
+   - Widget tree outline (\`component/id-Container_XXX/component-widget-tree-outline\`)
+   - Root Container node with \`isDummyRoot: true\`
+   - Individual child node files
+3. If refactoring: update the source page to reference the component via \`componentClassKeyRef\`
+4. \`validate_yaml\` for each file
+5. \`update_project_yaml(${pid}, { ...allFiles })\` — push ALL files in one call
+6. See \`get_yaml_docs(topic: "component")\` for full schema details`;
+        case "configure-project":
+            return `## Workflow: Configuring Project Settings
+
+1. \`sync_project(${pid})\` — sync the project cache
+2. Use cache tools to read current config:
+   - \`get_project_config\` — app details, auth, nav bar, permissions
+   - \`get_theme\` — colors, typography, breakpoints
+   - \`get_app_state\` — state variables, constants, environment
+3. \`get_project_yaml(${pid}, "fileName")\` — fetch the specific config file
+4. Modify the YAML
+5. \`validate_yaml\` then \`update_project_yaml\``;
+    }
+}
+// ---------------------------------------------------------------------------
+// Universal rules
+// ---------------------------------------------------------------------------
+const UNIVERSAL_RULES = `## Critical YAML Rules
+
+- **Always update both \`inputValue\` AND \`mostRecentInputValue\`** to the same value — they must stay in sync.
+  - **Exceptions:** \`fontWeightValue\` and \`fontSizeValue\` only accept \`inputValue\` (no \`mostRecentInputValue\`).
+- **Use node-level file keys** for targeted edits, not the full page YAML.
+- **Always validate before pushing** — call \`validate_yaml\` before \`update_project_yaml\`.
+- **Adding widgets requires node-level files** — push the tree outline + individual nodes together.
+- **Do NOT guess YAML field names** — use \`get_yaml_docs(topic: "...")\` to look them up.`;
+// ---------------------------------------------------------------------------
+// Doc resolution
+// ---------------------------------------------------------------------------
+function resolveDocFiles(words) {
+    const seen = new Set();
+    const files = [];
+    for (const word of words) {
+        // Normalize: lowercase, strip dashes/underscores
+        const key = word.toLowerCase().replace(/[\s_-]+/g, "");
+        const docFile = TOPIC_MAP[key];
+        if (docFile && !seen.has(docFile)) {
+            seen.add(docFile);
+            files.push(docFile);
+        }
+    }
+    return files;
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGetEditingGuideTool(server) {
+    server.tool("get_editing_guide", "Get the recommended workflow and relevant documentation for a FlutterFlow editing task. Call this BEFORE modifying any YAML. Describe what you want to do (e.g. 'change button color', 'add a TextField to the login page', 'create a reusable header component') and receive the correct workflow steps, YAML schemas, and critical rules.", {
+        task: z
+            .string()
+            .describe("Natural language description of what you want to do"),
+        projectId: z
+            .string()
+            .optional()
+            .describe("Optional project ID to include in workflow steps"),
+    }, async ({ task, projectId }) => {
+        // Tokenize into lowercase words
+        const words = task.toLowerCase().split(/\W+/).filter(Boolean);
+        // Detect edit type
+        const editType = detectEditType(words);
+        // Build workflow section
+        const workflow = getWorkflow(editType, projectId);
+        // Resolve matching doc files
+        const docFiles = resolveDocFiles(words);
+        // Read matched docs
+        const docSections = [];
+        for (const file of docFiles) {
+            const content = readDoc(file);
+            if (content) {
+                docSections.push(`---\n\n# Reference: ${file}\n\n${content}`);
+            }
+        }
+        // Assemble response
+        const parts = [workflow, "", UNIVERSAL_RULES, ""];
+        if (docSections.length > 0) {
+            parts.push(...docSections);
+        }
+        else {
+            parts.push('No specific widget/topic docs matched your task. Use `get_yaml_docs(topic: "...")` to search for relevant schemas, or `get_yaml_docs()` for the full index.');
+        }
+        return {
+            content: [{ type: "text", text: parts.join("\n") }],
+        };
+    });
+}

package/build/tools/get-general-settings.d.ts

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

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

@@ -0,0 +1,116 @@
+import { z } from "zod";
+import YAML from "yaml";
+import { cacheRead, cacheMeta } 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 registerGetGeneralSettingsTool(server) {
+    server.tool("get_general_settings", "Get General settings — App Details (name, package, initial page, routing), App Assets (icon, splash, error image), Nav Bar & App Bar. Mirrors the FlutterFlow 'General' 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 [appDetailsRaw, appAssetsRaw, navBarRaw] = await Promise.all([
+            cacheRead(projectId, "app-details"),
+            cacheRead(projectId, "app-assets"),
+            cacheRead(projectId, "nav-bar"),
+        ]);
+        const sections = ["# General Settings"];
+        // --- App Details ---
+        if (appDetailsRaw) {
+            const appDetails = YAML.parse(appDetailsRaw);
+            const appName = appDetails.name || "Unknown";
+            // Package name: take first env's packageName
+            let packageName = "not set";
+            const allAppNames = appDetails.allAppNames;
+            const appNames = allAppNames?.appNames;
+            if (appNames) {
+                const firstEnvKey = Object.keys(appNames)[0];
+                if (firstEnvKey) {
+                    packageName = appNames[firstEnvKey].packageName || "not set";
+                }
+            }
+            // Initial page
+            const initialPageKey = appDetails.initialPageKeyRef?.key;
+            let initialPageLine = "not set";
+            if (initialPageKey) {
+                const name = await resolvePageName(projectId, initialPageKey);
+                initialPageLine = `${name} (${initialPageKey})`;
+            }
+            // Routing
+            const routing = appDetails.routingSettings;
+            const routingEnabled = routing?.enableRouting === true;
+            const subroutes = routing?.pagesAreSubroutesOfRoot === true;
+            sections.push(`\n## App Details`, `Name: ${appName}`, `Package name: ${packageName}`, `Initial page: ${initialPageLine}`, `Routing: ${routingEnabled ? "enabled" : "disabled"}, pages are subroutes: ${subroutes ? "yes" : "no"}`);
+        }
+        else {
+            sections.push(`\n## App Details`, `(not configured)`);
+        }
+        // --- App Assets ---
+        if (appAssetsRaw) {
+            const appAssets = YAML.parse(appAssetsRaw);
+            const appIconPath = appAssets.appIconPath || "not set";
+            const splashImage = appAssets.splashImage;
+            const errorImagePath = appAssets.errorImagePath || "not set";
+            sections.push(`\n## App Assets`);
+            sections.push(`App icon: ${appIconPath}`);
+            if (splashImage) {
+                const splashPath = splashImage.path || "not set";
+                const splashFit = splashImage.fit || "not set";
+                const splashDuration = splashImage.minSplashScreenDuration;
+                sections.push(`Splash image: ${splashPath} (fit: ${splashFit})`);
+                if (splashDuration)
+                    sections.push(`Splash duration: ${splashDuration}ms`);
+            }
+            else {
+                sections.push(`Splash image: not set`);
+            }
+            sections.push(`Error image: ${errorImagePath}`);
+        }
+        else {
+            sections.push(`\n## App Assets`, `(not configured)`);
+        }
+        // --- Nav Bar & App Bar ---
+        if (navBarRaw) {
+            const navBar = YAML.parse(navBarRaw);
+            const visible = navBar.show === true;
+            if (visible) {
+                const navType = navBar.navBarType || "UNKNOWN";
+                const labels = navBar.labels === true;
+                const pageRefs = navBar.pageKeyRefOrder;
+                sections.push(`\n## Nav Bar & App Bar`, `Visible: Yes`, `Type: ${navType}`, `Labels: ${labels ? "Yes" : "No"}`);
+                if (pageRefs && pageRefs.length > 0) {
+                    const tabs = [];
+                    for (let i = 0; i < pageRefs.length; i++) {
+                        const scaffoldId = pageRefs[i].key;
+                        const name = await resolvePageName(projectId, scaffoldId);
+                        tabs.push(`  ${i + 1}. ${name} (${scaffoldId})`);
+                    }
+                    sections.push(`Tabs:`, ...tabs);
+                }
+            }
+            else {
+                sections.push(`\n## Nav Bar & App Bar`, `Visible: No`);
+            }
+        }
+        else {
+            sections.push(`\n## Nav Bar & App Bar`, `(not configured)`);
+        }
+        return {
+            content: [{ type: "text", text: sections.join("\n") }],
+        };
+    });
+}

package/build/tools/get-in-app-purchases.d.ts

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

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

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import YAML from "yaml";
+import { cacheRead, cacheMeta } from "../utils/cache.js";
+const PROVIDERS = [
+    { key: "stripe", label: "Stripe" },
+    { key: "braintree", label: "Braintree" },
+    { key: "revenue-cat", label: "RevenueCat" },
+    { key: "razorpay", label: "Razorpay" },
+];
+export function registerGetInAppPurchasesTool(server) {
+    server.tool("get_in_app_purchases", "Get In-App Purchases & Subscriptions settings — Stripe, Braintree, RevenueCat, Razorpay. Mirrors the FlutterFlow 'In App Purchases & Subscriptions' 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 sections = ["# In-App Purchases & Subscriptions"];
+        for (const provider of PROVIDERS) {
+            const raw = await cacheRead(projectId, provider.key);
+            sections.push(`\n## ${provider.label}`);
+            if (!raw) {
+                sections.push("(not configured)");
+                continue;
+            }
+            const doc = YAML.parse(raw);
+            const enabled = doc.enabled === true;
+            sections.push(`Enabled: ${enabled ? "Yes" : "No"}`);
+            // Show any additional top-level scalar fields (skip 'enabled' itself and complex objects)
+            for (const [key, value] of Object.entries(doc)) {
+                if (key === "enabled")
+                    continue;
+                if (value === null || value === undefined)
+                    continue;
+                if (typeof value === "object")
+                    continue;
+                sections.push(`${key}: ${String(value)}`);
+            }
+        }
+        return {
+            content: [{ type: "text", text: sections.join("\n") }],
+        };
+    });
+}

package/build/tools/get-integrations.d.ts

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

package/build/tools/get-integrations.js

@@ -0,0 +1,137 @@
+import { z } from "zod";
+import YAML from "yaml";
+import { cacheRead, cacheMeta } from "../utils/cache.js";
+/**
+ * Fields that should never be output — API keys, secrets, tokens, etc.
+ * Only IDs and non-sensitive configuration are shown.
+ */
+const SENSITIVE_KEYS = new Set([
+    "searchApiKey",
+    "supabaseAnonKey",
+    "supabaseServiceRoleKey",
+    "apiKey",
+    "secretKey",
+    "secret",
+    "token",
+    "accessToken",
+    "refreshToken",
+    "privateKey",
+]);
+// ---------------------------------------------------------------------------
+// Custom formatters for specific integrations
+// ---------------------------------------------------------------------------
+function formatAlgolia(doc) {
+    const lines = [];
+    const enabled = doc.enabled === true;
+    lines.push(`Enabled: ${enabled ? "Yes" : "No"}`);
+    const appId = doc.applicationId || "not set";
+    lines.push(`Application ID: ${appId}`);
+    const collections = doc.indexedCollections;
+    if (collections && collections.length > 0) {
+        lines.push(`Indexed collections:`);
+        for (const col of collections) {
+            lines.push(`  - ${col.name || "unnamed"}`);
+        }
+    }
+    else {
+        lines.push(`Indexed collections: none`);
+    }
+    return lines;
+}
+function formatGoogleMaps(doc) {
+    const androidKey = doc.androidKey || "not set";
+    const iosKey = doc.iosKey || "not set";
+    const webKey = doc.webKey || "not set";
+    return [
+        `Android key: ${androidKey}`,
+        `iOS key: ${iosKey}`,
+        `Web key: ${webKey}`,
+    ];
+}
+function formatFirebaseAnalytics(doc) {
+    const lines = [];
+    const enabled = doc.enabled === true;
+    lines.push(`Enabled: ${enabled ? "Yes" : "No"}`);
+    const settings = doc.automaticEventSettings;
+    if (settings) {
+        lines.push(`Automatic event settings:`);
+        lines.push(`  onPageLoad: ${settings.onPageLoad === true ? "Yes" : "No"}`);
+        lines.push(`  onActionsStart: ${settings.onActionsStart === true ? "Yes" : "No"}`);
+        lines.push(`  onAuth: ${settings.onAuth === true ? "Yes" : "No"}`);
+    }
+    return lines;
+}
+/**
+ * Generic formatter: shows `enabled` status and all non-sensitive
+ * top-level string/boolean fields.
+ */
+function formatGeneric(doc) {
+    const lines = [];
+    if ("enabled" in doc) {
+        lines.push(`Enabled: ${doc.enabled === true ? "Yes" : "No"}`);
+    }
+    for (const [key, value] of Object.entries(doc)) {
+        if (key === "enabled")
+            continue;
+        if (SENSITIVE_KEYS.has(key))
+            continue;
+        if (typeof value === "string" || typeof value === "boolean") {
+            lines.push(`${key}: ${typeof value === "boolean" ? (value ? "Yes" : "No") : value}`);
+        }
+    }
+    return lines;
+}
+// ---------------------------------------------------------------------------
+// Integration list — order matches the spec
+// ---------------------------------------------------------------------------
+const INTEGRATIONS = [
+    { fileKey: "supabase", displayName: "Supabase" },
+    { fileKey: "sqlite", displayName: "SQLite" },
+    { fileKey: "github", displayName: "GitHub" },
+    { fileKey: "algolia", displayName: "Algolia", format: formatAlgolia },
+    { fileKey: "firebase-analytics", displayName: "Google Analytics", format: formatFirebaseAnalytics },
+    { fileKey: "google-maps", displayName: "Google Maps", format: formatGoogleMaps },
+    { fileKey: "admob", displayName: "AdMob" },
+    { fileKey: "mux", displayName: "Mux Livestream" },
+    { fileKey: "onesignal", displayName: "OneSignal" },
+    { fileKey: "gemini", displayName: "Gemini" },
+];
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGetIntegrationsTool(server) {
+    server.tool("get_integrations", "Get Integrations settings — Supabase, SQLite, GitHub, Algolia, Google Analytics, Google Maps, AdMob, Mux Livestream, OneSignal, Gemini. Mirrors the FlutterFlow 'Integrations' 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.`,
+                    },
+                ],
+            };
+        }
+        // Read all integration files in parallel
+        const rawResults = await Promise.all(INTEGRATIONS.map((def) => cacheRead(projectId, def.fileKey)));
+        const sections = ["# Integrations"];
+        for (let i = 0; i < INTEGRATIONS.length; i++) {
+            const def = INTEGRATIONS[i];
+            const raw = rawResults[i];
+            sections.push(`\n## ${def.displayName}`);
+            if (!raw) {
+                sections.push("(not configured)");
+                continue;
+            }
+            const doc = YAML.parse(raw);
+            const formatter = def.format || formatGeneric;
+            const lines = formatter(doc);
+            sections.push(lines.join("\n"));
+        }
+        return {
+            content: [{ type: "text", text: sections.join("\n") }],
+        };
+    });
+}

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

@@ -6,6 +6,7 @@ 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";
 import { formatPageSummary } from "../utils/page-summary/formatter.js";
+import { resolveDataType } from "../utils/resolve-data-type.js";
 /**
  * Resolve a page name or scaffold ID to its cache file key.
  * Returns all available page names if no match found.
@@ -41,24 +42,6 @@ export async function resolvePage(projectId, pageName, scaffoldId) {
 // ---------------------------------------------------------------------------
 // Metadata extraction
 // ---------------------------------------------------------------------------
-/** Resolve a scalar/list data type to a readable string. */
-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";
-}
 /** Extract page metadata (name, params, state) from the top-level page YAML. */
 async function extractPageMeta(projectId, page, folder) {
     const content = await cacheRead(projectId, page.pageFileKey);

package/build/tools/get-project-setup.d.ts

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