flutterflow-mcp 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# flutterflow-mcp
+
+MCP server for the FlutterFlow Project API. Enables AI-assisted FlutterFlow development through Claude and other MCP-compatible clients.
+
+## Quick Start
+
+### 1. Get your FlutterFlow API token
+
+Go to **FlutterFlow > Account Settings > API Token** and copy your token.
+
+### 2. Add to your MCP client
+
+**Claude Code:**
+
+```bash
+claude mcp add flutterflow -- npx -y flutterflow-mcp
+```
+
+Then set your token in the MCP config (`~/.claude/settings.json` or project `.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "flutterflow": {
+      "command": "npx",
+      "args": ["-y", "flutterflow-mcp"],
+      "env": {
+        "FLUTTERFLOW_API_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+**Other MCP clients (Cursor, Windsurf, etc.):**
+
+Add to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "flutterflow": {
+      "command": "npx",
+      "args": ["-y", "flutterflow-mcp"],
+      "env": {
+        "FLUTTERFLOW_API_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+### 3. Start building
+
+Ask your AI assistant to list your FlutterFlow projects, inspect pages, or modify widgets — it handles the rest.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_projects` | List all FlutterFlow projects |
+| `list_project_files` | List YAML files in a project |
+| `list_pages` | List all pages with names, scaffold IDs, and folders |
+| `get_page_by_name` | Fetch a page by human-readable name |
+| `get_project_yaml` | Download project YAML files |
+| `validate_yaml` | Validate YAML before pushing |
+| `update_project_yaml` | Push YAML changes to a project |
+| `sync_project` | Bulk download all YAML to local cache |
+| `get_page_summary` | Quick page overview from cache (widget tree, actions, params) |
+| `get_component_summary` | Quick component overview from cache |
+| `find_component_usages` | Find all pages/components using a given component |
+| `find_page_navigations` | Find all actions that navigate to a given page |
+| `get_yaml_docs` | Search/retrieve FlutterFlow YAML reference docs by topic or file |
+
+## Resources
+
+| Resource | URI | Description |
+|----------|-----|-------------|
+| Docs Index | `ff://docs` | List all available YAML reference documentation files |
+| Doc File | `ff://docs/{path}` | Read a specific YAML reference doc (e.g. `ff://docs/04-widgets/button`) |
+
+## Prompts
+
+| Prompt | Description |
+|--------|-------------|
+| `generate-page` | Generate a new page from a description |
+| `modify-component` | Modify an existing component |
+| `inspect-project` | Summarize project structure |
+| `flutterflow-dev-workflow` | Efficient workflow guide for AI-assisted FlutterFlow development |
+
+## Built-in YAML Reference
+
+This MCP ships with a comprehensive FlutterFlow YAML reference catalog that AI models can access at runtime:
+
+- **`get_yaml_docs` tool** — Search by topic (e.g. `get_yaml_docs(topic: "Button")`) or browse the full index
+- **`ff://docs` resources** — Direct access to all 21 reference docs covering widgets, actions, variables, theming, and editing workflows
+
+See [docs/ff-yaml/](docs/ff-yaml/) for the full catalog.
+
+## Claude Code Skills
+
+Copy 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
+
+## Development
+
+```bash
+git clone https://github.com/mohn93/ff-mcp.git
+cd ff-mcp
+npm install
+npm run build
+npm run dev          # watch mode
+```
+
+## Requirements
+
+- Node.js 18+
+- FlutterFlow API token (paid FlutterFlow subscription required)
+
+## License
+
+MIT

package/build/api/flutterflow.d.ts

@@ -0,0 +1,11 @@
+export declare class FlutterFlowClient {
+    private token;
+    constructor(token: string);
+    private request;
+    listProjects(projectType?: string, deserializeResponse?: boolean): Promise<unknown>;
+    listPartitionedFileNames(projectId: string): Promise<unknown>;
+    getProjectYamls(projectId: string, fileName?: string): Promise<unknown>;
+    validateProjectYaml(projectId: string, fileKey: string, fileContent: string): Promise<unknown>;
+    updateProjectByYaml(projectId: string, fileKeyToContent: Record<string, string>): Promise<unknown>;
+}
+export declare function createClient(): FlutterFlowClient;

package/build/api/flutterflow.js

@@ -0,0 +1,61 @@
+const FF_API_BASE = "https://api.flutterflow.io/v2";
+export class FlutterFlowClient {
+    token;
+    constructor(token) {
+        this.token = token;
+    }
+    async request(method, endpoint, body) {
+        const url = `${FF_API_BASE}${endpoint}`;
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            "Content-Type": "application/json",
+        };
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const errorText = await res.text();
+            throw new Error(`FlutterFlow API error ${res.status}: ${errorText}`);
+        }
+        return res.json();
+    }
+    async listProjects(projectType, deserializeResponse) {
+        return this.request("POST", "/l/listProjects", {
+            project_type: projectType,
+            deserialize_response: deserializeResponse ?? true,
+        });
+    }
+    async listPartitionedFileNames(projectId) {
+        return this.request("GET", `/listPartitionedFileNames?projectId=${encodeURIComponent(projectId)}`);
+    }
+    async getProjectYamls(projectId, fileName) {
+        let endpoint = `/projectYamls?projectId=${encodeURIComponent(projectId)}`;
+        if (fileName) {
+            endpoint += `&fileName=${encodeURIComponent(fileName)}`;
+        }
+        return this.request("GET", endpoint);
+    }
+    async validateProjectYaml(projectId, fileKey, fileContent) {
+        return this.request("POST", "/validateProjectYaml", {
+            projectId,
+            fileKey,
+            fileContent,
+        });
+    }
+    async updateProjectByYaml(projectId, fileKeyToContent) {
+        return this.request("POST", "/updateProjectByYaml", {
+            projectId,
+            fileKeyToContent,
+        });
+    }
+}
+export function createClient() {
+    const token = process.env.FLUTTERFLOW_API_TOKEN;
+    if (!token) {
+        throw new Error("FLUTTERFLOW_API_TOKEN environment variable is required. " +
+            "Get your token from FlutterFlow > Account Settings > API Token.");
+    }
+    return new FlutterFlowClient(token);
+}

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createClient } from "./api/flutterflow.js";
+import { registerListProjectsTool } from "./tools/list-projects.js";
+import { registerListFilesTool } from "./tools/list-files.js";
+import { registerGetYamlTool } from "./tools/get-yaml.js";
+import { registerValidateYamlTool } from "./tools/validate-yaml.js";
+import { registerUpdateYamlTool } from "./tools/update-yaml.js";
+import { registerListPagesTool } from "./tools/list-pages.js";
+import { registerGetPageByNameTool } from "./tools/get-page-by-name.js";
+import { registerSyncProjectTool } from "./tools/sync-project.js";
+import { registerGetPageSummaryTool } from "./tools/get-page-summary.js";
+import { registerGetComponentSummaryTool } from "./tools/get-component-summary.js";
+import { registerFindComponentUsagesTool } from "./tools/find-component-usages.js";
+import { registerFindPageNavigationsTool } from "./tools/find-page-navigations.js";
+import { registerResources } from "./resources/projects.js";
+import { registerDocsResources } from "./resources/docs.js";
+import { registerGeneratePagePrompt } from "./prompts/generate-page.js";
+import { registerModifyComponentPrompt } from "./prompts/modify-component.js";
+import { registerInspectProjectPrompt } from "./prompts/inspect-project.js";
+import { registerDevWorkflowPrompt } from "./prompts/dev-workflow.js";
+import { registerGetYamlDocsTool } from "./tools/get-yaml-docs.js";
+const server = new McpServer({
+    name: "ff-mcp",
+    version: "0.1.0",
+});
+const client = createClient();
+// Register tools
+registerListProjectsTool(server, client);
+registerListFilesTool(server, client);
+registerGetYamlTool(server, client);
+registerValidateYamlTool(server, client);
+registerUpdateYamlTool(server, client);
+registerListPagesTool(server, client);
+registerGetPageByNameTool(server, client);
+registerSyncProjectTool(server, client);
+registerGetPageSummaryTool(server);
+registerGetComponentSummaryTool(server);
+registerFindComponentUsagesTool(server);
+registerFindPageNavigationsTool(server);
+registerGetYamlDocsTool(server);
+// Register resources
+registerResources(server, client);
+registerDocsResources(server);
+// Register prompts
+registerGeneratePagePrompt(server);
+registerModifyComponentPrompt(server);
+registerInspectProjectPrompt(server);
+registerDevWorkflowPrompt(server);
+// Start server
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("FlutterFlow MCP server running on stdio");

