flutterflow-mcp 0.3.0 → 0.3.1

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

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta, listCachedKeys, } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter, listCachedKeys, } from "../utils/cache.js";
 import { resolveComponent } from "./get-component-summary.js";
 import { batchProcess } from "../utils/batch-process.js";
 // ---------------------------------------------------------------------------
@@ -210,7 +210,7 @@ export function registerFindComponentUsagesTool(server) {
             }
         }
         return {
-            content: [{ type: "text", text: lines.join("\n") }],
+            content: [{ type: "text", text: lines.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

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

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta, listCachedKeys, } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter, listCachedKeys, } from "../utils/cache.js";
 import { resolvePage } from "./get-page-summary.js";
 import { batchProcess } from "../utils/batch-process.js";
 // ---------------------------------------------------------------------------
@@ -214,7 +214,7 @@ export function registerFindPageNavigationsTool(server) {
             }
         }
         return {
-            content: [{ type: "text", text: lines.join("\n") }],
+            content: [{ type: "text", text: lines.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-api-endpoints.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta, listCachedKeys } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter, listCachedKeys } from "../utils/cache.js";
 import { batchProcess } from "../utils/batch-process.js";
 function parseEndpoint(content) {
     const doc = YAML.parse(content);
@@ -120,7 +120,7 @@ export function registerGetApiEndpointsTool(server) {
             endpoints = filtered;
         }
         return {
-            content: [{ type: "text", text: formatEndpoints(endpoints) }],
+            content: [{ type: "text", text: formatEndpoints(endpoints) + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-app-settings.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter } from "../utils/cache.js";
 async function resolvePageName(projectId, scaffoldId) {
     const content = await cacheRead(projectId, `page/id-${scaffoldId}`);
     if (!content)
@@ -163,7 +163,7 @@ export function registerGetAppSettingsTool(server) {
             sections.push(`(not configured)`);
         }
         return {
-            content: [{ type: "text", text: sections.join("\n") }],
+            content: [{ type: "text", text: sections.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-app-state.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter } from "../utils/cache.js";
 import { resolveDataType } from "../utils/resolve-data-type.js";
 export function registerGetAppStateTool(server) {
     server.tool("get_app_state", "Get app state variables, constants, and environment settings from local cache. No API calls. Run sync_project first if not cached.", {
@@ -90,7 +90,7 @@ export function registerGetAppStateTool(server) {
             }
         }
         return {
-            content: [{ type: "text", text: sections.join("\n") }],
+            content: [{ type: "text", text: sections.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

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

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta, listCachedKeys, } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter, listCachedKeys, } from "../utils/cache.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";
@@ -189,7 +189,7 @@ export function registerGetComponentSummaryTool(server) {
         // Format output
         const summary = formatComponentSummary(componentMeta, enrichedTree);
         return {
-            content: [{ type: "text", text: summary }],
+            content: [{ type: "text", text: summary + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-custom-code.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta, listCachedKeys } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter, listCachedKeys } from "../utils/cache.js";
 import { batchProcess } from "../utils/batch-process.js";
 import { resolveDataType } from "../utils/resolve-data-type.js";
 // ---------------------------------------------------------------------------
@@ -374,7 +374,7 @@ export function registerGetCustomCodeTool(server) {
         }
         const output = `# Custom Code\n\n${sections.join("\n\n")}`;
         return {
-            content: [{ type: "text", text: output }],
+            content: [{ type: "text", text: output + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-data-models.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta, listCachedKeys } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter, listCachedKeys } from "../utils/cache.js";
 import { batchProcess } from "../utils/batch-process.js";
 import { resolveDataType } from "../utils/resolve-data-type.js";
 async function readStructs(projectId, nameFilter) {
@@ -260,7 +260,7 @@ export function registerGetDataModelsTool(server) {
         }
         const output = formatOutput(structs, enums, collections, supabaseTables, name);
         return {
-            content: [{ type: "text", text: output }],
+            content: [{ type: "text", text: output + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-general-settings.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter } from "../utils/cache.js";
 async function resolvePageName(projectId, scaffoldId) {
     const content = await cacheRead(projectId, `page/id-${scaffoldId}`);
     if (!content)
@@ -110,7 +110,7 @@ export function registerGetGeneralSettingsTool(server) {
             sections.push(`\n## Nav Bar & App Bar`, `(not configured)`);
         }
         return {
-            content: [{ type: "text", text: sections.join("\n") }],
+            content: [{ type: "text", text: sections.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-in-app-purchases.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter } from "../utils/cache.js";
 const PROVIDERS = [
     { key: "stripe", label: "Stripe" },
     { key: "braintree", label: "Braintree" },
@@ -45,7 +45,7 @@ export function registerGetInAppPurchasesTool(server) {
             }
         }
         return {
-            content: [{ type: "text", text: sections.join("\n") }],
+            content: [{ type: "text", text: sections.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-integrations.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter } from "../utils/cache.js";
 /**
  * Fields that should never be output — API keys, secrets, tokens, etc.
  * Only IDs and non-sensitive configuration are shown.
@@ -131,7 +131,7 @@ export function registerGetIntegrationsTool(server) {
             sections.push(lines.join("\n"));
         }
         return {
-            content: [{ type: "text", text: sections.join("\n") }],
+            content: [{ type: "text", text: sections.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

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

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta, listCachedKeys, } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter, 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";
@@ -199,7 +199,7 @@ export function registerGetPageSummaryTool(server) {
         // Format output
         const summary = formatPageSummary(pageMeta, enrichedTree);
         return {
-            content: [{ type: "text", text: summary }],
+            content: [{ type: "text", text: summary + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-project-setup.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter } from "../utils/cache.js";
 import { resolveDataType } from "../utils/resolve-data-type.js";
 export function registerGetProjectSetupTool(server) {
     server.tool("get_project_setup", "Get Project Setup settings — Firebase services, Languages, Platforms, Permissions, Project Dependencies, Dev Environments. Mirrors the FlutterFlow 'Project Setup' settings section. Cache-based, no API calls. Run sync_project first.", {
@@ -206,7 +206,7 @@ export function registerGetProjectSetupTool(server) {
             sections.push(`(not configured)`);
         }
         return {
-            content: [{ type: "text", text: sections.join("\n") }],
+            content: [{ type: "text", text: sections.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/get-theme.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import YAML from "yaml";
-import { cacheRead, cacheMeta } from "../utils/cache.js";
+import { cacheRead, cacheMeta, cacheAgeFooter } from "../utils/cache.js";
 function argbToHex(argbStr) {
     const n = parseInt(argbStr, 10);
     if (isNaN(n))
@@ -122,7 +122,7 @@ export function registerGetThemeTool(server) {
             }
         }
         return {
-            content: [{ type: "text", text: sections.join("\n") }],
+            content: [{ type: "text", text: sections.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/tools/list-files.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { listCachedKeys, cacheMeta } from "../utils/cache.js";
+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"),
@@ -15,7 +15,7 @@ export function registerListFilesTool(server, client) {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify({ value: { file_names: keys }, source: "cache", syncedAt: meta.lastSyncedAt }, null, 2),
+                        text: JSON.stringify({ value: { file_names: keys }, source: "cache", syncedAt: meta.lastSyncedAt }, null, 2) + cacheAgeFooter(meta),
                     },
                 ],
             };

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { cacheMeta, listCachedKeys } from "../utils/cache.js";
+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.", {
@@ -63,7 +63,7 @@ export function registerSearchProjectFilesTool(server) {
             lines.push(`- ${key}`);
         }
         return {
-            content: [{ type: "text", text: lines.join("\n") }],
+            content: [{ type: "text", text: lines.join("\n") + cacheAgeFooter(meta) }],
         };
     });
 }

package/build/utils/cache.d.ts

@@ -51,3 +51,8 @@ export declare function cacheWriteMeta(projectId: string, meta: CacheMeta): Prom
  * 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

@@ -148,6 +148,28 @@ export async function listCachedKeys(projectId, 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
 // ---------------------------------------------------------------------------
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flutterflow-mcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "MCP server for the FlutterFlow Project API — AI-assisted FlutterFlow development through Claude and other MCP-compatible clients",
   "type": "module",
   "main": "build/index.js",