flutterflow-mcp 0.2.2 → 0.2.3

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

@@ -4,4 +4,18 @@
  * 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

@@ -18,7 +18,7 @@ async function batchProcess(items, batchSize, fn) {
 /**
  * Resolve the value of a parameter pass to a readable string.
  */
-function resolveParamValue(paramObj) {
+export function resolveParamValue(paramObj) {
     // Check for variable source (e.g. INTERNATIONALIZATION)
     const variable = paramObj.variable;
     if (variable) {
@@ -60,7 +60,7 @@ function resolveParamValue(paramObj) {
  *   "page/id-Scaffold_xxx/page-widget-tree-outline/node/id-Widget_yyy"
  *   "component/id-Container_xxx/component-widget-tree-outline/node/id-Widget_yyy"
  */
-function parseParentFromKey(fileKey) {
+export function parseParentFromKey(fileKey) {
     const pageMatch = fileKey.match(/^page\/id-(Scaffold_\w+)\//);
     if (pageMatch)
         return { type: "page", id: pageMatch[1] };

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

@@ -4,4 +4,23 @@
  * 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

@@ -18,7 +18,7 @@ async function batchProcess(items, batchSize, fn) {
  * 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"
  */
-function parseActionContext(fileKey) {
+export function parseActionContext(fileKey) {
     // Page action
     const pageMatch = fileKey.match(/^page\/id-(Scaffold_\w+)\/.*\/node\/id-(\w+)\/trigger_actions\/id-([^/]+)\/action\//);
     if (pageMatch) {
@@ -45,7 +45,7 @@ function parseActionContext(fileKey) {
  * 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.
  */
-function findNavigateAction(obj, targetScaffoldId, isDisabled, depth) {
+export function findNavigateAction(obj, targetScaffoldId, isDisabled, depth) {
     if (!obj || typeof obj !== "object" || depth > 12)
         return null;
     const o = obj;

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

@@ -110,6 +110,8 @@ outline) {
         name: nodeInfo.name,
         slot: outline.slot,
         detail: nodeInfo.detail,
+        componentRef: nodeInfo.componentRef,
+        componentId: nodeInfo.componentId,
         triggers,
         children,
     };
@@ -118,7 +120,7 @@ outline) {
 // Tool registration
 // ---------------------------------------------------------------------------
 export function registerGetComponentSummaryTool(server) {
-    server.tool("get_component_summary", "Get a readable summary of a FlutterFlow component from local cache — widget tree, actions, params. No API calls. Run sync_project first if not cached.", {
+    server.tool("get_component_summary", "Get a readable summary of a FlutterFlow component from local cache — widget tree, actions, params. Nested component references are resolved to show [ComponentName] (ComponentId). No API calls. Run sync_project first if not cached.", {
         projectId: z.string().describe("The FlutterFlow project ID"),
         componentName: z
             .string()

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

@@ -131,6 +131,8 @@ outline) {
         name: nodeInfo.name,
         slot: outline.slot,
         detail: nodeInfo.detail,
+        componentRef: nodeInfo.componentRef,
+        componentId: nodeInfo.componentId,
         triggers,
         children,
     };
@@ -139,7 +141,7 @@ outline) {
 // 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.", {
+    server.tool("get_page_summary", "Get a readable summary of a FlutterFlow page from local cache — widget tree, actions, params, state. Component references are resolved to show [ComponentName] (ComponentId) instead of plain Container. Use the ComponentId with get_component_summary to drill into a component. No API calls. Run sync_project first if not cached.", {
         projectId: z.string().describe("The FlutterFlow project ID"),
         pageName: z
             .string()

package/build/utils/page-summary/action-summarizer.d.ts

@@ -1,4 +1,19 @@
-import { TriggerSummary } from "./types.js";
+import { ActionSummary, TriggerSummary } from "./types.js";
+/**
+ * Collect all action keys referenced in a trigger chain.
+ * Flattens followUpAction chains, conditionActions, and parallelActions.
+ */
+export declare function collectActionKeys(node: Record<string, unknown>): string[];
+/**
+ * Recursively search an object tree for the first recognizable action.
+ * Used to unwrap disableAction nodes where the real action is buried
+ * inside conditionalActions or other nesting.
+ */
+export declare function findDeepAction(obj: unknown, depth?: number): ActionSummary | null;
+/**
+ * Classify an action YAML into a human-readable summary.
+ */
+export declare function classifyAction(doc: Record<string, unknown>): ActionSummary;
 /**
  * Read all trigger_actions for a node and return summaries.
  *

package/build/utils/page-summary/action-summarizer.js

@@ -10,7 +10,7 @@ import { cacheRead, listCachedKeys } from "../cache.js";
  * Collect all action keys referenced in a trigger chain.
  * Flattens followUpAction chains, conditionActions, and parallelActions.
  */
-function collectActionKeys(node) {
+export function collectActionKeys(node) {
     const keys = [];
     // Direct action reference
     const action = node.action;
@@ -69,7 +69,7 @@ const ACTION_TYPE_KEYS = [
  * Used to unwrap disableAction nodes where the real action is buried
  * inside conditionalActions or other nesting.
  */
-function findDeepAction(obj, depth = 0) {
+export function findDeepAction(obj, depth = 0) {
     if (!obj || typeof obj !== "object" || depth > 8)
         return null;
     const o = obj;
@@ -91,7 +91,7 @@ function findDeepAction(obj, depth = 0) {
 /**
  * Classify an action YAML into a human-readable summary.
  */
-function classifyAction(doc) {
+export function classifyAction(doc) {
     // Disabled action — unwrap and recursively find the inner action
     if ("disableAction" in doc) {
         const da = doc.disableAction;

package/build/utils/page-summary/formatter.js

@@ -19,7 +19,15 @@ function fmtSlot(slot) {
 function nodeLabel(node) {
     const parts = [];
     parts.push(fmtSlot(node.slot));
-    parts.push(node.type);
+    if (node.componentRef) {
+        parts.push(`[${node.componentRef}]`);
+        if (node.componentId) {
+            parts.push(` (${node.componentId})`);
+        }
+    }
+    else {
+        parts.push(node.type);
+    }
     if (node.name) {
         parts.push(` (${node.name})`);
     }

package/build/utils/page-summary/node-extractor.d.ts

@@ -2,7 +2,14 @@ export interface NodeInfo {
     type: string;
     name: string;
     detail: string;
+    componentRef?: string;
+    componentId?: string;
 }
+/**
+ * Resolve the inputValue from a FF value object.
+ * Returns the literal string, or "[dynamic]" for variable references.
+ */
+export declare function resolveValue(obj: unknown): string;
 /**
  * Infer widget type from the key prefix (e.g. "Text_abc123" → "Text").
  */

package/build/utils/page-summary/node-extractor.js

@@ -8,7 +8,7 @@ import { cacheRead } from "../cache.js";
  * Resolve the inputValue from a FF value object.
  * Returns the literal string, or "[dynamic]" for variable references.
  */
-function resolveValue(obj) {
+export function resolveValue(obj) {
     if (obj == null)
         return "";
     if (typeof obj === "string" || typeof obj === "number")
@@ -172,6 +172,18 @@ export function inferTypeFromKey(key) {
     const match = key.match(/^([A-Z][a-zA-Z]*)_/);
     return match ? match[1] : "Unknown";
 }
+/**
+ * Resolve a component reference to its human-readable name.
+ * Reads the component definition file from cache (e.g. "component/id-Container_xxx").
+ */
+async function resolveComponentName(projectId, componentKey) {
+    const compFileKey = `component/id-${componentKey}`;
+    const content = await cacheRead(projectId, compFileKey);
+    if (!content)
+        return undefined;
+    const nameMatch = content.match(/^name:\s*(.+)$/m);
+    return nameMatch ? nameMatch[1].trim() : undefined;
+}
 /**
  * Read a node's cached file and extract type, name, and detail.
  *
@@ -195,7 +207,15 @@ export async function extractNodeInfo(projectId, pagePrefix, nodeKey) {
         const name = doc.name || "";
         const props = doc.props || {};
         const detail = extractDetail(type, props);
-        return { type, name, detail };
+        // Check for component reference
+        const compRef = doc.componentClassKeyRef;
+        let componentRef;
+        let componentId;
+        if (compRef?.key && typeof compRef.key === "string") {
+            componentId = compRef.key;
+            componentRef = await resolveComponentName(projectId, componentId);
+        }
+        return { type, name, detail, componentRef, componentId };
     }
     catch {
         return {

package/build/utils/page-summary/types.d.ts

@@ -18,6 +18,8 @@ export interface SummaryNode {
     name: string;
     slot: string;
     detail: string;
+    componentRef?: string;
+    componentId?: string;
     triggers: TriggerSummary[];
     children: SummaryNode[];
 }

package/docs/ff-yaml/03-components.md

@@ -414,7 +414,67 @@ node:
 
 ---
 
-## 10. Creating a New Component
+## 10. Components in Summary Output
+
+The `get_page_summary` and `get_component_summary` tools resolve component references and display them with a distinct format in the widget tree. This makes it easy to distinguish regular widgets from embedded components at a glance.
+
+### Format
+
+Component instances appear as `[ComponentName] (Container_ID)` instead of just `Container`:
+
+```
+FeedHomePage (Scaffold_e5ows2lg) — folder: home
+
+ON_INIT_STATE → [customAction: checkNotificationPermissionResult, ...]
+
+Widget Tree:
+└── [body] Container
+    └── Column
+        └── Column
+            ├── [Header] (Container_ur4ml9qw)
+            ├── [SearchBar] (Container_qw4kqc4l)
+            └── Container
+                └── [PostsList] (Container_pgvko7fz)
+```
+
+### Reading the output
+
+| Element | Meaning |
+|---|---|
+| `Container`, `Column`, `Row`, etc. | Regular widget — defined inline on this page/component |
+| `[Header] (Container_ur4ml9qw)` | Component instance — `Header` is the component name, `Container_ur4ml9qw` is the component ID |
+| `[body]`, `[appBar]`, etc. | Slot prefix — which slot of the parent widget this node fills |
+| `→ ON_TAP → [navigate: to page]` | Trigger — action(s) attached to this widget |
+
+### Drilling into components
+
+The component ID in parentheses (e.g. `Container_ur4ml9qw`) can be used to retrieve the full component structure:
+
+- **`get_component_summary`** — pass `componentId: "Container_ur4ml9qw"` (or `componentName: "Header"`) to see the component's internal widget tree, params, and actions
+- **`get_project_yaml`** — pass `fileName: "component/id-Container_ur4ml9qw"` to get the raw component metadata YAML
+- **`find_component_usages`** — pass `componentId: "Container_ur4ml9qw"` to find all pages and components where this component is used
+
+### Nested components
+
+Components can contain other components. The same `[Name] (ID)` format appears at any nesting level:
+
+```
+PostsList (Container_pgvko7fz)
+Params: customAudienceFilter (Enum), profileUserId (String), fetchType (Enum), itemId (String)
+
+Widget Tree:
+└── ConditionalBuilder
+    ├── PlaceholderWidget
+    │   └── ListView
+    │       └── [PostCard] (Container_abc12345) → CALLBACK → [updateState]
+    └── PlaceholderWidget
+        └── Column
+            └── [EmptyState] (Container_xyz98765)
+```
+
+---
+
+## 11. Creating a New Component
 
 Creating a component requires pushing multiple files in a **single** `update_project_yaml` call, similar to adding widgets to a page.
 
@@ -652,7 +712,7 @@ executeCallbackAction:
 
 ---
 
-## 11. Refactoring Page Widgets into a Component
+## 12. Refactoring Page Widgets into a Component
 
 To extract existing page widgets into a reusable component:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flutterflow-mcp",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "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",
@@ -16,6 +16,9 @@
     "build": "tsc && chmod 755 build/index.js",
     "dev": "tsc --watch",
     "start": "node build/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -50,6 +53,7 @@
   "devDependencies": {
     "@types/adm-zip": "^0.5.7",
     "@types/node": "^25.2.3",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
   }
 }