flutterflow-mcp 0.2.1 → 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/docs/ff-yaml/05-actions.md

@@ -726,7 +726,112 @@ trueAction:
 
 ## Disabled Actions
 
-Actions can be conditionally disabled using a `disableAction` wrapper. When the condition evaluates to true, the wrapped action executes; the chain terminates otherwise.
+FlutterFlow uses `disableAction` to mark actions or conditionals as disabled. There are three distinct patterns depending on what is being disabled.
+
+### Pattern 1: Disabling a Leaf Action (Unconditional)
+
+To fully disable a single action (navigate, database, revenueCat, etc.), wrap the action content in `disableAction` at the **action file level**. The trigger chain continues to reference the same key — FlutterFlow reads the file, sees `disableAction`, and skips execution.
+
+```yaml
+# Action file: id-epxy2a0w.yaml
+key: epxy2a0w
+disableAction:
+  actionNode:
+    key: gm8dis03           # Internal node key (can be any unique key)
+    action:
+      navigate:
+        allowBack: false
+        passedParameters:
+          widgetClassNodeKeyRef:
+            key: Scaffold_tydsj8ql
+        isNavigateBack: false
+        transition:
+          transitionType: FADE_IN
+          durationMillis: 500
+        pageNodeKeyRef:
+          key: Scaffold_tydsj8ql
+      key: epxy2a0w          # Must match the outer key
+```
+
+| Field | Description |
+|-------|-------------|
+| `key` (outer) | The action's original key — chain references this |
+| `disableAction.actionNode.key` | Internal node key (any unique value) |
+| `disableAction.actionNode.action` | The original action content, preserved for re-enabling |
+| `disableAction.actionNode.action.key` | Must match the outer `key` |
+
+**Important:** Disabling a leaf action at the file level does NOT disable `followUpAction` chains defined in the trigger YAML. If the trigger chain has a `followUpAction` after this action reference, that follow-up will still execute.
+
+### Pattern 2: Disabling a Conditional Node
+
+To disable an entire `conditionActions` block in the trigger chain, two changes are required:
+
+**Step 1 — Create a new action file** that wraps the full conditional in `disableAction.actionNode.conditionActions`. Leaf actions within the conditional are inlined (not file references) with their own `disableAction` wrappers:
+
+```yaml
+# Action file: id-ds8cnd01.yaml (new file)
+key: ds8cnd01
+disableAction:
+  actionNode:
+    key: f441awwi               # Original conditional node key from the chain
+    conditionActions:
+      falseAction:
+        key: wkklfcpy
+        action:
+          key: epxy2a0w
+          disableAction:          # Leaf action inlined with its own disable
+            actionNode:
+              key: gm8dis03
+              action:
+                navigate:
+                  allowBack: false
+                  pageNodeKeyRef:
+                    key: Scaffold_tydsj8ql
+                key: epxy2a0w
+      trueActions:
+        - condition:
+            revenueCatEntitlementResponse: {}
+          trueAction:
+            key: 5uq5p5vt
+            action:
+              key: bgxsmj4b
+              disableAction:      # Another leaf action inlined
+                actionNode:
+                  key: gm8dis04
+                  action:
+                    navigate:
+                      allowBack: false
+                      pageNodeKeyRef:
+                        key: Scaffold_91ca3wwv
+                    key: bgxsmj4b
+      hasMultiConditions: false
+      key: ev7ush66
+```
+
+**Step 2 — Update the trigger chain YAML.** Replace the `conditionActions` block with an `action` reference to a noop key (a key with no corresponding action file):
+
+```yaml
+# Before (in trigger chain):
+followUpAction:
+  key: f441awwi
+  conditionActions:
+    falseAction: ...
+    trueActions: ...
+    hasMultiConditions: false
+    key: ev7ush66
+
+# After (in trigger chain):
+followUpAction:
+  key: f441awwi
+  action:
+    key: np8noop1              # Noop key — no action file exists for this key
+```
+
+**Note:** The noop key has no corresponding action file. When pushed via the UI, FlutterFlow handles this internally. When pushed via the API, you may need to create the action file with the disabled conditional content under the noop key itself (see API Limitations).
+
+### Pattern 3: Conditionally Disabled Action
+
+Actions can be conditionally disabled using `disableAction` with a condition. When the condition evaluates to true, the wrapped action executes; otherwise it is skipped.
 
 ```yaml
 key: hfzr0kmk
@@ -763,7 +868,12 @@ disableAction:
       key: xsa3loej
 ```
 
-Note: In `disableAction`, the action body can be inlined directly rather than referenced by key.
+### Key Rules
+
+- `disableAction` is only valid in **action files**, never in the trigger chain YAML directly
+- Leaf actions inlined inside `disableAction` use the full action body, not key references
+- The original action content is preserved inside the wrapper for easy re-enabling
+- Disabling a leaf action does NOT prevent `followUpAction` chains in the trigger from continuing
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flutterflow-mcp",
-  "version": "0.2.1",
+  "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"
   }
 }