community-ff-mcp 0.4.0

package/build/tools/get-theme.js

@@ -0,0 +1,199 @@
+import { z } from "zod";
+import YAML from "yaml";
+import { cacheRead, cacheMeta, cacheAgeFooter } from "../utils/cache.js";
+function argbToHex(argbStr) {
+    const n = parseInt(argbStr, 10);
+    if (isNaN(n))
+        return argbStr;
+    const a = (n >>> 24) & 0xff;
+    const r = (n >>> 16) & 0xff;
+    const g = (n >>> 8) & 0xff;
+    const b = n & 0xff;
+    if (a === 255) {
+        return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`.toUpperCase();
+    }
+    return `#${a.toString(16).padStart(2, "0")}${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`.toUpperCase();
+}
+export function registerGetThemeTool(server) {
+    server.tool("get_theme", "Get theme colors, typography, breakpoints, and widget defaults from local cache. No API calls. Run sync_project first if not cached.", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+        section: z
+            .enum(["colors", "typography", "breakpoints", "widgets", "all"])
+            .default("all")
+            .describe("Which theme section to return. Defaults to 'all'."),
+    }, async ({ projectId, section }) => {
+        const meta = await cacheMeta(projectId);
+        if (!meta) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No cache found for project "${projectId}". Run sync_project first.`,
+                    },
+                ],
+            };
+        }
+        const [themeRaw, materialThemeRaw] = await Promise.all([
+            cacheRead(projectId, "theme"),
+            cacheRead(projectId, "material-theme"),
+        ]);
+        if (!themeRaw) {
+            return {
+                content: [
+                    { type: "text", text: "No theme data found in cache." },
+                ],
+            };
+        }
+        const theme = YAML.parse(themeRaw);
+        const sections = ["# Theme"];
+        // Material version
+        if (materialThemeRaw) {
+            const materialTheme = YAML.parse(materialThemeRaw);
+            const useMaterial2 = materialTheme.useMaterial2 === true;
+            sections.push(`\nMaterial version: Material ${useMaterial2 ? "2" : "3"}`);
+        }
+        const show = (s) => section === "all" || section === s;
+        // --- Colors ---
+        if (show("colors")) {
+            const colors = extractColors(theme);
+            if (colors.length > 0) {
+                sections.push("\n## Colors");
+                for (const { name, hex } of colors) {
+                    sections.push(`- ${name}: ${hex}`);
+                }
+            }
+        }
+        // --- Typography ---
+        if (show("typography")) {
+            const defaultTypography = theme.defaultTypography;
+            if (defaultTypography) {
+                const primaryFont = defaultTypography.primaryFontFamily || "Unknown";
+                const secondaryFont = defaultTypography.secondaryFontFamily || "Unknown";
+                sections.push("\n## Typography", `Primary font: ${primaryFont}`, `Secondary font: ${secondaryFont}`, "", "| Style | Size | Weight | Color |", "|-------|------|--------|-------|");
+                const styleKeys = [
+                    "displayLarge", "displayMedium", "displaySmall",
+                    "headlineLarge", "headlineMedium", "headlineSmall",
+                    "titleLarge", "titleMedium", "titleSmall",
+                    "bodyLarge", "bodyMedium", "bodySmall",
+                    "labelLarge", "labelMedium", "labelSmall",
+                ];
+                for (const key of styleKeys) {
+                    const style = defaultTypography[key];
+                    if (!style)
+                        continue;
+                    const size = style.fontSizeValue?.inputValue ?? "?";
+                    const weight = style.fontWeightValue?.inputValue ?? "?";
+                    const color = style.colorValue?.inputValue?.themeColor ?? "?";
+                    sections.push(`| ${key} | ${size} | ${weight} | ${color} |`);
+                }
+            }
+        }
+        // --- Breakpoints ---
+        if (show("breakpoints")) {
+            const bp = theme.breakPoints;
+            if (bp) {
+                const small = bp.small ?? 479;
+                const medium = bp.medium ?? 767;
+                const large = bp.large ?? 991;
+                sections.push("\n## Breakpoints", `- Phone: 0 - ${small}px`, `- Tablet: ${small + 1} - ${medium}px`, `- Tablet landscape: ${medium + 1} - ${large}px`, `- Desktop: ${large + 1}px+`);
+            }
+        }
+        // --- Widget Defaults ---
+        if (show("widgets")) {
+            const themeWidgets = theme.themeWidgets;
+            if (themeWidgets) {
+                sections.push("\n## Widget Defaults");
+                for (const [widgetName, widget] of Object.entries(themeWidgets)) {
+                    sections.push(`\n### ${widgetName}`);
+                    formatWidgetDefaults(widget, sections);
+                }
+            }
+            const scrollbar = theme.scrollbarTheme;
+            if (scrollbar) {
+                sections.push("\n### scrollbarTheme");
+                if (scrollbar.thickness !== undefined)
+                    sections.push(`Thickness: ${scrollbar.thickness}`);
+                if (scrollbar.radius !== undefined)
+                    sections.push(`Radius: ${scrollbar.radius}`);
+                const thumbColor = scrollbar.thumbColor;
+                if (thumbColor?.value) {
+                    sections.push(`Thumb color: ${argbToHex(thumbColor.value)}`);
+                }
+            }
+        }
+        return {
+            content: [{ type: "text", text: sections.join("\n") + cacheAgeFooter(meta) }],
+        };
+    });
+}
+function extractColors(theme) {
+    const results = [];
+    for (const [key, val] of Object.entries(theme)) {
+        if (val &&
+            typeof val === "object" &&
+            !Array.isArray(val)) {
+            const obj = val;
+            // Check if this is a single color entry: { value: "<argb>" }
+            if (typeof obj.value === "string" &&
+                Object.keys(obj).length <= 2 &&
+                isArgbColor(obj.value)) {
+                results.push({ name: key, hex: argbToHex(obj.value) });
+                continue;
+            }
+            // Check if this is a map of colors: { COLOR_NAME: { value: "<argb>" }, ... }
+            const childEntries = Object.entries(obj);
+            const colorChildren = [];
+            for (const [childKey, childVal] of childEntries) {
+                if (childVal &&
+                    typeof childVal === "object" &&
+                    !Array.isArray(childVal)) {
+                    const child = childVal;
+                    if (typeof child.value === "string" && isArgbColor(child.value)) {
+                        colorChildren.push({ name: childKey, hex: argbToHex(child.value) });
+                    }
+                }
+            }
+            if (colorChildren.length >= 3) {
+                results.push(...colorChildren);
+            }
+        }
+    }
+    return results;
+}
+function isArgbColor(value) {
+    const n = parseInt(value, 10);
+    return !isNaN(n) && n > 0xff000000;
+}
+function formatWidgetDefaults(widget, out) {
+    if (widget.fontFamily)
+        out.push(`Font: ${widget.fontFamily}`);
+    const textStyle = widget.textStyle;
+    if (textStyle?.themeStyle)
+        out.push(`Text style: ${textStyle.themeStyle}`);
+    const textColor = widget.textColorValue;
+    const textColorInput = textColor?.inputValue;
+    if (textColorInput?.themeColor)
+        out.push(`Text color: ${textColorInput.themeColor}`);
+    const bgColor = widget.backgroundColorValue;
+    const bgInput = bgColor?.inputValue;
+    if (bgInput?.themeColor)
+        out.push(`Background: ${bgInput.themeColor}`);
+    const borderRadius = widget.borderRadius;
+    if (borderRadius) {
+        const allVal = borderRadius.allValue;
+        if (allVal?.inputValue !== undefined) {
+            out.push(`Border radius: ${allVal.inputValue}`);
+        }
+    }
+    const dimensions = widget.dimensions;
+    if (dimensions) {
+        const height = dimensions.height;
+        const heightPx = height?.pixelsValue;
+        if (heightPx?.inputValue !== undefined)
+            out.push(`Height: ${heightPx.inputValue}px`);
+        const width = dimensions.width;
+        const widthPx = width?.pixelsValue;
+        if (widthPx?.inputValue !== undefined)
+            out.push(`Width: ${widthPx.inputValue}px`);
+    }
+}

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,116 @@
+import { z } from "zod";
+import { TOPIC_MAP, DOCS_DIR, listDocFiles, readDoc } from "../utils/topic-map.js";
+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,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerGetYamlTool(server: McpServer): void;