package/build/prompts/dev-workflow.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDevWorkflowPrompt(server: McpServer): void;

package/build/prompts/dev-workflow.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+export function registerDevWorkflowPrompt(server) {
+    server.prompt("flutterflow-dev-workflow", "Efficient workflow guide for developing FlutterFlow apps through MCP tools. References the full YAML docs catalog via get_yaml_docs tool.", {
+        projectId: z
+            .string()
+            .optional()
+            .describe("Optional project ID to include in instructions"),
+    }, ({ projectId }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `You are an expert FlutterFlow developer using MCP tools to read and modify FlutterFlow projects.
+
+## Documentation
+
+This MCP server includes a comprehensive FlutterFlow YAML reference catalog. Use the \`get_yaml_docs\` tool to look up any schema, pattern, or convention:
+
+- \`get_yaml_docs(topic: "Button")\` — Widget schemas (Button, Text, TextField, Container, etc.)
+- \`get_yaml_docs(topic: "actions")\` — Action chains, triggers, navigation
+- \`get_yaml_docs(topic: "variables")\` — Data binding, variable sources
+- \`get_yaml_docs(topic: "theming")\` — Colors, typography, dimensions
+- \`get_yaml_docs(topic: "editing")\` — Read/edit/add workflows and anti-patterns
+- \`get_yaml_docs()\` — Full index of all available docs
+
+Always consult the docs before writing YAML. They contain validated schemas, field references, enum values, and real examples from production projects.
+
+## Efficient Workflow
+
+${projectId ? `**Project ID:** \`${projectId}\`\n` : ""}
+### Reading / Inspecting
+\`\`\`
+list_projects → sync_project → get_page_summary / get_component_summary
+\`\`\`
+
+### Editing Existing Widgets
+\`\`\`
+list_pages → get_page_by_name → (node-level fetch) → validate_yaml → update_project_yaml
+\`\`\`
+
+### Adding New Widgets
+\`\`\`
+list_pages → get_page_by_name → update widget-tree-outline + push individual node files → validate_yaml → update_project_yaml
+\`\`\`
+
+## Critical YAML Rules
+
+1. **Always update both \`inputValue\` AND \`mostRecentInputValue\`** — they must stay in sync.
+   - **Exceptions:** \`fontWeightValue\` and \`fontSizeValue\` only accept \`inputValue\`.
+2. **Use node-level file keys** for targeted edits, not the full page YAML.
+3. **Always validate before pushing** — call \`validate_yaml\` first.
+4. **Adding widgets requires node-level files** — push the tree outline + individual nodes together.
+5. **Column has no \`mainAxisSize\`** — use \`minSizeValue: { inputValue: true }\` instead.
+6. **AppBar \`templateType\`** — only \`LARGE_HEADER\` is valid. Control height via \`toolbarHeight\`.
+7. **TextField keyboard types** — use \`EMAIL_ADDRESS\`, not \`EMAIL\`.
+
+## Anti-Patterns
+
+- Do NOT call \`list_project_files\` to find pages — use \`list_pages\` instead.
+- Do NOT fetch pages one-by-one — use \`get_page_by_name\`.
+- Do NOT edit full page YAML for a single widget — use node-level file keys.
+- Do NOT guess YAML field names — use \`get_yaml_docs\` to look them up.`,
+                },
+            },
+        ],
+    }));
+}

