community-ff-mcp 0.4.0

package/build/resources/docs.js

@@ -0,0 +1,76 @@
+import { ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
+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");
+/** Recursively list all .md files under a directory, returning relative paths. */
+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;
+}
+export function registerDocsResources(server) {
+    // Static resource: list all available docs
+    server.resource("docs-index", "ff://docs", {
+        description: "FlutterFlow YAML reference catalog — list all available documentation files",
+        mimeType: "application/json",
+    }, async (uri) => {
+        const files = listDocFiles(DOCS_DIR);
+        const index = files.map((f) => ({
+            file: f.replace(/\.md$/, ""),
+            uri: `ff://docs/${f.replace(/\.md$/, "")}`,
+        }));
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: JSON.stringify(index, null, 2),
+                    mimeType: "application/json",
+                },
+            ],
+        };
+    });
+    // Dynamic resource: get a specific doc file
+    server.resource("docs-file", new ResourceTemplate("ff://docs/{+path}", { list: undefined }), {
+        description: "Read a specific FlutterFlow YAML reference doc (e.g. ff://docs/04-widgets/button)",
+        mimeType: "text/markdown",
+    }, async (uri, { path: docPath }) => {
+        const filePath = path.join(DOCS_DIR, `${docPath}.md`);
+        if (!fs.existsSync(filePath)) {
+            const available = listDocFiles(DOCS_DIR)
+                .map((f) => f.replace(/\.md$/, ""))
+                .join("\n  ");
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        text: `Doc not found: ${docPath}\n\nAvailable docs:\n  ${available}`,
+                        mimeType: "text/plain",
+                    },
+                ],
+            };
+        }
+        const content = fs.readFileSync(filePath, "utf-8");
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: content,
+                    mimeType: "text/markdown",
+                },
+            ],
+        };
+    });
+}

package/build/resources/projects.d.ts

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

package/build/resources/projects.js

@@ -0,0 +1,60 @@
+import { ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { decodeProjectYamlResponse } from "../utils/decode-yaml.js";
+export function registerResources(server, client) {
+    // Static resource: list all projects
+    server.resource("projects", "ff://projects", {
+        description: "List all FlutterFlow projects",
+        mimeType: "application/json",
+    }, async (uri) => {
+        const projects = await client.listProjects();
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: JSON.stringify(projects, null, 2),
+                    mimeType: "application/json",
+                },
+            ],
+        };
+    });
+    // Dynamic resource: list files in a project
+    server.resource("project-files", new ResourceTemplate("ff://projects/{projectId}/files", {
+        list: undefined,
+    }), {
+        description: "List YAML file names in a FlutterFlow project",
+        mimeType: "application/json",
+    }, async (uri, { projectId }) => {
+        const files = await client.listPartitionedFileNames(projectId);
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: JSON.stringify(files, null, 2),
+                    mimeType: "application/json",
+                },
+            ],
+        };
+    });
+    // Dynamic resource: get specific YAML file
+    server.resource("project-yaml", new ResourceTemplate("ff://projects/{projectId}/yaml/{+fileName}", {
+        list: undefined,
+    }), {
+        description: "Get a specific YAML file from a FlutterFlow project",
+        mimeType: "text/yaml",
+    }, async (uri, { projectId, fileName }) => {
+        const raw = await client.getProjectYamls(projectId, fileName);
+        const decoded = decodeProjectYamlResponse(raw);
+        const yamlText = Object.entries(decoded)
+            .map(([name, content]) => `# ${name}\n${content}`)
+            .join("\n");
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: yamlText,
+                    mimeType: "text/yaml",
+                },
+            ],
+        };
+    });
+}

package/build/tools/find-component-usages.d.ts

