flutterflow-mcp 0.1.0

package/build/tools/list-pages.js

@@ -0,0 +1,101 @@
+import { z } from "zod";
+import { decodeProjectYamlResponse } from "../utils/decode-yaml.js";
+import { parseFolderMapping } from "../utils/parse-folders.js";
+import { cacheRead, cacheWrite } from "../utils/cache.js";
+/**
+ * Extract page scaffold IDs from the partitioned file names list.
+ * Filters for top-level page files only (not sub-files like widget-tree-outline).
+ */
+export function extractPageFileKeys(fileNames) {
+    const raw = fileNames;
+    const names = raw?.value?.file_names ?? raw?.value?.fileNames ?? [];
+    return names.filter((n) => /^page\/id-Scaffold_\w+$/.test(n));
+}
+/**
+ * Fetch a single YAML file and decode it. Returns null on failure.
+ */
+export async function fetchOneFile(client, projectId, fileName) {
+    // Check cache first
+    const cached = await cacheRead(projectId, fileName);
+    if (cached) {
+        return { fileKey: fileName, content: cached };
+    }
+    try {
+        const raw = await client.getProjectYamls(projectId, fileName);
+        const decoded = decodeProjectYamlResponse(raw);
+        const entries = Object.entries(decoded);
+        if (entries.length > 0) {
+            // Write to cache on fetch
+            await cacheWrite(projectId, fileName, entries[0][1]);
+            return { fileKey: fileName, content: entries[0][1] };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Process items in batches to avoid API rate limits.
+ */
+async function batchProcess(items, batchSize, fn) {
+    const results = [];
+    for (let i = 0; i < items.length; i += batchSize) {
+        const batch = items.slice(i, i + batchSize);
+        const batchResults = await Promise.allSettled(batch.map(fn));
+        results.push(...batchResults);
+    }
+    return results;
+}
+/**
+ * Extract a compact page index by fetching pages in batches.
+ */
+export async function listPages(client, projectId) {
+    // Step 1: Get file list and folders in parallel
+    const [fileNamesRaw, foldersResult] = await Promise.all([
+        client.listPartitionedFileNames(projectId),
+        fetchOneFile(client, projectId, "folders"),
+    ]);
+    const pageFileKeys = extractPageFileKeys(fileNamesRaw);
+    const folderMap = foldersResult
+        ? parseFolderMapping(foldersResult.content)
+        : {};
+    // Step 2: Fetch pages in batches of 5 to avoid rate limits
+    const results = await batchProcess(pageFileKeys, 5, (fileKey) => fetchOneFile(client, projectId, fileKey));
+    const pages = [];
+    for (let i = 0; i < pageFileKeys.length; i++) {
+        const fileKey = pageFileKeys[i];
+        const scaffoldMatch = fileKey.match(/^page\/id-(Scaffold_\w+)$/);
+        if (!scaffoldMatch)
+            continue;
+        const scaffoldId = scaffoldMatch[1];
+        const result = results[i];
+        let name = "(error - could not fetch)";
+        if (result.status === "fulfilled" && result.value) {
+            const nameMatch = result.value.content.match(/^name:\s*(.+)$/m);
+            name = nameMatch ? nameMatch[1].trim() : "(unknown)";
+        }
+        const folder = folderMap[scaffoldId] || "(unmapped)";
+        pages.push({ scaffoldId, name, folder, fileKey });
+    }
+    // Sort by folder then name
+    pages.sort((a, b) => a.folder === b.folder
+        ? a.name.localeCompare(b.name)
+        : a.folder.localeCompare(b.folder));
+    return pages;
+}
+export function registerListPagesTool(server, client) {
+    server.tool("list_pages", "List all pages in a FlutterFlow project with human-readable names, scaffold IDs, and folder assignments. Use this FIRST to discover pages before fetching their YAML.", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+    }, async ({ projectId }) => {
+        const pages = await listPages(client, projectId);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(pages, null, 2),
+                },
+            ],
+        };
+    });
+}

