community-ff-mcp 0.4.0

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

@@ -0,0 +1,126 @@
+import { z } from "zod";
+import YAML from "yaml";
+import { cacheRead, cacheMeta, cacheAgeFooter, listCachedKeys } from "../utils/cache.js";
+import { batchProcess } from "../utils/batch-process.js";
+function parseEndpoint(content) {
+    const doc = YAML.parse(content);
+    if (!doc)
+        return null;
+    const identifier = doc.identifier;
+    const name = identifier?.name || "Unknown";
+    const method = doc.callType || "GET";
+    const url = doc.url || "";
+    const bodyType = doc.bodyType;
+    const body = doc.body;
+    const variables = [];
+    const rawVars = doc.variables;
+    if (Array.isArray(rawVars)) {
+        for (const v of rawVars) {
+            const vid = v.identifier;
+            const vName = vid?.name || "unknown";
+            const vType = v.type || "String";
+            variables.push({ name: vName, type: vType });
+        }
+    }
+    const headers = [];
+    const rawHeaders = doc.headers;
+    if (Array.isArray(rawHeaders)) {
+        headers.push(...rawHeaders);
+    }
+    const responseFields = [];
+    const rawJsonPaths = doc.jsonPathDefinitions;
+    if (Array.isArray(rawJsonPaths)) {
+        for (const jp of rawJsonPaths) {
+            const jpId = jp.identifier;
+            const jpName = jpId?.name || "unknown";
+            const jpDef = jp.jsonPath;
+            const path = jpDef?.jsonPath || "";
+            const returnParam = jpDef?.returnParameter;
+            const dt = returnParam?.dataType;
+            const scalarType = dt?.scalarType || "String";
+            responseFields.push({ name: jpName, type: scalarType, jsonPath: path });
+        }
+    }
+    return { name, method, url, bodyType, body, variables, headers, responseFields };
+}
+function formatEndpoints(endpoints) {
+    if (endpoints.length === 0)
+        return "No API endpoints found in cache.";
+    const lines = [`# API Endpoints (${endpoints.length})`];
+    for (const ep of endpoints) {
+        lines.push("");
+        lines.push(`## ${ep.name}`);
+        lines.push(`Method: ${ep.method}`);
+        lines.push(`URL: ${ep.url}`);
+        if (ep.bodyType)
+            lines.push(`Body type: ${ep.bodyType}`);
+        if (ep.variables.length > 0) {
+            lines.push("Variables:");
+            for (const v of ep.variables) {
+                lines.push(`  - ${v.name}: ${v.type}`);
+            }
+        }
+        if (ep.headers.length > 0) {
+            lines.push("Headers:");
+            for (const h of ep.headers) {
+                lines.push(`  - ${h}`);
+            }
+        }
+        if (ep.responseFields.length > 0) {
+            lines.push("Response fields:");
+            for (const rf of ep.responseFields) {
+                lines.push(`  - ${rf.name}: ${rf.type} (${rf.jsonPath})`);
+            }
+        }
+    }
+    return lines.join("\n");
+}
+export function registerGetApiEndpointsTool(server) {
+    server.tool("get_api_endpoints", "Get API endpoint definitions from local cache — method, URL, variables, headers, response fields. No API calls. Run sync_project first if not cached.", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+        name: z
+            .string()
+            .optional()
+            .describe("Case-insensitive filter on endpoint name"),
+    }, async ({ projectId, name }) => {
+        const meta = await cacheMeta(projectId);
+        if (!meta) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No cache found for project "${projectId}". Run sync_project first to download the project YAML files.`,
+                    },
+                ],
+            };
+        }
+        const allKeys = await listCachedKeys(projectId, "api-endpoint/id-");
+        const topLevelKeys = allKeys.filter((k) => /^api-endpoint\/id-[a-z0-9]+$/i.test(k));
+        const parsed = await batchProcess(topLevelKeys, 10, async (key) => {
+            const content = await cacheRead(projectId, key);
+            if (!content)
+                return null;
+            return parseEndpoint(content);
+        });
+        let endpoints = parsed.filter((ep) => ep !== null);
+        if (name) {
+            const lower = name.toLowerCase();
+            const filtered = endpoints.filter((ep) => ep.name.toLowerCase().includes(lower));
+            if (filtered.length === 0) {
+                const available = endpoints.map((ep) => ep.name).join(", ");
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No API endpoints matching '${name}' found. Available: ${available}`,
+                        },
+                    ],
+                };
+            }
+            endpoints = filtered;
+        }
+        return {
+            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.d.ts

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

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

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import YAML from "yaml";
+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.", {
+        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 = ["# App State"];
+        // --- State Variables ---
+        const appStateYaml = await cacheRead(projectId, "app-state");
+        if (appStateYaml) {
+            const doc = YAML.parse(appStateYaml);
+            const fields = doc.fields || [];
+            const lines = [];
+            for (const field of fields) {
+                const name = field.parameter?.identifier?.name || "unknown";
+                const dt = resolveDataType(field.parameter?.dataType || {});
+                const parts = [`- ${name}: ${dt}`];
+                if (field.persisted)
+                    parts.push("(persisted)");
+                if (field.serializedDefaultValue && field.serializedDefaultValue.length > 0) {
+                    const joined = field.serializedDefaultValue
+                        .map((v) => `"${v}"`)
+                        .join(", ");
+                    parts.push(`[default: ${joined}]`);
+                }
+                lines.push(parts.join(" "));
+            }
+            sections.push("\n## State Variables");
+            if (lines.length > 0) {
+                sections.push(lines.join("\n"));
+            }
+            const secure = doc.securePersistedValues ?? false;
+            sections.push(`\nSecure persisted values: ${secure ? "Yes" : "No"}`);
+        }
+        // --- Constants ---
+        const constantsYaml = await cacheRead(projectId, "app-constants");
+        if (constantsYaml) {
+            const doc = YAML.parse(constantsYaml);
+            const fields = doc.fields || [];
+            const lines = [];
+            for (const field of fields) {
+                const name = field.parameter?.identifier?.name || "unknown";
+                const dt = resolveDataType(field.parameter?.dataType || {});
+                const vals = field.serializedValue || [];
+                const formatted = vals.map((v) => `"${v}"`).join(", ");
+                lines.push(`- ${name}: ${dt} = [${formatted}]`);
+            }
+            sections.push("\n## Constants");
+            if (lines.length > 0) {
+                sections.push(lines.join("\n"));
+            }
+        }
+        // --- Environment Settings ---
+        const envYaml = await cacheRead(projectId, "environment-settings");
+        if (envYaml) {
+            const doc = YAML.parse(envYaml);
+            const currentEnv = doc.currentEnvironment;
+            const envValues = doc.environmentValues || [];
+            sections.push("\n## Environment Settings");
+            if (currentEnv) {
+                sections.push(`Current: ${currentEnv.name || "unknown"} (${currentEnv.key || "?"})`);
+            }
+            const lines = [];
+            for (const ev of envValues) {
+                const name = ev.parameter?.identifier?.name || "unknown";
+                const dt = resolveDataType(ev.parameter?.dataType || {});
+                const privateTag = ev.isPrivate ? " (private)" : "";
+                lines.push(`- ${name}: ${dt}${privateTag}`);
+                const valuesMap = ev.valuesMap || {};
+                for (const [envKey, envVal] of Object.entries(valuesMap)) {
+                    const display = ev.isPrivate ? "****" : (envVal.serializedValue ?? "");
+                    lines.push(`  ${envKey}: ${display}`);
+                }
+            }
+            if (lines.length > 0) {
+                sections.push(lines.join("\n"));
+            }
+        }
+        return {
+            content: [{ type: "text", text: sections.join("\n") + cacheAgeFooter(meta) }],
+        };
+    });
+}

