community-ff-mcp 0.4.0

package/build/tools/sync-project.js

@@ -0,0 +1,147 @@
+import { z } from "zod";
+import { decodeProjectYamlResponse } from "../utils/decode-yaml.js";
+import { cacheWriteBulk, cacheWriteMeta, cacheWrite, cacheMeta, cacheClear, } 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),
+                        },
+                    ],
+                };
+            }
+        }
+        // Clear stale cache before re-syncing so files that no longer exist
+        // on the server are removed instead of persisting as stale data.
+        await cacheClear(projectId);
+        // 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. For best results, call get_editing_guide before writing YAML to get the correct workflow and schema documentation.", {
+        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,39 @@
+import { z } from "zod";
+/** Extract widget type from a node-level fileKey, e.g. "Button" from "node/id-Button_xyz" */
+function extractWidgetTypeFromFileKey(fileKey) {
+    const match = fileKey.match(/node\/id-([A-Z][a-zA-Z]+)_/);
+    return match ? match[1] : null;
+}
+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. Tip: Call get_editing_guide or get_yaml_docs BEFORE writing YAML to understand the correct schema and field names. Validation catches syntax errors but not semantic mistakes.", {
+        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);
+        let text = JSON.stringify(result, null, 2);
+        // Add doc hint on validation failure
+        const isFailure = result && typeof result === "object" && result.valid === false;
+        if (isFailure) {
+            const widgetType = extractWidgetTypeFromFileKey(fileKey);
+            if (widgetType) {
+                text += `\n\nHint: Use get_yaml_docs(topic: "${widgetType}") to look up the correct field schema for ${widgetType} widgets.`;
+            }
+            else {
+                text += `\n\nHint: Use get_yaml_docs to look up the correct YAML schema for the file you're editing.`;
+            }
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text,
+                },
+            ],
+        };
+    });
+}

package/build/utils/batch-process.d.ts

@@ -0,0 +1,2 @@
+/** Batch-process items in groups to avoid overwhelming the file system. */
+export declare function batchProcess<T, R>(items: T[], batchSize: number, fn: (item: T) => Promise<R>): Promise<R[]>;

package/build/utils/batch-process.js

@@ -0,0 +1,10 @@
+/** Batch-process items in groups to avoid overwhelming the file system. */
+export 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.all(batch.map(fn));
+        results.push(...batchResults);
+    }
+    return results;
+}

package/build/utils/cache.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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>;
+/**
+ * Delete the entire cache directory for a project, removing all cached files
+ * and metadata. No-op if the directory does not exist.
+ */
+export declare function cacheClear(projectId: 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[]>;
+/**
+ * Format a human-readable footer indicating cache age.
+ * Appended to cache-based tool responses so the AI can judge staleness.
+ */
+export declare function cacheAgeFooter(meta: CacheMeta): string;

package/build/utils/cache.js

@@ -0,0 +1,199 @@
+import { mkdir, readFile, writeFile, unlink, readdir, rm } 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;
+    }
+}
+/**
+ * Delete the entire cache directory for a project, removing all cached files
+ * and metadata. No-op if the directory does not exist.
+ */
+export async function cacheClear(projectId) {
+    try {
+        await rm(cacheDir(projectId), { recursive: true, force: true });
+    }
+    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;
+}
+// ---------------------------------------------------------------------------
+// Cache age footer
+// ---------------------------------------------------------------------------
+/**
+ * Format a human-readable footer indicating cache age.
+ * Appended to cache-based tool responses so the AI can judge staleness.
+ */
+export function cacheAgeFooter(meta) {
+    const syncedAt = new Date(meta.lastSyncedAt);
+    const diffMs = Date.now() - syncedAt.getTime();
+    const diffMin = Math.floor(diffMs / 60_000);
+    let ago;
+    if (diffMin < 1)
+        ago = "just now";
+    else if (diffMin < 60)
+        ago = `${diffMin} min ago`;
+    else if (diffMin < 1440)
+        ago = `${Math.floor(diffMin / 60)}h ${diffMin % 60}m ago`;
+    else
+        ago = `${Math.floor(diffMin / 1440)}d ago`;
+    return `\n\n---\n_Synced: ${meta.lastSyncedAt} (${ago}). Call sync_project to refresh._`;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * 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,24 @@
+import { ActionSummary, TriggerSummary } from "./types.js";
+/**
+ * Collect all action keys referenced in a trigger chain.
+ * Flattens followUpAction chains, conditionActions, and parallelActions.
+ */
+export declare function collectActionKeys(node: Record<string, unknown>): string[];
+/**
+ * Recursively search an object tree for the first recognizable action.
+ * Used to unwrap disableAction nodes where the real action is buried
+ * inside conditionalActions or other nesting.
+ */
+export declare function findDeepAction(obj: unknown, depth?: number): ActionSummary | null;
+/**
+ * Classify an action YAML into a human-readable summary.
+ */
+export declare function classifyAction(doc: Record<string, unknown>): ActionSummary;
+/**
+ * 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[]>;