package/build/tools/get-yaml.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { cacheRead, listCachedKeys } from "../utils/cache.js";
+export function registerGetYamlTool(server) {
+    server.tool("get_project_yaml", "Read YAML files from the local project cache. Requires sync_project to be run first. Returns one file if fileName is specified, or lists all cached file keys if omitted.", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+        fileName: z
+            .string()
+            .optional()
+            .describe("Specific YAML file name to read (e.g. 'app-details', 'page/id-xxx'). Omit to list all cached file keys."),
+    }, async ({ projectId, fileName }) => {
+        if (fileName) {
+            const cached = await cacheRead(projectId, fileName);
+            if (cached) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `# ${fileName}\n${cached}`,
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `File "${fileName}" not found in local cache for project "${projectId}". Run sync_project(projectId: "${projectId}") first to download all YAML files, then retry.`,
+                    },
+                ],
+            };
+        }
+        // No fileName: list all cached keys
+        const keys = await listCachedKeys(projectId);
+        if (keys.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No cached files found for project "${projectId}". Run sync_project(projectId: "${projectId}") first to download all YAML files.`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `# Cached files (${keys.length})\n${keys.join("\n")}`,
+                },
+            ],
+        };
+    });
+}

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,49 @@
+import { z } from "zod";
+import { listCachedKeys, cacheMeta, cacheAgeFooter } from "../utils/cache.js";
+export function registerListFilesTool(server, client) {
+    server.tool("list_project_files", "List all YAML file names in a FlutterFlow project. Supports optional prefix filter (e.g. 'page/', 'component/') to narrow results.", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+        prefix: z.string().optional().describe("Optional prefix to filter file keys (e.g. 'page/', 'custom-file/')"),
+    }, async ({ projectId, prefix }) => {
+        // If cache exists, return file keys from cache
+        const meta = await cacheMeta(projectId);
+        if (meta) {
+            const keys = prefix
+                ? await listCachedKeys(projectId, prefix)
+                : await listCachedKeys(projectId);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ value: { file_names: keys }, source: "cache", syncedAt: meta.lastSyncedAt }, null, 2) + cacheAgeFooter(meta),
+                    },
+                ],
+            };
+        }
+        const result = await client.listPartitionedFileNames(projectId);
+        // Apply client-side prefix filter when falling back to API
+        if (prefix) {
+            const apiResult = result;
+            const allKeys = apiResult?.value?.file_names;
+            if (Array.isArray(allKeys)) {
+                const filtered = allKeys.filter((k) => k.startsWith(prefix));
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ value: { file_names: filtered } }, null, 2),
+                        },
+                    ],
+                };
+            }
+        }
+        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;

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,23 @@
+import { z } from "zod";
+export function registerListProjectsTool(server, client) {
+    server.tool("list_projects", "List FlutterFlow projects for the authenticated user. NOTE: This may not return all projects you have access to (shared/team projects can be missing). If a project is missing, copy its ID directly from the FlutterFlow editor (click the project name in the top-left corner).", {
+        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),
+                },
+                {
+                    type: "text",
+                    text: "\n---\n**Tip:** This list may not include all projects you have access to (shared/team projects can be missing). If you don't see a project here, copy its ID directly from the FlutterFlow editor: click the project name (top-left corner) and copy the project ID.",
+                },
+            ],
+        };
+    });
+}