package/build/prompts/generate-page.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerGeneratePagePrompt(server: McpServer): void;

package/build/prompts/generate-page.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+export function registerGeneratePagePrompt(server) {
+    server.prompt("generate-page", "Generate a new FlutterFlow page from a natural language description", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+        description: z
+            .string()
+            .describe("Natural language description of the page to create"),
+    }, ({ projectId, description }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `You are an expert FlutterFlow developer. Generate a new page for the FlutterFlow project.
+
+## Instructions
+
+1. First, use the list_project_files tool with projectId "${projectId}" to understand the existing project structure.
+2. Then, use get_project_yaml to read a few existing pages to understand the YAML schema and conventions used in this project.
+3. Based on the following description, generate valid FlutterFlow YAML for a new page:
+
+**Page Description:** ${description}
+
+4. Use validate_yaml to check your generated YAML is valid.
+5. If validation passes, use update_project_yaml to push the new page to the project.
+6. If validation fails, fix the errors and try again.
+
+## Important
+- Follow the exact YAML structure you observed in existing pages.
+- Use consistent naming conventions matching the project.
+- YAML content must be single-line strings with escaped newlines (\\n).`,
+                },
+            },
+        ],
+    }));
+}

package/build/prompts/inspect-project.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerInspectProjectPrompt(server: McpServer): void;

