flutterflow-mcp 0.1.0

package/build/tools/get-page-by-name.js

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { parseFolderMapping } from "../utils/parse-folders.js";
+import { extractPageFileKeys, fetchOneFile } from "./list-pages.js";
+export function registerGetPageByNameTool(server, client) {
+    server.tool("get_page_by_name", "Fetch a FlutterFlow page by its human-readable name (e.g. 'Welcome', 'GoldPass'). Resolves the name to the correct scaffold ID and returns the full page YAML. Case-insensitive matching.", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+        pageName: z
+            .string()
+            .describe("The human-readable page name (e.g. 'Welcome', 'GoldPass'). Case-insensitive."),
+    }, async ({ projectId, pageName }) => {
+        // Step 1: Get file list and folders (2 API calls)
+        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: Search pages sequentially until we find the name match
+        const searchName = pageName.toLowerCase();
+        const available = [];
+        for (const fileKey of pageFileKeys) {
+            const result = await fetchOneFile(client, projectId, fileKey);
+            if (!result)
+                continue;
+            const nameMatch = result.content.match(/^name:\s*(.+)$/m);
+            const name = nameMatch ? nameMatch[1].trim() : "";
+            if (name.toLowerCase() === searchName) {
+                const scaffoldMatch = fileKey.match(/^page\/id-(Scaffold_\w+)$/);
+                const scaffoldId = scaffoldMatch
+                    ? scaffoldMatch[1]
+                    : fileKey;
+                const folder = folderMap[scaffoldId] || "(unmapped)";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `# ${name} (${scaffoldId}) — folder: ${folder}\n# File key: ${fileKey}\n${result.content}`,
+                        },
+                    ],
+                };
+            }
+            if (name)
+                available.push(name);
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Page "${pageName}" not found. Available pages:\n${available.map((n) => `  - ${n}`).join("\n")}`,
+                },
+            ],
+        };
+    });
+}

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

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

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

@@ -0,0 +1,220 @@
+import { z } from "zod";
+import YAML from "yaml";
+import { cacheRead, cacheMeta, listCachedKeys, } from "../utils/cache.js";
+import { parseFolderMapping } from "../utils/parse-folders.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 { formatPageSummary } from "../utils/page-summary/formatter.js";
+/**
+ * Resolve a page name or scaffold ID to its cache file key.
+ * Returns all available page names if no match found.
+ */
+export async function resolvePage(projectId, pageName, scaffoldId) {
+    if (scaffoldId) {
+        const pageFileKey = `page/id-${scaffoldId}`;
+        const content = await cacheRead(projectId, pageFileKey);
+        if (content) {
+            return { ok: true, page: { scaffoldId, pageFileKey } };
+        }
+    }
+    // List all cached page top-level files
+    const allKeys = await listCachedKeys(projectId, "page/id-Scaffold_");
+    // Filter to top-level page files only (not sub-files)
+    const pageKeys = allKeys.filter((k) => /^page\/id-Scaffold_\w+$/.test(k));
+    const available = [];
+    for (const key of pageKeys) {
+        const content = await cacheRead(projectId, key);
+        if (!content)
+            continue;
+        const nameMatch = content.match(/^name:\s*(.+)$/m);
+        const name = nameMatch ? nameMatch[1].trim() : "";
+        if (pageName && name.toLowerCase() === pageName.toLowerCase()) {
+            const sid = key.match(/^page\/id-(Scaffold_\w+)$/)?.[1] || "";
+            return { ok: true, page: { scaffoldId: sid, pageFileKey: 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 page metadata (name, params, state) from the top-level page YAML. */
+async function extractPageMeta(projectId, page, folder) {
+    const content = await cacheRead(projectId, page.pageFileKey);
+    if (!content) {
+        return {
+            pageName: page.scaffoldId,
+            scaffoldId: page.scaffoldId,
+            folder,
+            params: [],
+            stateFields: [],
+        };
+    }
+    const doc = YAML.parse(content);
+    const pageName = doc.name || page.scaffoldId;
+    // 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,
+            });
+        }
+    }
+    // State fields
+    const stateFields = [];
+    const classModel = doc.classModel;
+    const rawFields = classModel?.stateFields;
+    if (Array.isArray(rawFields)) {
+        for (const field of rawFields) {
+            const param = field.parameter;
+            if (!param)
+                continue;
+            const id = param.identifier;
+            const name = id?.name || "unknown";
+            const dt = param.dataType || {};
+            const defaultVals = field.serializedDefaultValue;
+            stateFields.push({
+                name,
+                dataType: resolveDataType(dt),
+                defaultValue: defaultVals?.[0],
+            });
+        }
+    }
+    return { pageName, scaffoldId: page.scaffoldId, folder, params, stateFields };
+}
+// ---------------------------------------------------------------------------
+// Tree enrichment
+// ---------------------------------------------------------------------------
+/**
+ * Recursively enrich an OutlineNode tree with node info and trigger summaries.
+ */
+async function enrichNode(projectId, pagePrefix, // e.g. "page/id-Scaffold_xxx/page-widget-tree-outline"
+outline) {
+    const nodeInfo = await extractNodeInfo(projectId, pagePrefix, outline.key);
+    // Check for triggers
+    const nodeFilePrefix = `${pagePrefix}/node/id-${outline.key}`;
+    const triggers = await summarizeTriggers(projectId, nodeFilePrefix);
+    // Enrich children
+    const children = await Promise.all(outline.children.map((child) => enrichNode(projectId, pagePrefix, child)));
+    return {
+        key: outline.key,
+        type: nodeInfo.type,
+        name: nodeInfo.name,
+        slot: outline.slot,
+        detail: nodeInfo.detail,
+        triggers,
+        children,
+    };
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerGetPageSummaryTool(server) {
+    server.tool("get_page_summary", "Get a readable summary of a FlutterFlow page from local cache — widget tree, actions, params, state. No API calls. Run sync_project first if not cached.", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+        pageName: z
+            .string()
+            .optional()
+            .describe("Human-readable page name (e.g. 'PaywallPage'). Case-insensitive. Provide either pageName or scaffoldId."),
+        scaffoldId: z
+            .string()
+            .optional()
+            .describe("Scaffold ID (e.g. 'Scaffold_tydsj8ql'). Provide either pageName or scaffoldId."),
+    }, async ({ projectId, pageName, scaffoldId }) => {
+        // 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 (!pageName && !scaffoldId) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Provide either pageName or scaffoldId.",
+                    },
+                ],
+            };
+        }
+        // Resolve page
+        const resolved = await resolvePage(projectId, pageName, scaffoldId);
+        if (!resolved.ok) {
+            const list = resolved.available.map((n) => `  - ${n}`).join("\n");
+            const searchTerm = pageName || scaffoldId || "";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Page "${searchTerm}" not found in cache. Available pages:\n${list}`,
+                    },
+                ],
+            };
+        }
+        const page = resolved.page;
+        // Get folder mapping
+        const foldersContent = await cacheRead(projectId, "folders");
+        const folderMap = foldersContent
+            ? parseFolderMapping(foldersContent)
+            : {};
+        const folder = folderMap[page.scaffoldId] || "(unmapped)";
+        // Extract metadata
+        const pageMeta = await extractPageMeta(projectId, page, folder);
+        // Parse widget tree outline
+        const outlineKey = `${page.pageFileKey}/page-widget-tree-outline`;
+        const outlineContent = await cacheRead(projectId, outlineKey);
+        if (!outlineContent) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Page "${pageMeta.pageName}" 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 = formatPageSummary(pageMeta, enrichedTree);
+        return {
+            content: [{ type: "text", text: summary }],
+        };
+    });
+}

