flutterflow-mcp 0.3.4 → 0.3.6

package/README.md

@@ -263,9 +263,19 @@ This MCP ships with a comprehensive FlutterFlow YAML reference catalog that AI m
 
 See [docs/ff-yaml/](docs/ff-yaml/) for the full catalog.
 
+## AI Agent Skill
+
+This MCP includes a [skills.sh](https://skills.sh)-compatible skill for AI agents. Install it to teach your AI assistant how to use FlutterFlow MCP effectively:
+
+```bash
+npx skills add mohn93/ff-mcp --skill flutterflow-mcp
+```
+
+Compatible with Claude Code, Cursor, GitHub Copilot, Codex, Goose, Windsurf, and 12+ other AI agents. The skill provides tool orchestration workflows, critical YAML rules, and detailed reference documentation for widgets, actions, data binding, theming, and more.
+
 ## Claude Code Skills
 
-Copy skills from [`skills/`](skills/) into your project's `.claude/skills/` directory:
+You can also copy Claude Code-specific skills from [`skills/`](skills/) into your project's `.claude/skills/` directory:
 
 - **`ff-yaml-dev.md`** — Core workflow: reading, editing, and creating FlutterFlow pages/components
 - **`ff-widget-patterns.md`** — Quick reference for common widget YAML patterns and snippets

package/build/utils/topic-map.js

@@ -84,6 +84,13 @@ export const TOPIC_MAP = {
     parametervalues: "03-components.md",
     callback: "03-components.md",
     executecallbackaction: "03-components.md",
+    // Internationalization
+    translation: "01-project-files.md",
+    translations: "01-project-files.md",
+    i18n: "01-project-files.md",
+    localization: "01-project-files.md",
+    translatabletext: "01-project-files.md",
+    languages: "01-project-files.md",
     // Universal patterns
     inputvalue: "README.md",
     mostrecentinputvalue: "README.md",

package/docs/ff-yaml/00-overview.md

@@ -36,7 +36,7 @@ Every FlutterFlow project is a collection of YAML files accessed via file keys.
 | `enums/id-XXX` | Enum definition with named values |
 | `collections/id-XXX` | Firestore collection schema: fields, types, subcollections |
 | `agent/id-XXX` | AI agent configuration |
-| `custom-file/id-<TYPE>` | Custom file configs for native platform files. Known types: `MAIN` (main.dart startup actions), `ANDROID_MANIFEST` (XML injection hooks for AndroidManifest.xml), `PROGUARD` (ProGuard rule injection for proguard-rules.pro), `BUILD_GRADLE` (Gradle plugin/dependency/repository injection for build.gradle). Only appear after enabled in FF editor. Sub-file `custom-file/id-MAIN/custom-file-code.dart` contains generated Dart source. |
+| `custom-file/id-<TYPE>` | Custom file configs for native platform files. Known types: `MAIN` (main.dart startup actions), `ANDROID_MANIFEST` (XML injection hooks for AndroidManifest.xml), `INFO_PLIST` (plist property injection for Info.plist), `ENTITLEMENTS` (iOS capability entitlements for Runner.entitlements), `APP_DELEGATE` (Swift code injection for AppDelegate.swift), `PROGUARD` (ProGuard rule injection for proguard-rules.pro), `BUILD_GRADLE` (Gradle plugin/dependency/repository injection for build.gradle). Only appear after enabled in FF editor. Sub-file `custom-file/id-<TYPE>/custom-file-code.dart` contains generated source. |
 | `environment-settings` | Per-environment configuration values (API URLs, keys) |
 | `dependencies` | FlutterFlow library package dependencies |
 | `custom-code-dependencies` | Dart/Flutter pub dependencies for custom code |

package/docs/ff-yaml/01-project-files.md

@@ -444,6 +444,69 @@ persistLanguageSelection: true         # Remember user's language choice
 
 ---
 
+## languages/translation/id-{key} (Translation Files)
+
+**Purpose:** Individual translation entries for user-defined translatable strings. Each file maps a unique key to translated text across all supported languages.
+
+**File key pattern:** `languages/translation/id-<key>` (e.g., `languages/translation/id-ttk654j0`)
+
+**Schema:**
+```yaml
+translationIdentifier:
+  key: ttk654j0                # Unique translation key (8-char alphanumeric)
+translations:
+  - language:
+      language: en             # ISO 639-1 code (must match languages.yaml)
+    text: Continue             # Translated text for this language
+  - language:
+      language: es
+    text: Continuar
+isFixed: false                 # false = user-editable, true = system/preset string
+```
+
+**Key fields:**
+
+| Field | Type | Notes |
+|---|---|---|
+| `translationIdentifier.key` | string | Unique key matching the file key suffix. Referenced by widgets and parameter passes. |
+| `translations` | list | One entry per language. Must include all languages from `languages.yaml`. |
+| `translations[].language.language` | string | ISO 639-1 code (`en`, `es`, `fr`, etc.) |
+| `translations[].text` | string | Translated text. Empty string `""` = untranslated (falls back to primary language). |
+| `isFixed` | bool | `true` for system preset strings, `false` for user-defined translations. |
+
+### Where translation keys are referenced
+
+Translation keys appear in two contexts:
+
+**1. On Text widgets** — via `translationIdentifier` in the `text` prop:
+```yaml
+# Widget-level translation (static, per-widget)
+text:
+  translationIdentifier:
+    key: ttk654j0
+  textValue:
+    inputValue: Continue       # English default / editor preview
+```
+
+**2. On component parameter passes** — via `translatableText` inside `inputValue`:
+```yaml
+# Parameter-level translation (per-instance, used when passing
+# translated strings to component parameters)
+paramIdentifier:
+  name: title
+  key: p1titl
+inputValue:
+  translatableText:
+    translationIdentifier:
+      key: ms01ttl1
+    textValue:
+      inputValue: Histamine / Low DAO    # English default
+```
+
+> **Important:** The `translatableText` wrapper is the correct way to pass translated strings as component parameters. Do NOT use `translationIdentifier` directly on the parameterPass (it will fail validation with "Unknown field name"). Instead, nest it inside `inputValue.translatableText`.
+
+---
+
 ## app-state.yaml
 
 **Purpose:** App-level state variables (global state accessible from any page/component).
@@ -1242,6 +1305,363 @@ parameters:                                # Template variables referenced in ho
 
 ---
 
+## custom-file/id-INFO_PLIST
+
+**Purpose:** Allows injecting custom properties into the generated `Info.plist` for iOS builds, and defining template variables for dynamic values. Like `ANDROID_MANIFEST`, this is an abstraction layer — you define "hooks" (plist property injection) and "parameters" (template variables).
+
+> **This file only exists when it has content.** If all hooks and parameters are removed (via UI or API), the file disappears from the server (API returns 404). It reappears when a user adds a hook or parameter in the FF editor.
+
+> **WARNING: Pushing any `custom-file` deletes siblings.** The API treats all `custom-file/id-*` keys as a single collection. Pushing this file alone will delete all other custom files (MAIN, ANDROID_MANIFEST, PROGUARD, BUILD_GRADLE, etc.). **Always include all existing `custom-file` entries in the same push payload.** See [API Limitation #10](../flutterflow-api-limitations.md#10-pushing-one-custom-file-deletes-all-other-custom-file-entries).
+
+> **Important — this is NOT the Info.plist itself.**
+> This is FlutterFlow's configuration that controls **property injection into the generated Info.plist** at build time. The file only appears after a user adds at least one property in the FF editor (Settings > Custom Code > Custom Files > Info.plist).
+
+**Top-level keys:**
+- `type`
+- `identifier`
+- `hooks`
+- `parameters`
+
+### Hook Types
+
+Only one hook type:
+
+| Hook Type | Where it injects in Info.plist |
+|---|---|
+| `INFO_PLIST_PROPERTY` | Inside the root `<dict>` — use for adding `<key>`/`<value>` pairs (strings, booleans, arrays, etc.) |
+
+### Parameters (Template Variables)
+
+Same pattern as ANDROID_MANIFEST — parameters are template variables that can be referenced in hook `content` using `{{variableName}}` syntax. Values can come from literal input or environment variables.
+
+### Schema
+
+```yaml
+type: INFO_PLIST
+identifier:
+  name: Info.plist
+
+hooks:                                       # List of plist property injection hooks
+  - type: INFO_PLIST_PROPERTY                # Only hook type for Info.plist
+    identifier:
+      name: livetag                          # Human-readable hook name
+      key: gh2m0b                            # Unique 6-char alphanumeric key
+    content: "<key>live</key>\n<string>value</string>"  # Raw plist XML to inject
+
+parameters:                                  # Template variables
+  zini8l:                                    # Parameter key
+    parameter:
+      identifier:
+        name: fsdafd                         # Variable name — use {{fsdafd}} in hook content
+      dataType:
+        scalarType: String                   # Data type (String, Integer, etc.)
+    value:
+      inputValue:
+        serializedValue: safdsaf             # Literal value
+```
+
+**Key fields:**
+
+| Field | Type | Notes |
+|---|---|---|
+| `type` | string | Always `INFO_PLIST` for this file. |
+| `identifier.name` | string | Always `Info.plist`. |
+| `hooks` | list | List of plist property injection hooks. Each hook injects a key-value pair into the root `<dict>`. |
+| `hooks[].type` | enum | Always `INFO_PLIST_PROPERTY`. |
+| `hooks[].identifier.name` | string | Human-readable hook name. |
+| `hooks[].identifier.key` | string | Unique 6-char alphanumeric key. |
+| `hooks[].content` | string | Raw plist XML to inject. Typically `<key>name</key>\n<string>value</string>` or similar plist entries. Must be properly escaped in YAML. |
+| `parameters` | map | Map of parameter key to parameter definition. |
+| `parameters.<key>.parameter.identifier.name` | string | Variable name. Referenced in hook `content` as `{{variableName}}`. |
+| `parameters.<key>.parameter.dataType.scalarType` | enum | Data type (`String`, `Integer`, `Double`, `Boolean`, etc.). |
+| `parameters.<key>.value` | object | Value source — either `inputValue.serializedValue` (literal) or `variable` (environment reference). |
+
+### Parameter value sources
+
+Parameters support two value sources:
+
+**Literal value:**
+```yaml
+value:
+  inputValue:
+    serializedValue: my-value              # Hardcoded value
+```
+
+**Environment variable reference:**
+```yaml
+value:
+  variable:
+    source: DEV_ENVIRONMENT
+    baseVariable:
+      environmentValue:
+        identifier:
+          name: myEnvVar                   # References environment-settings.yaml
+          key: eji5p6
+```
+
+### Hook content examples
+
+**Simple string property:**
+```yaml
+content: "<key>MyCustomKey</key>\n<string>MyCustomValue</string>"
+```
+
+**Boolean property:**
+```yaml
+content: "<key>MyFeatureFlag</key>\n<true/>"
+```
+
+**Array property:**
+```yaml
+content: "<key>LSApplicationQueriesSchemes</key>\n<array>\n  <string>myapp</string>\n  <string>myapp-dev</string>\n</array>"
+```
+
+**API capabilities:**
+
+| Operation | Status | Notes |
+|---|---|---|
+| Reading config | Works | Full hook and parameter data returned. |
+| Adding hooks via API | Expected to work | Same structure as ANDROID_MANIFEST hooks. |
+| Adding parameters via API | Expected to work | Same structure as other custom file parameters. |
+| Hook name validation gap | Caution | Same as ANDROID_MANIFEST — avoid hyphens in names, use camelCase or spaces. |
+
+### Code sub-file (`custom-file/id-INFO_PLIST/custom-file-code.dart`)
+
+Contains the full generated `Info.plist` XML. This is the complete plist including all standard iOS keys (bundle identifiers, permissions, URL schemes, etc.) plus any injected hook content. It is **read-only** — modifications should be made through the hooks/parameters config, not by editing the XML directly.
+
+---
+
+## custom-file/id-ENTITLEMENTS
+
+**Purpose:** Allows injecting custom entitlements into the generated `Runner.entitlements` file for iOS builds. Entitlements declare app capabilities such as push notifications, App Groups, iCloud, associated domains, and other iOS-specific permissions.
+
+> **This file only exists when it has content.** If all hooks and parameters are removed (via UI or API), the file disappears from the server (API returns 404). It reappears when a user adds an entitlement or parameter in the FF editor.
+
+> **WARNING: Pushing any `custom-file` deletes siblings.** The API treats all `custom-file/id-*` keys as a single collection. Pushing this file alone will delete all other custom files (MAIN, ANDROID_MANIFEST, INFO_PLIST, etc.). **Always include all existing `custom-file` entries in the same push payload.** See [API Limitation #10](../flutterflow-api-limitations.md#10-pushing-one-custom-file-deletes-all-other-custom-file-entries).
+
+> **Important — this is an abstraction layer.**
+> This config controls **entitlement injection into the generated `Runner.entitlements`** at build time. The file only appears after a user adds at least one entitlement in the FF editor (Settings > Custom Code > Custom Files > Runner.entitlements).
+
+**Top-level keys:**
+- `type`
+- `identifier`
+- `hooks`
+- `parameters`
+
+### Hook Types
+
+Only one hook type:
+
+| Hook Type | Where it injects in Runner.entitlements |
+|---|---|
+| `ENTITLEMENT` | Inside the root `<dict>` of the entitlements plist — use for adding capability key-value pairs |
+
+### Schema
+
+```yaml
+type: ENTITLEMENTS
+identifier:
+  name: Runner.entitlements
+
+hooks:
+  - type: ENTITLEMENT                            # Only hook type for entitlements
+    identifier:
+      name: environemnt                          # Human-readable hook name
+      key: 5x527x                               # Unique 6-char alphanumeric key
+    content: "<key>aps-environment</key>\n<string>development</string>"  # Plist XML to inject
+
+parameters:                                      # Template variables — same as all other custom files
+  f4cahu:
+    parameter:
+      identifier:
+        name: variable1                          # Variable name — use {{variable1}} in hook content
+      dataType:
+        scalarType: String
+    value:
+      inputValue:
+        serializedValue: clear value             # Default value
+```
+
+**Key fields:**
+
+| Field | Type | Notes |
+|---|---|---|
+| `type` | string | Always `ENTITLEMENTS` for this file. |
+| `identifier.name` | string | Always `Runner.entitlements`. |
+| `hooks` | list | List of entitlement injection hooks. Each hook injects a capability key-value pair into the entitlements plist. |
+| `hooks[].type` | enum | Always `ENTITLEMENT`. |
+| `hooks[].identifier.name` | string | Human-readable name for the entitlement. |
+| `hooks[].identifier.key` | string | Unique 6-char alphanumeric key. |
+| `hooks[].content` | string | Raw plist XML to inject. Typically `<key>capability-name</key>` followed by a value (`<string>`, `<true/>`, `<array>`, etc.). Must be properly escaped in YAML. |
+| `parameters` | map | Template variables keyed by parameter ID. Use `{{variableName}}` in `content` to reference them. Same structure as all other custom files. |
+
+### Common entitlement content examples
+
+**Push notifications (development):**
+```yaml
+content: "<key>aps-environment</key>\n<string>development</string>"
+```
+
+**Push notifications (production):**
+```yaml
+content: "<key>aps-environment</key>\n<string>production</string>"
+```
+
+**Associated domains (for universal links):**
+```yaml
+content: "<key>com.apple.developer.associated-domains</key>\n<array>\n  <string>applinks:example.com</string>\n</array>"
+```
+
+**App Groups:**
+```yaml
+content: "<key>com.apple.security.application-groups</key>\n<array>\n  <string>group.com.example.myapp</string>\n</array>"
+```
+
+### API capabilities
+
+| Operation | Status | Notes |
+|---|---|---|
+| Reading config | Works | Full hook and parameter data returned. |
+| Adding hooks via API | Expected to work | Same structure as other custom file hooks. |
+| Adding parameters via API | Expected to work | Same structure as other custom file parameters. |
+| Hook name validation gap | Caution | Same as other custom files — avoid hyphens in names, use camelCase or spaces. |
+
+---
+
+## custom-file/id-APP_DELEGATE
+
+**Purpose:** Allows injecting custom Swift code into the generated `AppDelegate.swift` for iOS builds. Supports import statements and initialization code that runs during the iOS app launch sequence.
+
+> **This file only exists when it has content.** If all hooks and parameters are removed (via UI or API), the file disappears from the server (API returns 404). It reappears when a user adds a hook or parameter in the FF editor.
+
+> **WARNING: Pushing any `custom-file` deletes siblings.** The API treats all `custom-file/id-*` keys as a single collection. Pushing this file alone will delete all other custom files (MAIN, ANDROID_MANIFEST, INFO_PLIST, etc.). **Always include all existing `custom-file` entries in the same push payload.** See [API Limitation #10](../flutterflow-api-limitations.md#10-pushing-one-custom-file-deletes-all-other-custom-file-entries).
+
+> **Important — this is an abstraction layer.**
+> This config controls **Swift code injection into the generated `AppDelegate.swift`** at build time. The file only appears after a user adds at least one hook in the FF editor (Settings > Custom Code > Custom Files > AppDelegate.swift).
+
+**Top-level keys:**
+- `type`
+- `identifier`
+- `hooks`
+- `parameters`
+
+### Hook Types
+
+Two hook types control where Swift code is injected in the generated `AppDelegate.swift`:
+
+| Hook Type | Where it injects in AppDelegate.swift |
+|---|---|
+| `APP_DELEGATE_IMPORT_HOOK` | At the top of the file — use for `import` statements |
+| `APP_DELEGATE_INITIALIZATION_HOOK` | Inside `application(_:didFinishLaunchingWithOptions:)` — use for SDK init calls and setup code |
+
+### Schema
+
+```yaml
+type: APP_DELEGATE
+identifier:
+  name: AppDelegate.swift
+
+hooks:
+  - type: APP_DELEGATE_IMPORT_HOOK               # Injects at the top of the file (imports)
+    identifier:
+      name: UIkitimprot                          # Human-readable hook name
+      key: rtmoen                                # Unique 6-char alphanumeric key
+    content: import UIKit                        # Swift import statement
+
+  - type: APP_DELEGATE_INITIALIZATION_HOOK       # Injects inside didFinishLaunchingWithOptions
+    identifier:
+      name: logsinit                             # Human-readable hook name
+      key: 2b582i                                # Unique 6-char alphanumeric key
+    content: Logs.init()                         # Swift initialization code
+
+parameters:                                      # Template variables — same as all other custom files
+  74q7xg:
+    parameter:
+      identifier:
+        name: vars1                              # Variable name — use {{vars1}} in hook content
+      dataType:
+        scalarType: String
+    value:
+      inputValue:
+        serializedValue: var val                 # Default value
+```
+
+**Key fields:**
+
+| Field | Type | Notes |
+|---|---|---|
+| `type` | string | Always `APP_DELEGATE` for this file. |
+| `identifier.name` | string | Always `AppDelegate.swift`. |
+| `hooks` | list | List of Swift code injection hooks. |
+| `hooks[].type` | enum | `APP_DELEGATE_IMPORT_HOOK` (imports) or `APP_DELEGATE_INITIALIZATION_HOOK` (init code). |
+| `hooks[].identifier.name` | string | Human-readable name for the hook. |
+| `hooks[].identifier.key` | string | Unique 6-char alphanumeric key. |
+| `hooks[].content` | string | Raw Swift code to inject. For imports: a single `import` statement. For initialization: Swift code that runs during app launch. |
+| `parameters` | map | Template variables keyed by parameter ID. Use `{{variableName}}` in `content` to reference them. Same structure as all other custom files. |
+
+### Generated AppDelegate execution order
+
+The generated `AppDelegate.swift` follows this structure:
+
+```
+1.  import Flutter                              ← Standard Flutter import
+2.  import UIKit                                ← APP_DELEGATE_IMPORT_HOOK entries
+3.  import MySDK                                ← APP_DELEGATE_IMPORT_HOOK entries
+4.
+5.  @UIApplicationMain
+6.  class AppDelegate: FlutterAppDelegate {
+7.    override func application(...) -> Bool {
+8.      GeneratedPluginRegistrant.register(with: self)
+9.      Logs.init()                              ← APP_DELEGATE_INITIALIZATION_HOOK entries
+10.     MySDK.configure()                        ← APP_DELEGATE_INITIALIZATION_HOOK entries
+11.     return super.application(...)
+12.   }
+13. }
+```
+
+- **Import hooks** are placed at the top of the file alongside the standard Flutter/UIKit imports.
+- **Initialization hooks** are placed inside `application(_:didFinishLaunchingWithOptions:)` after plugin registration but before the `return` statement.
+
+### Common hook content examples
+
+**Import a framework:**
+```yaml
+- type: APP_DELEGATE_IMPORT_HOOK
+  identifier:
+    name: firebaseImport
+    key: abc123
+  content: import Firebase
+```
+
+**Initialize an SDK:**
+```yaml
+- type: APP_DELEGATE_INITIALIZATION_HOOK
+  identifier:
+    name: firebaseInit
+    key: def456
+  content: FirebaseApp.configure()
+```
+
+**Multi-line initialization:**
+```yaml
+- type: APP_DELEGATE_INITIALIZATION_HOOK
+  identifier:
+    name: oneSignalSetup
+    key: ghi789
+  content: "OneSignal.initialize(\"{{appId}}\")\nOneSignal.Notifications.requestPermission({ accepted in })"
+```
+
+### API capabilities
+
+| Operation | Status | Notes |
+|---|---|---|
+| Reading config | Works | Full hook and parameter data returned. |
+| Adding hooks via API | Expected to work | Same structure as other custom file hooks. |
+| Adding parameters via API | Expected to work | Same structure as other custom file parameters. |
+| Hook name validation gap | Caution | Same as other custom files — avoid hyphens in names, use camelCase or spaces. |
+
+---
+
 ## custom-file/id-PROGUARD
 
 **Purpose:** Allows injecting custom ProGuard rules into the generated `proguard-rules.pro` file for Android builds. Controls code shrinking, obfuscation, and optimization rules.

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

@@ -335,6 +335,26 @@ widgetProperty:
         inputValue: 460
 ```
 
+**Translatable text (i18n):**
+
+Use `translatableText` inside `inputValue` to pass a string that should be translated at runtime based on the app's current locale. This is the correct way to make component parameter text translatable.
+
+```yaml
+paramIdentifier:
+  name: title
+  key: p1titl
+inputValue:
+  translatableText:
+    translationIdentifier:
+      key: ms01ttl1              # References languages/translation/id-ms01ttl1
+    textValue:
+      inputValue: Histamine / Low DAO   # English default / editor preview
+```
+
+Each `translationIdentifier.key` must have a corresponding `languages/translation/id-<key>` file with translations for all supported languages (see `01-project-files.md` for the translation file schema).
+
+> **Note:** `translationIdentifier` is NOT valid as a direct sibling of `paramIdentifier` on a parameterPass — it must be nested inside `inputValue.translatableText`. Placing it at the wrong level causes a validation error.
+
 ---
 
 ## 7. isDummyRoot

package/docs/ff-yaml/06-variables.md

@@ -831,4 +831,19 @@ inputValue:
     value: "4294967295"        # ARGB integer as string
 ```
 
+**Translatable text (i18n):**
+
+Used when passing a string that should be translated at runtime based on the app's locale. Wraps `translationIdentifier` and `textValue` inside `inputValue.translatableText`. Commonly used in component parameter passes to make per-instance text translatable.
+
+```yaml
+inputValue:
+  translatableText:
+    translationIdentifier:
+      key: ms01ttl1            # References languages/translation/id-ms01ttl1
+    textValue:
+      inputValue: Histamine / Low DAO   # English default
+```
+
+Each key must have a corresponding translation file at `languages/translation/id-<key>` with entries for all supported languages. See `01-project-files.md` for the translation file schema.
+
 The `mostRecentInputValue` field must always stay in sync with `inputValue` when both are present.

package/docs/ff-yaml/08-custom-code.md

@@ -1,6 +1,6 @@
 # Custom Code
 
-FlutterFlow supports four types of custom code: **Custom Actions** (async Dart functions with side effects), **Custom Functions** (pure synchronous Dart functions), **Custom Widgets** (Flutter widgets with parameters), and **AI Agents** (LLM-powered processing pipelines). Additionally, **App Action Components** provide reusable action chains that can be invoked from any page, and **Custom Files** allow overriding special project-level files like `main.dart` and `AndroidManifest.xml`.
+FlutterFlow supports four types of custom code: **Custom Actions** (async Dart functions with side effects), **Custom Functions** (pure synchronous Dart functions), **Custom Widgets** (Flutter widgets with parameters), and **AI Agents** (LLM-powered processing pipelines). Additionally, **App Action Components** provide reusable action chains that can be invoked from any page, and **Custom Files** allow overriding special project-level files like `main.dart`, `AndroidManifest.xml`, `Info.plist`, `proguard-rules.pro`, and `build.gradle`.
 
 ---
 
@@ -706,76 +706,21 @@ variable:
 
 ## Custom Files
 
-Custom Files are special project-level files such as `main.dart` (the app entry point) and `AndroidManifest.xml`. Each has a metadata YAML file and a companion code file. They live under `custom-file/`.
+Custom Files are special project-level files that override platform-specific configuration (e.g., `main.dart`, `AndroidManifest.xml`, `Info.plist`, `proguard-rules.pro`, `build.gradle`). Each has a metadata YAML file and a companion code file under `custom-file/`.
 
-### File layout
-
-```
-custom-file/
-  id-MAIN.yaml                              # Metadata for main.dart
-  id-MAIN/custom-file-code.dart.yaml        # main.dart Dart code
-  id-ANDROID_MANIFEST.yaml                  # Metadata for AndroidManifest.xml
-  id-ANDROID_MANIFEST/custom-file-code.dart.yaml  # AndroidManifest.xml content
-```
-
-### MAIN metadata (id-MAIN.yaml)
-
-```yaml
-type: MAIN
-isUnlocked: false
-actions:
-  - type: FINAL_ACTION
-    identifier:
-      name: initializeUlink
-      key: t6snt
-      projectId: ulink-21sajt
-description: ""
-```
-
-### ANDROID_MANIFEST metadata (id-ANDROID_MANIFEST.yaml)
-
-```yaml
-type: ANDROID_MANIFEST
-identifier:
-  name: AndroidManifest.xml
-isUnlocked: true
-parameters:
-  29c3b7b9-afe7-4429-9d20-abb2e09f7a40:
-    parameter:
-      identifier:
-        name: ulinkDomain
-      dataType:
-        scalarType: String
-    value:
-      variable:
-        source: DEV_ENVIRONMENT
-        baseVariable:
-          environmentValue:
-            identifier:
-              name: ulinkDomain
-              key: eji5p6
-description: ""
-```
-
-### Definition fields
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `type` | Yes | File type: `MAIN` or `ANDROID_MANIFEST` |
-| `identifier` | For ANDROID_MANIFEST | `name` of the file |
-| `isUnlocked` | No | Whether the file is editable (default: false) |
-| `actions` | No | List of final actions (library initializers) that run at startup |
-| `parameters` | No | Template parameter substitutions for the code file |
-| `description` | No | Human-readable description |
-
-### Code files
-
-- **MAIN:** `custom-file/id-MAIN/custom-file-code.dart.yaml` contains the full `main.dart` with imports, `main()` function, Firebase/Supabase initialization, and library init calls.
-- **ANDROID_MANIFEST:** `custom-file/id-ANDROID_MANIFEST/custom-file-code.dart.yaml` contains the XML manifest with template placeholders (e.g., `{{unlinkDomain}}`, `{{ulink-21sajt.ulinkSchema}}`). Parameters in metadata map to these placeholders.
+> **Full documentation:** Custom Files are documented in detail in [01-project-files.md](01-project-files.md) under the `custom-file/id-*` sections, since they are project-level configuration files. See those sections for complete schemas, hook types, parameters, API capabilities, and warnings.
 
-### Parameter substitution
+### Quick reference
 
-Parameters in ANDROID_MANIFEST metadata define template variables. Each key is a UUID, and the value specifies where the parameter's value comes from (typically `DEV_ENVIRONMENT`). These get substituted into the code file's template placeholders at build time.
+| Type | File key | Description |
+|------|----------|-------------|
+| `MAIN` | `custom-file/id-MAIN` | App entry point (`main.dart`) — lifecycle actions (INITIAL/FINAL) |
+| `ANDROID_MANIFEST` | `custom-file/id-ANDROID_MANIFEST` | Android manifest — XML injection hooks, template parameters |
+| `INFO_PLIST` | `custom-file/id-INFO_PLIST` | iOS Info.plist — property injection hooks, template parameters |
+| `ENTITLEMENTS` | `custom-file/id-ENTITLEMENTS` | iOS Runner.entitlements — capability entitlement injection |
+| `APP_DELEGATE` | `custom-file/id-APP_DELEGATE` | iOS AppDelegate.swift — import and initialization code injection |
+| `PROGUARD` | `custom-file/id-PROGUARD` | ProGuard rules — rule injection hooks |
+| `BUILD_GRADLE` | `custom-file/id-BUILD_GRADLE` | Gradle config — plugin/dependency/repository injection hooks |
 
 ---
 
@@ -788,4 +733,4 @@ Parameters in ANDROID_MANIFEST metadata define template variables. Each key is a
 | Custom Widget | `custom-widgets/id-<key>.yaml` | (code embedded or separate) | `custom-widgets/` |
 | AI Agent | `agent/id-<key>.yaml` | N/A (no code file) | `agent/` |
 | App Action Component | `app-action-components/id-<key>.yaml` | N/A (actions are inline) | `app-action-components/` |
-| Custom File | `custom-file/id-<TYPE>.yaml` | `custom-file/id-<TYPE>/custom-file-code.dart.yaml` | `custom-file/` |
+| Custom File | `custom-file/id-<TYPE>` | `custom-file/id-<TYPE>/custom-file-code.dart` | `custom-file/` |

package/package.json

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

package/skills/flutterflow-mcp/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: flutterflow-mcp
+description: >
+  Teaches AI assistants how to develop FlutterFlow apps using MCP tools.
+  Use this skill when working with FlutterFlow projects, editing FF YAML,
+  creating or inspecting pages and components, reading project configuration,
+  or navigating FlutterFlow widget trees. It covers all 25 MCP tools for
+  discovery, reading, editing, and settings. Triggers on: FlutterFlow,
+  FF YAML, FF page, FF component, FF widget, FF theme, FF project.
+license: MIT
+compatibility: Requires the flutterflow-mcp MCP server to be connected and a valid FLUTTERFLOW_API_TOKEN environment variable.
+metadata:
+  author: mohn93
+  version: "1.0"
+---
+
+## Prerequisites
+
+This skill requires the **flutterflow-mcp** MCP server to be installed and connected. Before proceeding, check if the `list_projects` tool is available. If not, the user needs to set up the MCP server first:
+
+1. Get a FlutterFlow API token from **FlutterFlow > Profile > Account Settings > API Token** (requires a paid FlutterFlow subscription)
+2. Add the MCP server to your AI client:
+   ```bash
+   # Claude Code
+   claude mcp add flutterflow -e FLUTTERFLOW_API_TOKEN=<token> -- npx -y flutterflow-mcp
+
+   # Other clients (Claude Desktop, Cursor, Windsurf) — add to MCP config:
+   # { "command": "npx", "args": ["-y", "flutterflow-mcp"], "env": { "FLUTTERFLOW_API_TOKEN": "<token>" } }
+   ```
+3. Restart your AI client, then verify by calling `list_projects`
+
+## Overview
+
+The FlutterFlow MCP provides 25 tools for reading, inspecting, and editing FlutterFlow projects through YAML. It connects AI assistants to the FlutterFlow Project API, enabling programmatic access to pages, components, themes, actions, data models, and settings. All project data is represented as YAML files that can be fetched, cached locally, validated, and pushed back.
+
+## Tool Catalog
+
+### Discovery & Exploration
+
+| Tool | Purpose |
+|------|---------|
+| `list_projects` | List all FF projects accessible to your API token |
+| `list_project_files` | List YAML file keys in a project (supports prefix filter) |
+| `list_pages` | List pages with human-readable names, scaffold IDs, and folders |
+| `search_project_files` | Search file keys by keyword, prefix, or regex |
+| `sync_project` | Download all project YAML to local cache for fast reads |
+
+### Reading & Understanding
+
+| Tool | Purpose |
+|------|---------|
+| `get_page_by_name` | Fetch full page YAML by human-readable name |
+| `get_project_yaml` | Fetch specific YAML file(s) by file key |
+| `get_page_summary` | Quick page overview: widget tree, actions, params (cache-based) |
+| `get_component_summary` | Quick component overview: widget tree, params (cache-based) |
+| `find_component_usages` | Find all pages/components that use a given component |
+| `find_page_navigations` | Find all actions that navigate to a given page |
+
+### Configuration & Settings
+
+| Tool | Purpose |
+|------|---------|
+| `get_theme` | Theme colors, typography, breakpoints, widget defaults |
+| `get_app_state` | App state variables, constants, environment settings |
+| `get_api_endpoints` | API endpoint definitions (method, URL, headers, response) |
+| `get_data_models` | Data structs, enums, Firestore collections, Supabase tables |
+| `get_custom_code` | Custom actions, functions, widgets, AI agents (read-only) |
+| `get_general_settings` | App Details, App Assets, Nav Bar & App Bar |
+| `get_project_setup` | Firebase, Languages, Platforms, Permissions, Dependencies |
+| `get_app_settings` | Authentication, Push Notifications, Deployment settings |
+| `get_in_app_purchases` | Stripe, Braintree, RevenueCat, Razorpay config |
+| `get_integrations` | Supabase, SQLite, GitHub, Algolia, Google Maps, AdMob, etc. |
+
+### Editing & Documentation
+
+| Tool | Purpose |
+|------|---------|
+| `get_editing_guide` | Get recommended workflow and docs for a specific editing task |
+| `get_yaml_docs` | Search/retrieve YAML reference docs by topic or file path |
+| `validate_yaml` | Validate YAML content before pushing changes |
+| `update_project_yaml` | Push validated YAML changes to the FF project |
+
+## Core Workflows
+
+### Discover & Explore a Project
+
+Use this workflow when first connecting to a FlutterFlow project or when you need to understand its structure.
+
+```
+1. list_projects → pick the target projectId
+2. sync_project(projectId) → cache all YAML locally for fast reads
+3. list_pages(projectId) → see all pages with human-readable names, scaffold IDs, folders
+4. get_page_summary(projectId, pageName) → widget tree overview for any page of interest
+```
+
+After syncing, all cache-based tools (`get_page_summary`, `get_component_summary`, `get_theme`, `get_app_state`, etc.) work without additional API calls.
+
+### Read / Inspect a Page or Component
+
+Use this workflow to understand what a page contains, how it is structured, and how it connects to the rest of the app.
+
+```
+1. get_page_summary(projectId, pageName) → quick overview of widget tree, actions, params
+2. get_page_by_name(projectId, pageName) → full YAML if you need complete details
+3. find_page_navigations(projectId, pageName) → discover what actions navigate here
+4. find_component_usages(projectId, componentName) → find everywhere a component is used
+```
+
+For components, use `get_component_summary` instead of `get_page_summary`. Component summaries resolve nested component references so you can see the full hierarchy.
+
+### Edit an Existing Widget
+
+Use this workflow to modify a specific widget on a page without affecting the rest of the page.
+
+```
+1. get_page_by_name(projectId, pageName) → get the full page YAML
+2. Identify the node file key for the target widget (format: page/id-Scaffold_XXX/page-widget-tree-outline/node/id-Widget_YYY)
+3. get_project_yaml(projectId, fileName: "page/id-.../node/id-Widget_XXX") → fetch the individual node YAML
+4. Modify the YAML — keep inputValue and mostRecentInputValue in sync
+5. validate_yaml(projectId, fileKey, content) → check for errors before pushing
+6. update_project_yaml(projectId, {fileKey: content}) → push changes
+```
+
+Always edit at the node level. Editing the full page YAML for a single widget change risks overwriting unrelated content and is more error-prone.
+
+### Add a New Widget to a Page
+
+Use this workflow when you need to add new widgets to an existing page.
+
+```
+1. get_page_by_name(projectId, pageName) → understand the current widget tree structure
+2. get_yaml_docs(topic: "WidgetType") → look up the YAML schema for the widget you want to add
+3. Update the page-widget-tree-outline to include a reference to the new widget key
+4. Create individual node files for each new widget (one file per widget)
+5. validate_yaml → validate the tree outline first, then each node file
+6. update_project_yaml → push tree outline + all node files together in one call
+```
+
+Pushing the tree outline and node files in a single call is critical. The server strips inline widget children from the tree outline, so nodes must be separate files.
+
+### Create a Reusable Component
+
+Use this workflow to build a new component from scratch.
+
+```
+1. get_yaml_docs(topic: "create component") → get the full walkthrough and required file structure
+2. Design component parameters: name, dataType, isNullable for each param
+3. Create these files: component metadata, widget-tree-outline, root node (with isDummyRoot: true), child nodes
+4. validate_yaml → validate all files before pushing
+5. update_project_yaml → push all component files in one call
+```
+
+Remember: the root node of a component must have `isDummyRoot: true`. Callback triggers use `triggerType: CALLBACK` with a separate `parameterIdentifier` field. WidgetProperty params use `widgetProperty` in parameterPasses, not `inputValue`.
+
+## Critical YAML Rules
+
+1. **Sync inputValue and mostRecentInputValue** -- Both fields must always contain the same value when you set or update them. If you change one, change both. Exceptions: `fontWeightValue` and `fontSizeValue` only accept `inputValue` (they have no `mostRecentInputValue` field).
+
+2. **Use node-level file keys for edits** -- Target `page/id-Scaffold_XXX/page-widget-tree-outline/node/id-Widget_YYY` for individual widget edits. Never edit the full page YAML (`page/id-Scaffold_XXX`) just to change a single widget. Full-page edits risk overwriting unrelated content and are harder to validate.
+
+3. **Always validate before pushing** -- Call `validate_yaml` before every `update_project_yaml` call. Validation catches missing node files, unknown fields, invalid enum values, and structural problems. Skipping validation risks corrupting the project.
+
+4. **Push tree outline and node files together** -- When adding new widgets, include the updated `page-widget-tree-outline` AND all individual node files in a single `update_project_yaml` call. Widget children embedded inline in the tree outline will be silently stripped by the FlutterFlow server.
+
+5. **Column has no mainAxisSize field** -- To achieve shrink-to-content behavior (equivalent to `MainAxisSize.min` in Flutter), use `minSizeValue: { inputValue: true }` on the Column widget instead.
+
+6. **AppBar templateType** -- Only `LARGE_HEADER` is a confirmed valid value. Do not use `STANDARD` as it may cause unexpected behavior. Control the AppBar height through the `toolbarHeight` property instead.
+
+7. **Custom code is read-only** -- Custom actions, functions, widgets, and AI agents cannot be created or edited through the MCP API. Use `get_custom_code` to read their signatures and source code, but any modifications must be made directly in the FlutterFlow UI. Attempting to push custom code changes will silently corrupt or be ignored.
+
+## Anti-Patterns
+
+- **Don't use `list_project_files` to find pages** -- It returns raw file keys without human-readable names. Use `list_pages` instead, which gives you page names, scaffold IDs, and folder assignments.
+
+- **Don't fetch pages one-by-one to browse a project** -- This is slow and wastes API calls. Use `sync_project` to cache everything locally first, then use `get_page_summary` for quick overviews of any page.
+
+- **Don't edit full page YAML for a single widget change** -- Full-page edits can overwrite other widgets, actions, or parameters. Always use node-level file keys for targeted, safe edits.
+
+- **Don't guess YAML field names or enum values** -- FlutterFlow YAML has specific field names and valid values that are not always intuitive. Use `get_yaml_docs(topic)` or `get_editing_guide(task)` to look up the correct schema before writing YAML.
+
+- **Don't embed widget children inline in the tree outline** -- The FlutterFlow server silently strips inline children from the `page-widget-tree-outline` file. Always create separate node files for each widget.
+
+- **Don't push custom code changes through the API** -- The API silently corrupts or ignores Dart code edits for custom actions, functions, and widgets. These must be edited in the FlutterFlow UI.
+
+## Documentation Lookup
+
+The MCP server ships with 21 built-in reference documents. Use these tools to look up schemas, patterns, and conventions **before** writing YAML:
+
+| When you need... | Call |
+|------------------|------|
+| Widget schema (Button, Text, Container, etc.) | `get_yaml_docs(topic: "Button")` |
+| Action chains, triggers, navigation | `get_yaml_docs(topic: "actions")` |
+| Data binding, variable sources | `get_yaml_docs(topic: "variables")` |
+| Colors, typography, dimensions | `get_yaml_docs(topic: "theming")` |
+| Creating components from scratch | `get_yaml_docs(topic: "create component")` |
+| Editing workflows and anti-patterns | `get_yaml_docs(topic: "editing")` |
+| Data structs, enums, collections | `get_yaml_docs(topic: "data")` |
+| Full docs index | `get_yaml_docs()` |
+| Guided workflow for a specific task | `get_editing_guide(task: "change the button color")` |
+
+Always consult the docs before writing YAML. They contain validated schemas, field references, enum values, and real examples.