package/build/tools/list-projects.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { FlutterFlowClient } from "../api/flutterflow.js";
+export declare function registerListProjectsTool(server: McpServer, client: FlutterFlowClient): void;

package/build/tools/list-projects.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+export function registerListProjectsTool(server, client) {
+    server.tool("list_projects", "List all FlutterFlow projects for the authenticated user", {
+        project_type: z
+            .string()
+            .optional()
+            .describe("Optional filter for project type"),
+    }, async ({ project_type }) => {
+        const result = await client.listProjects(project_type);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+}

package/build/tools/sync-project.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { FlutterFlowClient } from "../api/flutterflow.js";
+export declare function registerSyncProjectTool(server: McpServer, client: FlutterFlowClient): void;

package/build/tools/sync-project.js

@@ -0,0 +1,144 @@
+import { z } from "zod";
+import { decodeProjectYamlResponse } from "../utils/decode-yaml.js";
+import { cacheWriteBulk, cacheWriteMeta, cacheWrite, cacheMeta, } from "../utils/cache.js";
+import { fetchOneFile } from "./list-pages.js";
+/**
+ * Extract top-level file keys from the listPartitionedFileNames response.
+ * Filters out deeply nested sub-files (widget nodes, etc.) that can't be
+ * fetched individually and would hammer the API with thousands of requests.
+ * Top-level keys have at most 2 path segments (e.g. "page/id-Scaffold_xxx").
+ */
+function extractTopLevelFileKeys(fileNamesRaw) {
+    const raw = fileNamesRaw;
+    const allKeys = raw?.value?.file_names ?? raw?.value?.fileNames ?? [];
+    return allKeys.filter((key) => key.split("/").length <= 2);
+}
+/**
+ * Process items in batches to avoid API rate limits.
+ */
+async function batchProcess(items, batchSize, fn) {
+    const results = [];
+    for (let i = 0; i < items.length; i += batchSize) {
+        const batch = items.slice(i, i + batchSize);
+        const batchResults = await Promise.allSettled(batch.map(fn));
+        results.push(...batchResults);
+    }
+    return results;
+}
+export function registerSyncProjectTool(server, client) {
+    server.tool("sync_project", "Sync an entire FlutterFlow project to the local cache. Downloads all YAML files (bulk or batched fallback) for fast offline reads. Use force=true to re-sync an already cached project.", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+        force: z
+            .boolean()
+            .optional()
+            .describe("Force re-sync even if cache already exists (default: false)"),
+    }, async ({ projectId, force }) => {
+        // Check existing cache unless force is set
+        if (!force) {
+            const existing = await cacheMeta(projectId);
+            if (existing) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                status: "already_cached",
+                                message: "Project is already cached. Pass force=true to re-sync.",
+                                cachedAt: existing.lastSyncedAt,
+                                fileCount: existing.fileCount,
+                                syncMethod: existing.syncMethod,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+        }
+        // Primary path: bulk fetch entire project as one ZIP
+        try {
+            const raw = await client.getProjectYamls(projectId);
+            const decoded = decodeProjectYamlResponse(raw);
+            // ZIP entry names include .yaml extension, but cacheWrite adds it too.
+            // Strip .yaml from keys to avoid double extension (.yaml.yaml).
+            const normalized = {};
+            for (const [key, content] of Object.entries(decoded)) {
+                const cleanKey = key.endsWith(".yaml") ? key.slice(0, -".yaml".length) : key;
+                normalized[cleanKey] = content;
+            }
+            const syncedFiles = await cacheWriteBulk(projectId, normalized);
+            const meta = {
+                lastSyncedAt: new Date().toISOString(),
+                fileCount: syncedFiles,
+                syncMethod: "bulk",
+            };
+            await cacheWriteMeta(projectId, meta);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            status: "synced",
+                            syncedFiles,
+                            failed: 0,
+                            method: "bulk",
+                            cachedAt: meta.lastSyncedAt,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            // Bulk fetch failed — log and fall through to batched approach
+            console.error(`[sync_project] Bulk fetch failed, falling back to batched:`, err instanceof Error ? err.message : err);
+        }
+        // Fallback path: list all file keys, then batch-fetch 5 at a time
+        const fileNamesRaw = await client.listPartitionedFileNames(projectId);
+        const allKeys = extractTopLevelFileKeys(fileNamesRaw);
+        if (allKeys.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            status: "error",
+                            message: "No file keys returned by listPartitionedFileNames. " +
+                                "Check the projectId.",
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        let syncedFiles = 0;
+        let failed = 0;
+        const results = await batchProcess(allKeys, 5, (fileKey) => fetchOneFile(client, projectId, fileKey));
+        for (let i = 0; i < allKeys.length; i++) {
+            const result = results[i];
+            if (result.status === "fulfilled" && result.value) {
+                await cacheWrite(projectId, allKeys[i], result.value.content);
+                syncedFiles++;
+            }
+            else {
+                failed++;
+            }
+        }
+        const meta = {
+            lastSyncedAt: new Date().toISOString(),
+            fileCount: syncedFiles,
+            syncMethod: "batched",
+        };
+        await cacheWriteMeta(projectId, meta);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        status: "synced",
+                        syncedFiles,
+                        failed,
+                        method: "batched",
+                        cachedAt: meta.lastSyncedAt,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/build/tools/update-yaml.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { FlutterFlowClient } from "../api/flutterflow.js";
+export declare function registerUpdateYamlTool(server: McpServer, client: FlutterFlowClient): void;

package/build/tools/update-yaml.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { cacheWrite } from "../utils/cache.js";
+export function registerUpdateYamlTool(server, client) {
+    server.tool("update_project_yaml", "Push YAML changes to a FlutterFlow project. IMPORTANT: Always call validate_yaml first to check for errors before updating.", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+        fileKeyToContent: z
+            .record(z.string(), z.string())
+            .describe("Map of file keys to YAML content. Pass each value as a normal multi-line YAML string."),
+    }, async ({ projectId, fileKeyToContent }) => {
+        const result = await client.updateProjectByYaml(projectId, fileKeyToContent);
+        // Update cache with the pushed content
+        for (const [fileKey, content] of Object.entries(fileKeyToContent)) {
+            await cacheWrite(projectId, fileKey, content);
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+}

package/build/tools/validate-yaml.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { FlutterFlowClient } from "../api/flutterflow.js";
+export declare function registerValidateYamlTool(server: McpServer, client: FlutterFlowClient): void;

package/build/tools/validate-yaml.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+export function registerValidateYamlTool(server, client) {
+    server.tool("validate_yaml", "Validate YAML content before pushing changes to a FlutterFlow project. Always call this before update_project_yaml.", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+        fileKey: z
+            .string()
+            .describe("The YAML file key (e.g. 'app-details', 'page/id-xxx')"),
+        fileContent: z
+            .string()
+            .describe("Pass YAML content as a normal multi-line string."),
+    }, async ({ projectId, fileKey, fileContent }) => {
+        const result = await client.validateProjectYaml(projectId, fileKey, fileContent);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+}

package/build/utils/cache.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Metadata stored alongside the cached YAML files for a project.
+ */
+export interface CacheMeta {
+    lastSyncedAt: string;
+    fileCount: number;
+    syncMethod: "bulk" | "batched";
+}
+/**
+ * Resolve the cache directory for a given project.
+ * Returns an absolute path: `<projectRoot>/.ff-cache/<projectId>/`
+ */
+export declare function cacheDir(projectId: string): string;
+/**
+ * Read a cached YAML string for a given file key.
+ * Returns `null` if the file does not exist.
+ */
+export declare function cacheRead(projectId: string, fileKey: string): Promise<string | null>;
+/**
+ * Write a single YAML string to the cache, creating directories as needed.
+ */
+export declare function cacheWrite(projectId: string, fileKey: string, content: string): Promise<void>;
+/**
+ * Delete a single cached file. No-op if the file does not exist.
+ */
+export declare function cacheInvalidate(projectId: string, fileKey: string): Promise<void>;
+/**
+ * Write multiple YAML entries to the cache in one call.
+ * Returns the number of entries written.
+ */
+export declare function cacheWriteBulk(projectId: string, entries: Record<string, string>): Promise<number>;
+/**
+ * Read the `_meta.json` file for a project cache.
+ * Returns `null` if it does not exist.
+ */
+export declare function cacheMeta(projectId: string): Promise<CacheMeta | null>;
+/**
+ * Write (or overwrite) the `_meta.json` file for a project cache.
+ */
+export declare function cacheWriteMeta(projectId: string, meta: CacheMeta): Promise<void>;
+/**
+ * Walk the cache directory for a project and return all cached file keys,
+ * optionally filtered by a prefix (e.g. `"page/"` to list only pages).
+ *
+ * File keys are reconstructed by stripping the `.yaml` extension and making
+ * the path relative to the project cache dir.
+ */
+export declare function listCachedKeys(projectId: string, prefix?: string): Promise<string[]>;

package/build/utils/cache.js

@@ -0,0 +1,162 @@
+import { mkdir, readFile, writeFile, unlink, readdir } from "node:fs/promises";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+// ---------------------------------------------------------------------------
+// Project root resolution
+// ---------------------------------------------------------------------------
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Project root: two levels up from src/utils/ */
+const PROJECT_ROOT = resolve(__dirname, "..", "..");
+const CACHE_DIR_NAME = ".ff-cache";
+const META_FILE = "_meta.json";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the cache directory for a given project.
+ * Returns an absolute path: `<projectRoot>/.ff-cache/<projectId>/`
+ */
+export function cacheDir(projectId) {
+    return join(PROJECT_ROOT, CACHE_DIR_NAME, projectId);
+}
+/**
+ * Convert a FlutterFlow file key to a cache file path.
+ * `page/id-Scaffold_xxx` -> `.ff-cache/{pid}/page/id-Scaffold_xxx.yaml`
+ */
+function keyToPath(projectId, fileKey) {
+    return join(cacheDir(projectId), `${fileKey}.yaml`);
+}
+/**
+ * Ensure a directory exists (recursive mkdir, no-op if already there).
+ */
+async function ensureDir(dir) {
+    await mkdir(dir, { recursive: true });
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Read a cached YAML string for a given file key.
+ * Returns `null` if the file does not exist.
+ */
+export async function cacheRead(projectId, fileKey) {
+    try {
+        const content = await readFile(keyToPath(projectId, fileKey), "utf-8");
+        return content;
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === "ENOENT") {
+            return null;
+        }
+        throw err;
+    }
+}
+/**
+ * Write a single YAML string to the cache, creating directories as needed.
+ */
+export async function cacheWrite(projectId, fileKey, content) {
+    const filePath = keyToPath(projectId, fileKey);
+    await ensureDir(dirname(filePath));
+    await writeFile(filePath, content, "utf-8");
+}
+/**
+ * Delete a single cached file. No-op if the file does not exist.
+ */
+export async function cacheInvalidate(projectId, fileKey) {
+    try {
+        await unlink(keyToPath(projectId, fileKey));
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === "ENOENT") {
+            return; // already gone — no-op
+        }
+        throw err;
+    }
+}
+/**
+ * Write multiple YAML entries to the cache in one call.
+ * Returns the number of entries written.
+ */
+export async function cacheWriteBulk(projectId, entries) {
+    const keys = Object.keys(entries);
+    await Promise.all(keys.map((key) => cacheWrite(projectId, key, entries[key])));
+    return keys.length;
+}
+/**
+ * Read the `_meta.json` file for a project cache.
+ * Returns `null` if it does not exist.
+ */
+export async function cacheMeta(projectId) {
+    const metaPath = join(cacheDir(projectId), META_FILE);
+    try {
+        const raw = await readFile(metaPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === "ENOENT") {
+            return null;
+        }
+        throw err;
+    }
+}
+/**
+ * Write (or overwrite) the `_meta.json` file for a project cache.
+ */
+export async function cacheWriteMeta(projectId, meta) {
+    const dir = cacheDir(projectId);
+    await ensureDir(dir);
+    await writeFile(join(dir, META_FILE), JSON.stringify(meta, null, 2), "utf-8");
+}
+/**
+ * Walk the cache directory for a project and return all cached file keys,
+ * optionally filtered by a prefix (e.g. `"page/"` to list only pages).
+ *
+ * File keys are reconstructed by stripping the `.yaml` extension and making
+ * the path relative to the project cache dir.
+ */
+export async function listCachedKeys(projectId, prefix) {
+    const root = cacheDir(projectId);
+    const keys = [];
+    try {
+        await walkDir(root, root, keys, ".yaml");
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === "ENOENT") {
+            return []; // cache dir doesn't exist yet
+        }
+        throw err;
+    }
+    const yamlKeys = keys.map((k) => k.slice(0, -".yaml".length));
+    if (prefix) {
+        return yamlKeys.filter((k) => k.startsWith(prefix));
+    }
+    return yamlKeys;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Recursively walk a directory, collecting relative paths of files.
+ */
+async function walkDir(base, dir, out, ext) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            await walkDir(base, full, out, ext);
+        }
+        else if (entry.isFile()) {
+            if (ext && !entry.name.endsWith(ext))
+                continue;
+            // Relative path from cache root, using forward slashes for consistency
+            const rel = full.slice(base.length + 1).split("\\").join("/");
+            out.push(rel);
+        }
+    }
+}
+/**
+ * Type guard for Node.js system errors (which carry a `code` property).
+ */
+function isNodeError(err) {
+    return err instanceof Error && "code" in err;
+}

package/build/utils/decode-yaml.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Decode the base64-encoded ZIP returned by the FlutterFlow projectYamls API
+ * into a map of filename → YAML text.
+ *
+ * The API response shape is: { value: { projectYamlBytes: "<base64>" } }
+ */
+export declare function decodeProjectYamlResponse(apiResponse: unknown): Record<string, string>;

package/build/utils/decode-yaml.js

@@ -0,0 +1,31 @@
+import AdmZip from "adm-zip";
+/**
+ * Decode the base64-encoded ZIP returned by the FlutterFlow projectYamls API
+ * into a map of filename → YAML text.
+ *
+ * The API response shape is: { value: { projectYamlBytes: "<base64>" } }
+ */
+export function decodeProjectYamlResponse(apiResponse) {
+    const resp = apiResponse;
+    // API docs use camelCase (projectYamlBytes), but handle snake_case fallback
+    const b64 = resp?.value?.projectYamlBytes ?? resp?.value?.project_yaml_bytes;
+    if (!b64) {
+        throw new Error("Unexpected API response: missing value.projectYamlBytes");
+    }
+    const zipBuffer = Buffer.from(b64, "base64");
+    const zip = new AdmZip(zipBuffer);
+    const entries = zip.getEntries();
+    const result = {};
+    for (const entry of entries) {
+        if (!entry.isDirectory) {
+            try {
+                result[entry.entryName] = entry.getData().toString("utf-8");
+            }
+            catch {
+                // Skip entries that fail to decompress (e.g. buffer overflow on large pages)
+                console.error(`[decode-yaml] Failed to decompress entry: ${entry.entryName}`);
+            }
+        }
+    }
+    return result;
+}

package/build/utils/page-summary/action-summarizer.d.ts

@@ -0,0 +1,9 @@
+import { TriggerSummary } from "./types.js";
+/**
+ * Read all trigger_actions for a node and return summaries.
+ *
+ * @param projectId - FF project ID
+ * @param nodeFileKeyPrefix - Cache prefix for the node's trigger actions,
+ *   e.g. "page/id-Scaffold_xxx/page-widget-tree-outline/node/id-Button_yyy"
+ */
+export declare function summarizeTriggers(projectId: string, nodeFileKeyPrefix: string): Promise<TriggerSummary[]>;