package/build/tools/get-yaml-docs.d.ts

@@ -0,0 +1,6 @@
+/**
+ * get_yaml_docs tool — search and retrieve FlutterFlow YAML reference documentation.
+ * No API calls: reads from bundled docs/ff-yaml/ directory.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerGetYamlDocsTool(server: McpServer): void;

package/build/tools/get-yaml-docs.js

@@ -0,0 +1,217 @@
+import { z } from "zod";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const DOCS_DIR = path.resolve(__dirname, "../../docs/ff-yaml");
+/** Topic-to-file mapping for fuzzy search. */
+const TOPIC_MAP = {
+    // Widgets
+    button: "04-widgets/button.md",
+    iconbutton: "04-widgets/button.md",
+    text: "04-widgets/text.md",
+    richtext: "04-widgets/text.md",
+    richtextspan: "04-widgets/text.md",
+    textfield: "04-widgets/text-field.md",
+    "text-field": "04-widgets/text-field.md",
+    input: "04-widgets/text-field.md",
+    container: "04-widgets/container.md",
+    boxdecoration: "04-widgets/container.md",
+    column: "04-widgets/layout.md",
+    row: "04-widgets/layout.md",
+    stack: "04-widgets/layout.md",
+    wrap: "04-widgets/layout.md",
+    layout: "04-widgets/layout.md",
+    image: "04-widgets/image.md",
+    form: "04-widgets/form.md",
+    validation: "04-widgets/form.md",
+    dropdown: "04-widgets/dropdown.md",
+    choicechips: "04-widgets/dropdown.md",
+    icon: "04-widgets/misc.md",
+    progressbar: "04-widgets/misc.md",
+    appbar: "04-widgets/misc.md",
+    conditionalbuilder: "04-widgets/misc.md",
+    widget: "04-widgets/README.md",
+    widgets: "04-widgets/README.md",
+    // Non-widget topics
+    actions: "05-actions.md",
+    action: "05-actions.md",
+    trigger: "05-actions.md",
+    navigate: "05-actions.md",
+    navigation: "05-actions.md",
+    ontap: "05-actions.md",
+    variables: "06-variables.md",
+    variable: "06-variables.md",
+    binding: "06-variables.md",
+    "data-binding": "06-variables.md",
+    data: "07-data.md",
+    collections: "07-data.md",
+    firestore: "07-data.md",
+    api: "07-data.md",
+    custom: "08-custom-code.md",
+    dart: "08-custom-code.md",
+    "custom-code": "08-custom-code.md",
+    theme: "09-theming.md",
+    theming: "09-theming.md",
+    color: "09-theming.md",
+    colors: "09-theming.md",
+    font: "09-theming.md",
+    typography: "09-theming.md",
+    editing: "10-editing-guide.md",
+    workflow: "10-editing-guide.md",
+    "editing-guide": "10-editing-guide.md",
+    push: "10-editing-guide.md",
+    overview: "00-overview.md",
+    structure: "00-overview.md",
+    "project-files": "01-project-files.md",
+    config: "01-project-files.md",
+    settings: "01-project-files.md",
+    pages: "02-pages.md",
+    page: "02-pages.md",
+    scaffold: "02-pages.md",
+    components: "03-components.md",
+    component: "03-components.md",
+    // Universal patterns
+    inputvalue: "README.md",
+    mostrecentinputvalue: "README.md",
+    padding: "README.md",
+    "border-radius": "README.md",
+};
+/** List all doc files recursively. */
+function listDocFiles(dir, prefix = "") {
+    const results = [];
+    if (!fs.existsSync(dir))
+        return results;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            results.push(...listDocFiles(path.join(dir, entry.name), relPath));
+        }
+        else if (entry.name.endsWith(".md")) {
+            results.push(relPath);
+        }
+    }
+    return results;
+}
+/** Read a doc file. Returns null if not found. */
+function readDoc(relPath) {
+    const filePath = path.join(DOCS_DIR, relPath);
+    if (!fs.existsSync(filePath))
+        return null;
+    return fs.readFileSync(filePath, "utf-8");
+}
+export function registerGetYamlDocsTool(server) {
+    server.tool("get_yaml_docs", "Search and retrieve FlutterFlow YAML reference documentation. Use `topic` to search by keyword (e.g. 'Button', 'actions', 'theming') or `file` to fetch a specific doc file. Returns the full doc content.", {
+        topic: z
+            .string()
+            .optional()
+            .describe("Search topic/keyword (e.g. 'Button', 'actions', 'theme', 'Column', 'variables'). Case-insensitive."),
+        file: z
+            .string()
+            .optional()
+            .describe("Specific doc file path (e.g. '04-widgets/button', '05-actions', 'README'). Omit .md extension."),
+    }, async ({ topic, file }) => {
+        // Direct file access
+        if (file) {
+            const content = readDoc(`${file}.md`);
+            if (content) {
+                return {
+                    content: [{ type: "text", text: content }],
+                };
+            }
+            const available = listDocFiles(DOCS_DIR)
+                .map((f) => `  - ${f.replace(/\.md$/, "")}`)
+                .join("\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Doc file not found: "${file}"\n\nAvailable files:\n${available}`,
+                    },
+                ],
+            };
+        }
+        // Topic search
+        if (topic) {
+            const key = topic.toLowerCase().replace(/[\s_-]+/g, "");
+            const matchedFile = TOPIC_MAP[key];
+            if (matchedFile) {
+                const content = readDoc(matchedFile);
+                if (content) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `# Matched: ${matchedFile}\n\n${content}`,
+                            },
+                        ],
+                    };
+                }
+            }
+            // Fallback: scan filenames and file contents for the topic
+            const allFiles = listDocFiles(DOCS_DIR);
+            const matches = [];
+            for (const f of allFiles) {
+                // Check filename match
+                if (f.toLowerCase().includes(topic.toLowerCase())) {
+                    matches.push(f);
+                    continue;
+                }
+                // Check content match (first-level scan)
+                const content = readDoc(f);
+                if (content &&
+                    content.toLowerCase().includes(topic.toLowerCase())) {
+                    matches.push(f);
+                }
+            }
+            if (matches.length === 0) {
+                const available = allFiles
+                    .map((f) => `  - ${f.replace(/\.md$/, "")}`)
+                    .join("\n");
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No docs found for topic "${topic}".\n\nAvailable docs:\n${available}`,
+                        },
+                    ],
+                };
+            }
+            // Return the first match content, list others
+            const primary = readDoc(matches[0]) || "";
+            const others = matches.length > 1
+                ? `\n\n---\n\nOther matching docs:\n${matches
+                    .slice(1)
+                    .map((f) => `  - ${f.replace(/\.md$/, "")}`)
+                    .join("\n")}`
+                : "";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `# Matched: ${matches[0]}\n\n${primary}${others}`,
+                    },
+                ],
+            };
+        }
+        // No params: return index
+        const readme = readDoc("README.md");
+        if (readme) {
+            return {
+                content: [{ type: "text", text: readme }],
+            };
+        }
+        const available = listDocFiles(DOCS_DIR)
+            .map((f) => `  - ${f.replace(/\.md$/, "")}`)
+            .join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `FlutterFlow YAML Reference Docs:\n${available}\n\nUse the 'topic' or 'file' parameter to fetch specific docs.`,
+                },
+            ],
+        };
+    });
+}

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

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