package/build/tools/get-component-summary.d.ts

@@ -0,0 +1,22 @@
+/**
+ * get_component_summary tool — assembles cached sub-files into a readable
+ * component summary. Zero API calls: everything comes from the local .ff-cache.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+interface ResolvedComponent {
+    containerId: string;
+    componentFileKey: string;
+}
+/**
+ * Resolve a component name or container ID to its cache file key.
+ * Returns all available component names if no match found.
+ */
+export declare function resolveComponent(projectId: string, componentName?: string, componentId?: string): Promise<{
+    ok: true;
+    component: ResolvedComponent;
+} | {
+    ok: false;
+    available: string[];
+}>;
+export declare function registerGetComponentSummaryTool(server: McpServer): void;
+export {};

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

@@ -0,0 +1,195 @@
+import { z } from "zod";
+import YAML from "yaml";
+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";
+import { formatComponentSummary } from "../utils/page-summary/formatter.js";
+/**
+ * Resolve a component name or container ID to its cache file key.
+ * Returns all available component names if no match found.
+ */
+export async function resolveComponent(projectId, componentName, componentId) {
+    if (componentId) {
+        const componentFileKey = `component/id-${componentId}`;
+        const content = await cacheRead(projectId, componentFileKey);
+        if (content) {
+            return { ok: true, component: { containerId: componentId, componentFileKey } };
+        }
+    }
+    // List all cached component top-level files
+    const allKeys = await listCachedKeys(projectId, "component/id-");
+    // Filter to top-level component files only (not sub-files)
+    const componentKeys = allKeys.filter((k) => /^component\/id-Container_\w+$/.test(k));
+    const available = [];
+    for (const key of componentKeys) {
+        const content = await cacheRead(projectId, key);
+        if (!content)
+            continue;
+        const nameMatch = content.match(/^name:\s*(.+)$/m);
+        const name = nameMatch ? nameMatch[1].trim() : "";
+        if (componentName && name.toLowerCase() === componentName.toLowerCase()) {
+            const cid = key.match(/^component\/id-(Container_\w+)$/)?.[1] || "";
+            return { ok: true, component: { containerId: cid, componentFileKey: key } };
+        }
+        if (name)
+            available.push(name);
+    }
+    return { ok: false, available };
+}
+// ---------------------------------------------------------------------------
+// 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 component metadata (name, description, params) from the top-level YAML. */
+async function extractComponentMeta(projectId, component) {
+    const content = await cacheRead(projectId, component.componentFileKey);
+    if (!content) {
+        return {
+            componentName: component.containerId,
+            containerId: component.containerId,
+            description: "",
+            params: [],
+        };
+    }
+    const doc = YAML.parse(content);
+    const componentName = doc.name || component.containerId;
+    const description = doc.description || "";
+    // Params
+    const params = [];
+    const rawParams = doc.params;
+    if (rawParams) {
+        for (const val of Object.values(rawParams)) {
+            const id = val.identifier;
+            const name = id?.name || "unknown";
+            const dt = val.dataType || {};
+            const defaultVal = val.defaultValue;
+            params.push({
+                name,
+                dataType: resolveDataType(dt),
+                defaultValue: defaultVal?.serializedValue,
+            });
+        }
+    }
+    return { componentName, containerId: component.containerId, description, params };
+}
+// ---------------------------------------------------------------------------
+// Tree enrichment (reused from page summary)
+// ---------------------------------------------------------------------------
+/**
+ * Recursively enrich an OutlineNode tree with node info and trigger summaries.
+ */
+async function enrichNode(projectId, treePrefix, // e.g. "component/id-Container_xxx/component-widget-tree-outline"
+outline) {
+    const nodeInfo = await extractNodeInfo(projectId, treePrefix, outline.key);
+    // Check for triggers
+    const nodeFilePrefix = `${treePrefix}/node/id-${outline.key}`;
+    const triggers = await summarizeTriggers(projectId, nodeFilePrefix);
+    // Enrich children
+    const children = await Promise.all(outline.children.map((child) => enrichNode(projectId, treePrefix, child)));
+    return {
+        key: outline.key,
+        type: nodeInfo.type,
+        name: nodeInfo.name,
+        slot: outline.slot,
+        detail: nodeInfo.detail,
+        componentRef: nodeInfo.componentRef,
+        componentId: nodeInfo.componentId,
+        triggers,
+        children,
+    };
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGetComponentSummaryTool(server) {
+    server.tool("get_component_summary", "Get a readable summary of a FlutterFlow component from local cache — widget tree, actions, params. Nested component references are resolved to show [ComponentName] (ComponentId). No API calls. Run sync_project first if not cached.", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+        componentName: z
+            .string()
+            .optional()
+            .describe("Human-readable component name (e.g. 'PremuimContentWall'). Case-insensitive. Provide either componentName or componentId."),
+        componentId: z
+            .string()
+            .optional()
+            .describe("Container ID (e.g. 'Container_ffzg5wc5'). Provide either componentName or componentId."),
+    }, async ({ projectId, componentName, componentId }) => {
+        // Check cache exists
+        const meta = await cacheMeta(projectId);
+        if (!meta) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No cache found for project "${projectId}". Run sync_project first to download the project YAML files.`,
+                    },
+                ],
+            };
+        }
+        if (!componentName && !componentId) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Provide either componentName or componentId.",
+                    },
+                ],
+            };
+        }
+        // Resolve component
+        const resolved = await resolveComponent(projectId, componentName, componentId);
+        if (!resolved.ok) {
+            const list = resolved.available.map((n) => `  - ${n}`).join("\n");
+            const searchTerm = componentName || componentId || "";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Component "${searchTerm}" not found in cache. Available components:\n${list}`,
+                    },
+                ],
+            };
+        }
+        const component = resolved.component;
+        // Extract metadata
+        const componentMeta = await extractComponentMeta(projectId, component);
+        // Parse widget tree outline
+        const outlineKey = `${component.componentFileKey}/component-widget-tree-outline`;
+        const outlineContent = await cacheRead(projectId, outlineKey);
+        if (!outlineContent) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Component "${componentMeta.componentName}" found but widget tree outline is not cached. Re-run sync_project to fetch all sub-files.`,
+                    },
+                ],
+            };
+        }
+        const outlineTree = parseTreeOutline(outlineContent);
+        // Enrich the tree with node info and triggers
+        const enrichedTree = await enrichNode(projectId, outlineKey, outlineTree);
+        // Format output
+        const summary = formatComponentSummary(componentMeta, enrichedTree);
+        return {
+            content: [{ type: "text", text: summary + cacheAgeFooter(meta) }],
+        };
+    });
+}

package/build/tools/get-custom-code.d.ts

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