package/build/prompts/inspect-project.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+export function registerInspectProjectPrompt(server) {
+    server.prompt("inspect-project", "Read and summarize a FlutterFlow project's structure, pages, and components", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+    }, ({ projectId }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `You are an expert FlutterFlow developer. Inspect and summarize the FlutterFlow project.
+
+## Instructions
+
+1. Use list_project_files with projectId "${projectId}" to get all files.
+2. Use get_project_yaml to read key files like "app-details", "folders", and "authentication".
+3. Read a sample of page and component files to understand the app structure.
+4. Provide a clear summary including:
+   - App name and details
+   - Number of pages and their names
+   - Number of components and their names
+   - Data models / collections
+   - Authentication setup
+   - Any custom code files
+   - Overall architecture observations`,
+                },
+            },
+        ],
+    }));
+}

package/build/prompts/modify-component.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerModifyComponentPrompt(server: McpServer): void;

package/build/prompts/modify-component.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+export function registerModifyComponentPrompt(server) {
+    server.prompt("modify-component", "Read an existing FlutterFlow component and modify it based on instructions", {
+        projectId: z.string().describe("The FlutterFlow project ID"),
+        fileName: z
+            .string()
+            .describe("The YAML file name of the component to modify"),
+        changes: z
+            .string()
+            .describe("Description of changes to make to the component"),
+    }, ({ projectId, fileName, changes }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `You are an expert FlutterFlow developer. Modify an existing component in the FlutterFlow project.
+
+## Instructions
+
+1. Use get_project_yaml with projectId "${projectId}" and fileName "${fileName}" to read the current component YAML.
+2. Understand the current structure and widget tree.
+3. Apply the following changes:
+
+**Requested Changes:** ${changes}
+
+4. Use validate_yaml to verify your modified YAML is valid.
+5. If validation passes, use update_project_yaml to push the changes.
+6. If validation fails, fix the errors and try again.
+
+## Important
+- Preserve all existing structure you are not modifying.
+- YAML content must be single-line strings with escaped newlines (\\n).
+- Only change what was requested — do not refactor or reorganize.`,
+                },
+            },
+        ],
+    }));
+}

package/build/resources/docs.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDocsResources(server: McpServer): void;

package/build/resources/docs.js