package/build/tools/search-project-files.d.ts

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

package/build/tools/search-project-files.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { cacheMeta, listCachedKeys, cacheAgeFooter } from "../utils/cache.js";
+const MAX_RESULTS = 100;
+export function registerSearchProjectFilesTool(server) {
+    server.tool("search_project_files", "Search cached project file keys by keyword, prefix, or regex. Returns matching file keys for use with get_project_yaml. Cache-only, no API calls. Run sync_project first.", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+        query: z.string().describe("Search query string"),
+        mode: z
+            .enum(["prefix", "contains", "regex"])
+            .default("contains")
+            .describe("Search mode: prefix (startsWith), contains (case-insensitive includes), or regex (case-insensitive RegExp)"),
+    }, async ({ projectId, query, mode }) => {
+        const meta = await cacheMeta(projectId);
+        if (!meta) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No cache found for project "${projectId}". Run sync_project first.`,
+                    },
+                ],
+            };
+        }
+        const allKeys = await listCachedKeys(projectId);
+        let matched;
+        switch (mode) {
+            case "prefix":
+                matched = allKeys.filter((k) => k.startsWith(query));
+                break;
+            case "regex": {
+                const re = new RegExp(query, "i");
+                matched = allKeys.filter((k) => re.test(k));
+                break;
+            }
+            case "contains":
+            default: {
+                const lowerQuery = query.toLowerCase();
+                matched = allKeys.filter((k) => k.toLowerCase().includes(lowerQuery));
+                break;
+            }
+        }
+        if (matched.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No files found matching "${query}" (mode: ${mode}).`,
+                    },
+                ],
+            };
+        }
+        const total = matched.length;
+        const truncated = total > MAX_RESULTS;
+        const displayed = truncated ? matched.slice(0, MAX_RESULTS) : matched;
+        const lines = [];
+        if (truncated) {
+            lines.push(`Found ${MAX_RESULTS} of ${total} files matching "${query}" (showing first ${MAX_RESULTS}):`);
+        }
+        else {
+            lines.push(`Found ${total} files matching "${query}":`);
+        }
+        for (const key of displayed) {
+            lines.push(`- ${key}`);
+        }
+        return {
+            content: [{ type: "text", text: lines.join("\n") + cacheAgeFooter(meta) }],
+        };
+    });
+}

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;