package/build/tools/get-yaml.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { decodeProjectYamlResponse } from "../utils/decode-yaml.js";
+import { cacheRead, cacheWrite } from "../utils/cache.js";
+export function registerGetYamlTool(server, client) {
+    server.tool("get_project_yaml", "Download YAML files from a FlutterFlow project. Returns one file if fileName is specified, otherwise returns all files.", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+        fileName: z
+            .string()
+            .optional()
+            .describe("Specific YAML file name to download (e.g. 'app-details', 'page/id-xxx'). Omit to get all files."),
+    }, async ({ projectId, fileName }) => {
+        // Cache-first for single-file requests
+        if (fileName) {
+            const cached = await cacheRead(projectId, fileName);
+            if (cached) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `# ${fileName} (cached)\n${cached}`,
+                        },
+                    ],
+                };
+            }
+        }
+        const raw = await client.getProjectYamls(projectId, fileName);
+        const decoded = decodeProjectYamlResponse(raw);
+        // Write fetched results to cache (strip .yaml from ZIP entry names to avoid double extension)
+        for (const [name, yaml] of Object.entries(decoded)) {
+            const cleanName = name.endsWith(".yaml") ? name.slice(0, -".yaml".length) : name;
+            await cacheWrite(projectId, cleanName, yaml);
+        }
+        const entries = Object.entries(decoded);
+        if (entries.length === 1) {
+            const [name, yaml] = entries[0];
+            return {
+                content: [{ type: "text", text: `# ${name}\n${yaml}` }],
+            };
+        }
+        return {
+            content: entries.map(([name, yaml]) => ({
+                type: "text",
+                text: `# ${name}\n${yaml}`,
+            })),
+        };
+    });
+}

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

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