@@ -0,0 +1,76 @@
+import { ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const DOCS_DIR = path.resolve(__dirname, "../../docs/ff-yaml");
+/** Recursively list all .md files under a directory, returning relative paths. */
+function listDocFiles(dir, prefix = "") {
+    const results = [];
+    if (!fs.existsSync(dir))
+        return results;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            results.push(...listDocFiles(path.join(dir, entry.name), relPath));
+        }
+        else if (entry.name.endsWith(".md")) {
+            results.push(relPath);
+        }
+    }
+    return results;
+}
+export function registerDocsResources(server) {
+    // Static resource: list all available docs
+    server.resource("docs-index", "ff://docs", {
+        description: "FlutterFlow YAML reference catalog — list all available documentation files",
+        mimeType: "application/json",
+    }, async (uri) => {
+        const files = listDocFiles(DOCS_DIR);
+        const index = files.map((f) => ({
+            file: f.replace(/\.md$/, ""),
+            uri: `ff://docs/${f.replace(/\.md$/, "")}`,
+        }));
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: JSON.stringify(index, null, 2),
+                    mimeType: "application/json",
+                },
+            ],
+        };
+    });
+    // Dynamic resource: get a specific doc file
+    server.resource("docs-file", new ResourceTemplate("ff://docs/{+path}", { list: undefined }), {
+        description: "Read a specific FlutterFlow YAML reference doc (e.g. ff://docs/04-widgets/button)",
+        mimeType: "text/markdown",
+    }, async (uri, { path: docPath }) => {
+        const filePath = path.join(DOCS_DIR, `${docPath}.md`);
+        if (!fs.existsSync(filePath)) {
+            const available = listDocFiles(DOCS_DIR)
+                .map((f) => f.replace(/\.md$/, ""))
+                .join("\n  ");
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        text: `Doc not found: ${docPath}\n\nAvailable docs:\n  ${available}`,
+                        mimeType: "text/plain",
+                    },
+                ],
+            };
+        }
+        const content = fs.readFileSync(filePath, "utf-8");
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: content,
+                    mimeType: "text/markdown",
+                },
+            ],
+        };
+    });
+}

package/build/resources/projects.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { FlutterFlowClient } from "../api/flutterflow.js";
+export declare function registerResources(server: McpServer, client: FlutterFlowClient): void;

package/build/resources/projects.js

@@ -0,0 +1,60 @@
+import { ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { decodeProjectYamlResponse } from "../utils/decode-yaml.js";
+export function registerResources(server, client) {
+    // Static resource: list all projects
+    server.resource("projects", "ff://projects", {
+        description: "List all FlutterFlow projects",
+        mimeType: "application/json",
+    }, async (uri) => {
+        const projects = await client.listProjects();
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: JSON.stringify(projects, null, 2),
+                    mimeType: "application/json",
+                },
+            ],
+        };
+    });
+    // Dynamic resource: list files in a project
+    server.resource("project-files", new ResourceTemplate("ff://projects/{projectId}/files", {
+        list: undefined,
+    }), {
+        description: "List YAML file names in a FlutterFlow project",
+        mimeType: "application/json",
+    }, async (uri, { projectId }) => {
+        const files = await client.listPartitionedFileNames(projectId);
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: JSON.stringify(files, null, 2),
+                    mimeType: "application/json",
+                },
+            ],
+        };
+    });
+    // Dynamic resource: get specific YAML file
+    server.resource("project-yaml", new ResourceTemplate("ff://projects/{projectId}/yaml/{+fileName}", {
+        list: undefined,
+    }), {
+        description: "Get a specific YAML file from a FlutterFlow project",
+        mimeType: "text/yaml",
+    }, async (uri, { projectId, fileName }) => {
+        const raw = await client.getProjectYamls(projectId, fileName);
+        const decoded = decodeProjectYamlResponse(raw);
+        const yamlText = Object.entries(decoded)
+            .map(([name, content]) => `# ${name}\n${content}`)
+            .join("\n");
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: yamlText,
+                    mimeType: "text/yaml",
+                },
+            ],
+        };
+    });
+}

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

@@ -0,0 +1,7 @@
+/**
+ * find_component_usages tool — scans cached node files to find all pages and
+ * components where a given component is instantiated.
+ * Zero API calls: everything comes from the local .ff-cache.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerFindComponentUsagesTool(server: McpServer): void;