flutterflow-mcp 0.3.5 → 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/package.json

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