package/build/tools/list-files.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { listCachedKeys, cacheMeta } from "../utils/cache.js";
+export function registerListFilesTool(server, client) {
+    server.tool("list_project_files", "List all YAML file names in a FlutterFlow project", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+    }, async ({ projectId }) => {
+        // If cache exists, return file keys from cache
+        const meta = await cacheMeta(projectId);
+        if (meta) {
+            const keys = await listCachedKeys(projectId);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ value: { file_names: keys }, source: "cache", syncedAt: meta.lastSyncedAt }, null, 2),
+                    },
+                ],
+            };
+        }
+        const result = await client.listPartitionedFileNames(projectId);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    });
+}

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

@@ -0,0 +1,25 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { FlutterFlowClient } from "../api/flutterflow.js";
+export interface PageInfo {
+    scaffoldId: string;
+    name: string;
+    folder: string;
+    fileKey: string;
+}
+/**
+ * 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 declare function extractPageFileKeys(fileNames: unknown): string[];
+/**
+ * Fetch a single YAML file and decode it. Returns null on failure.
+ */
+export declare function fetchOneFile(client: FlutterFlowClient, projectId: string, fileName: string): Promise<{
+    fileKey: string;
+    content: string;
+} | null>;
+/**
+ * Extract a compact page index by fetching pages in batches.
+ */
+export declare function listPages(client: FlutterFlowClient, projectId: string): Promise<PageInfo[]>;
+export declare function registerListPagesTool(server: McpServer, client: FlutterFlowClient): void;