@@ -0,0 +1,21 @@
+/**
+ * find_component_usages tool — scans cached node files to find all pages and
+ * components where a given component is instantiated.
+ * Zero API calls: everything comes from the local .ff-cache.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Resolve the value of a parameter pass to a readable string.
+ */
+export declare function resolveParamValue(paramObj: Record<string, unknown>): string;
+/**
+ * Extract parent context (page or component name + ID) from a file key path.
+ * Examples:
+ *   "page/id-Scaffold_xxx/page-widget-tree-outline/node/id-Widget_yyy"
+ *   "component/id-Container_xxx/component-widget-tree-outline/node/id-Widget_yyy"
+ */
+export declare function parseParentFromKey(fileKey: string): {
+    type: "page" | "component";
+    id: string;
+} | null;
+export declare function registerFindComponentUsagesTool(server: McpServer): void;

package/build/tools/find-component-usages.js

@@ -0,0 +1,216 @@
+import { z } from "zod";
+import YAML from "yaml";
+import { cacheRead, cacheMeta, cacheAgeFooter, listCachedKeys, } from "../utils/cache.js";
+import { resolveComponent } from "./get-component-summary.js";
+import { batchProcess } from "../utils/batch-process.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the value of a parameter pass to a readable string.
+ */
+export function resolveParamValue(paramObj) {
+    // Check for variable source (e.g. INTERNATIONALIZATION)
+    const variable = paramObj.variable;
+    if (variable) {
+        const source = variable.source;
+        if (source === "INTERNATIONALIZATION") {
+            const fc = variable.functionCall;
+            const values = fc?.values;
+            if (values && values.length > 0) {
+                const first = values[0];
+                const iv = first.inputValue;
+                const sv = iv?.serializedValue;
+                return sv ? `"${sv}" (i18n)` : "[i18n]";
+            }
+            return "[i18n]";
+        }
+        if (source)
+            return `[${source}]`;
+        return "[dynamic]";
+    }
+    // Check for inputValue
+    const inputValue = paramObj.inputValue;
+    if (inputValue != null) {
+        if (typeof inputValue === "string" || typeof inputValue === "number") {
+            return `"${inputValue}"`;
+        }
+        if (typeof inputValue === "object") {
+            const ivo = inputValue;
+            if ("serializedValue" in ivo)
+                return `"${ivo.serializedValue}"`;
+            if ("themeColor" in ivo)
+                return `[theme:${ivo.themeColor}]`;
+        }
+    }
+    return "[dynamic]";
+}
+/**
+ * Extract parent context (page or component name + ID) from a file key path.
+ * Examples:
+ *   "page/id-Scaffold_xxx/page-widget-tree-outline/node/id-Widget_yyy"
+ *   "component/id-Container_xxx/component-widget-tree-outline/node/id-Widget_yyy"
+ */
+export function parseParentFromKey(fileKey) {
+    const pageMatch = fileKey.match(/^page\/id-(Scaffold_\w+)\//);
+    if (pageMatch)
+        return { type: "page", id: pageMatch[1] };
+    const compMatch = fileKey.match(/^component\/id-(Container_\w+)\//);
+    if (compMatch)
+        return { type: "component", id: compMatch[1] };
+    return null;
+}
+/**
+ * Resolve the name of a page or component from its top-level YAML cache.
+ */
+async function resolveParentName(projectId, parentType, parentId) {
+    const prefix = parentType === "page" ? "page" : "component";
+    const fileKey = `${prefix}/id-${parentId}`;
+    const content = await cacheRead(projectId, fileKey);
+    if (!content)
+        return parentId;
+    const nameMatch = content.match(/^name:\s*(.+)$/m);
+    return nameMatch ? nameMatch[1].trim() : parentId;
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerFindComponentUsagesTool(server) {
+    server.tool("find_component_usages", "Find all pages and components where a given component is used, with parameter pass details. Cache-only, no API calls. Run sync_project first.", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+        componentName: z
+            .string()
+            .optional()
+            .describe("Human-readable component name (e.g. 'PremuimContentWall'). Case-insensitive."),
+        componentId: z
+            .string()
+            .optional()
+            .describe("Container ID (e.g. 'Container_ffzg5wc5')."),
+    }, async ({ projectId, componentName, componentId }) => {
+        // Check cache exists
+        const meta = await cacheMeta(projectId);
+        if (!meta) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No cache found for project "${projectId}". Run sync_project first to download the project YAML files.`,
+                    },
+                ],
+            };
+        }
+        if (!componentName && !componentId) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Provide either componentName or componentId.",
+                    },
+                ],
+            };
+        }
+        // Resolve component to its key
+        const resolved = await resolveComponent(projectId, componentName, componentId);
+        if (!resolved.ok) {
+            const list = resolved.available.map((n) => `  - ${n}`).join("\n");
+            const searchTerm = componentName || componentId || "";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Component "${searchTerm}" not found in cache. Available components:\n${list}`,
+                    },
+                ],
+            };
+        }
+        const targetId = resolved.component.containerId;
+        // Get component name for display
+        const componentContent = await cacheRead(projectId, resolved.component.componentFileKey);
+        const displayName = componentContent
+            ? (componentContent.match(/^name:\s*(.+)$/m)?.[1]?.trim() || targetId)
+            : targetId;
+        // Scan all node files for componentClassKeyRef matching this component
+        const allKeys = await listCachedKeys(projectId);
+        const nodeKeys = allKeys.filter((k) => /\/node\/id-[A-Z]/.test(k));
+        // Read node files in batches to check for component references
+        const usages = [];
+        await batchProcess(nodeKeys, 20, async (nodeKey) => {
+            const content = await cacheRead(projectId, nodeKey);
+            if (!content)
+                return;
+            // Quick string check before parsing YAML
+            if (!content.includes(targetId))
+                return;
+            let doc;
+            try {
+                doc = YAML.parse(content);
+            }
+            catch {
+                return;
+            }
+            // Check componentClassKeyRef
+            const classKeyRef = doc.componentClassKeyRef;
+            if (!classKeyRef)
+                return;
+            const refKey = classKeyRef.key;
+            if (refKey !== targetId)
+                return;
+            // Found a usage! Extract parent context
+            const parent = parseParentFromKey(nodeKey);
+            if (!parent)
+                return;
+            // Extract the widget key from the file key
+            const widgetKeyMatch = nodeKey.match(/\/node\/id-(\w+)$/);
+            const widgetKey = widgetKeyMatch ? widgetKeyMatch[1] : "unknown";
+            // Extract parameter passes
+            const params = [];
+            const parameterValues = doc.parameterValues;
+            if (parameterValues) {
+                for (const [, paramVal] of Object.entries(parameterValues)) {
+                    const paramId = paramVal.paramIdentifier;
+                    const value = resolveParamValue(paramVal);
+                    params.push({
+                        paramName: paramId || "unknown",
+                        value,
+                    });
+                }
+            }
+            // Resolve parent name
+            const parentName = await resolveParentName(projectId, parent.type, parent.id);
+            usages.push({
+                parentType: parent.type,
+                parentName,
+                parentId: parent.id,
+                widgetKey,
+                params,
+            });
+        });
+        // Format output
+        if (usages.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Component: ${displayName} (${targetId})\nNo usages found in cached files.`,
+                    },
+                ],
+            };
+        }
+        const lines = [];
+        lines.push(`Component: ${displayName} (${targetId})`);
+        lines.push(`Found ${usages.length} usage${usages.length === 1 ? "" : "s"}:`);
+        lines.push("");
+        for (let i = 0; i < usages.length; i++) {
+            const u = usages[i];
+            const parentLabel = u.parentType === "page" ? u.parentName : `[component] ${u.parentName}`;
+            lines.push(`${i + 1}. ${parentLabel} (${u.parentId}) \u2192 ${u.widgetKey}`);
+            if (u.params.length > 0) {
+                const paramStrs = u.params.map((p) => `${p.paramName} = ${p.value}`);
+                lines.push(`   Params: ${paramStrs.join(", ")}`);
+            }
+        }
+        return {
+            content: [{ type: "text", text: lines.join("\n") + cacheAgeFooter(meta) }],
+        };
+    });
+}

package/build/tools/find-page-navigations.d.ts

@@ -0,0 +1,26 @@
+/**
+ * find_page_navigations tool — scans cached action files to find all places
+ * that navigate to a given page.
+ * Zero API calls: everything comes from the local .ff-cache.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Parse parent context from an action file key.
+ * Example: "page/id-Scaffold_XXX/page-widget-tree-outline/node/id-Widget_YYY/trigger_actions/id-ON_TAP/action/id-zzz"
+ */
+export declare function parseActionContext(fileKey: string): {
+    parentType: "page" | "component";
+    parentId: string;
+    widgetKey: string;
+    trigger: string;
+} | null;
+/**
+ * Recursively search an object for a navigate action targeting the given scaffold ID.
+ * Returns navigate details if found, including whether it's inside a disableAction.
+ */
+export declare function findNavigateAction(obj: unknown, targetScaffoldId: string, isDisabled: boolean, depth: number): {
+    disabled: boolean;
+    allowBack: boolean;
+    passedParams: string[];
+} | null;
+export declare function registerFindPageNavigationsTool(server: McpServer): void;

package/build/tools/find-page-navigations.js

@@ -0,0 +1,220 @@
+import { z } from "zod";
+import YAML from "yaml";
+import { cacheRead, cacheMeta, cacheAgeFooter, listCachedKeys, } from "../utils/cache.js";
+import { resolvePage } from "./get-page-summary.js";
+import { batchProcess } from "../utils/batch-process.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Parse parent context from an action file key.
+ * Example: "page/id-Scaffold_XXX/page-widget-tree-outline/node/id-Widget_YYY/trigger_actions/id-ON_TAP/action/id-zzz"
+ */
+export function parseActionContext(fileKey) {
+    // Page action
+    const pageMatch = fileKey.match(/^page\/id-(Scaffold_\w+)\/.*\/node\/id-(\w+)\/trigger_actions\/id-([^/]+)\/action\//);
+    if (pageMatch) {
+        return {
+            parentType: "page",
+            parentId: pageMatch[1],
+            widgetKey: pageMatch[2],
+            trigger: pageMatch[3],
+        };
+    }
+    // Component action
+    const compMatch = fileKey.match(/^component\/id-(Container_\w+)\/.*\/node\/id-(\w+)\/trigger_actions\/id-([^/]+)\/action\//);
+    if (compMatch) {
+        return {
+            parentType: "component",
+            parentId: compMatch[1],
+            widgetKey: compMatch[2],
+            trigger: compMatch[3],
+        };
+    }
+    return null;
+}
+/**
+ * Recursively search an object for a navigate action targeting the given scaffold ID.
+ * Returns navigate details if found, including whether it's inside a disableAction.
+ */
+export function findNavigateAction(obj, targetScaffoldId, isDisabled, depth) {
+    if (!obj || typeof obj !== "object" || depth > 12)
+        return null;
+    const o = obj;
+    // Check for disableAction wrapper
+    if ("disableAction" in o) {
+        const da = o.disableAction;
+        return findNavigateAction(da, targetScaffoldId, true, depth + 1);
+    }
+    // Check for navigate action with matching pageNodeKeyRef
+    if ("navigate" in o) {
+        const nav = o.navigate;
+        const pageRef = nav.pageNodeKeyRef;
+        if (pageRef?.key === targetScaffoldId) {
+            const allowBack = nav.allowBack ?? true;
+            const passedParams = [];
+            const params = nav.passedParameters;
+            if (params) {
+                for (const [key, val] of Object.entries(params)) {
+                    if (key === "widgetClassNodeKeyRef")
+                        continue;
+                    passedParams.push(key);
+                }
+            }
+            return { disabled: isDisabled, allowBack, passedParams };
+        }
+    }
+    // Recurse into values
+    for (const val of Object.values(o)) {
+        if (val && typeof val === "object") {
+            const found = findNavigateAction(val, targetScaffoldId, isDisabled, depth + 1);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the name of a page or component from its top-level YAML cache.
+ */
+async function resolveParentName(projectId, parentType, parentId) {
+    const prefix = parentType === "page" ? "page" : "component";
+    const fileKey = `${prefix}/id-${parentId}`;
+    const content = await cacheRead(projectId, fileKey);
+    if (!content)
+        return parentId;
+    const nameMatch = content.match(/^name:\s*(.+)$/m);
+    return nameMatch ? nameMatch[1].trim() : parentId;
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+export function registerFindPageNavigationsTool(server) {
+    server.tool("find_page_navigations", "Find all actions that navigate to a given page, showing source page, trigger, disabled status, and passed parameters. Cache-only, no API calls. Run sync_project first.", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+        pageName: z
+            .string()
+            .optional()
+            .describe("Human-readable page name (e.g. 'PaywallPage'). Case-insensitive."),
+        scaffoldId: z
+            .string()
+            .optional()
+            .describe("Scaffold ID (e.g. 'Scaffold_tydsj8ql')."),
+    }, 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 targetScaffoldId = resolved.page.scaffoldId;
+        // Get target page name for display
+        const targetContent = await cacheRead(projectId, resolved.page.pageFileKey);
+        const displayName = targetContent
+            ? (targetContent.match(/^name:\s*(.+)$/m)?.[1]?.trim() || targetScaffoldId)
+            : targetScaffoldId;
+        // Scan all action files for navigate references
+        const allKeys = await listCachedKeys(projectId);
+        const actionKeys = allKeys.filter((k) => /\/action\/id-/.test(k));
+        const refs = [];
+        await batchProcess(actionKeys, 20, async (actionKey) => {
+            const content = await cacheRead(projectId, actionKey);
+            if (!content)
+                return;
+            // Quick string check before YAML parsing
+            if (!content.includes(targetScaffoldId))
+                return;
+            let doc;
+            try {
+                doc = YAML.parse(content);
+            }
+            catch {
+                return;
+            }
+            const navInfo = findNavigateAction(doc, targetScaffoldId, false, 0);
+            if (!navInfo)
+                return;
+            const ctx = parseActionContext(actionKey);
+            if (!ctx)
+                return;
+            const parentName = await resolveParentName(projectId, ctx.parentType, ctx.parentId);
+            refs.push({
+                parentType: ctx.parentType,
+                parentName,
+                parentId: ctx.parentId,
+                widgetKey: ctx.widgetKey,
+                trigger: ctx.trigger,
+                disabled: navInfo.disabled,
+                allowBack: navInfo.allowBack,
+                passedParams: navInfo.passedParams,
+            });
+        });
+        // Deduplicate (same parent + widget + trigger)
+        const seen = new Set();
+        const uniqueRefs = refs.filter((r) => {
+            const key = `${r.parentId}:${r.widgetKey}:${r.trigger}:${r.disabled}`;
+            if (seen.has(key))
+                return false;
+            seen.add(key);
+            return true;
+        });
+        // Format output
+        if (uniqueRefs.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Page: ${displayName} (${targetScaffoldId})\nNo navigations found in cached action files.`,
+                    },
+                ],
+            };
+        }
+        const lines = [];
+        lines.push(`Page: ${displayName} (${targetScaffoldId})`);
+        lines.push(`Found ${uniqueRefs.length} navigation${uniqueRefs.length === 1 ? "" : "s"}:`);
+        lines.push("");
+        for (let i = 0; i < uniqueRefs.length; i++) {
+            const r = uniqueRefs[i];
+            const status = r.disabled ? "[DISABLED] " : "";
+            const parentLabel = r.parentType === "page" ? r.parentName : `[component] ${r.parentName}`;
+            const back = r.allowBack ? "" : " (no back)";
+            lines.push(`${i + 1}. ${status}${parentLabel} (${r.parentId}) → ${r.trigger} on ${r.widgetKey}${back}`);
+            if (r.passedParams.length > 0) {
+                lines.push(`   Params: ${r.passedParams.join(", ")}`);
+            }
+        }
+        return {
+            content: [{ type: "text", text: lines.join("\n") + cacheAgeFooter(meta) }],
+        };
+    });
+}

package/build/tools/get-api-endpoints.d.ts

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