community-ff-mcp 0.4.0 → 0.4.2

package/README.md

@@ -1,5 +1,7 @@
 # community-ff-mcp
 
+> **Disclaimer:** This is an unofficial, community-built project. It is not affiliated with, endorsed by, or sponsored by FlutterFlow. "FlutterFlow" is a trademark of FlutterFlow Inc. This project uses the FlutterFlow public API.
+
 MCP server for the FlutterFlow Project API. Enables AI-assisted FlutterFlow development through Claude and other MCP-compatible clients.
 
 ## What This MCP Does Best
@@ -265,13 +267,33 @@ 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:
+This MCP includes a [skills.sh](https://skills.sh)-compatible skill that teaches AI assistants how to use FlutterFlow MCP effectively. The skill provides tool orchestration workflows, critical YAML rules, and reference documentation for widgets, actions, data binding, theming, and more.
+
+### Install the Skill
 
 ```bash
 npx skills add mohn93/ff-mcp --skill community-ff-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.
+This works with **18+ AI agents** including Claude Code, Cursor, GitHub Copilot, Codex, Goose, Windsurf, and more. The `skills` CLI auto-detects your AI tool and installs the skill to the correct location.
+
+### What the Skill Teaches Your AI
+
+Once installed, your AI assistant will know how to:
+
+- **Discover** — List projects, pages, components, and search project files
+- **Read** — Summarize pages/components, trace component usages, inspect navigations
+- **Edit** — Follow the correct read → guide → edit → validate → push workflow
+- **Configure** — Read theme, app state, API endpoints, data models, and integrations
+
+### Skill + MCP Setup
+
+The skill and the MCP server are installed separately:
+
+1. **MCP server** gives the AI the tools (see [Quick Start](#quick-start) above)
+2. **Skill** teaches the AI *how* to use those tools effectively
+
+If the skill detects the MCP tools aren't connected, it will guide the user through setup automatically.
 
 ## Claude Code Skills
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "community-ff-mcp",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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/build/tools/get-project-config.d.ts

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

package/build/tools/get-project-config.js

@@ -1,216 +0,0 @@
-import { z } from "zod";
-import YAML from "yaml";
-import { cacheRead, cacheMeta, listCachedKeys } from "../utils/cache.js";
-async function resolvePageName(projectId, scaffoldId) {
-    const content = await cacheRead(projectId, `page/id-${scaffoldId}`);
-    if (!content)
-        return scaffoldId;
-    const nameMatch = content.match(/^name:\s*(.+)$/m);
-    return nameMatch ? nameMatch[1].trim() : scaffoldId;
-}
-export function registerGetProjectConfigTool(server) {
-    server.tool("get_project_config", "Get core project configuration — app name, entry pages, routing, nav bar, auth, permissions, services, main.dart lifecycle actions, and a project file map. No API calls. Run sync_project first if not cached.", {
-        projectId: z.string().describe("The FlutterFlow project ID"),
-    }, async ({ projectId }) => {
-        const meta = await cacheMeta(projectId);
-        if (!meta) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `No cache found for project "${projectId}". Run sync_project first to download the project YAML files.`,
-                    },
-                ],
-            };
-        }
-        const [appDetailsRaw, navBarRaw, authRaw, permissionsRaw, revenueCatRaw] = await Promise.all([
-            cacheRead(projectId, "app-details"),
-            cacheRead(projectId, "nav-bar"),
-            cacheRead(projectId, "authentication"),
-            cacheRead(projectId, "permissions"),
-            cacheRead(projectId, "revenue-cat"),
-        ]);
-        const sections = ["# Project Configuration"];
-        // --- App Details ---
-        if (appDetailsRaw) {
-            const appDetails = YAML.parse(appDetailsRaw);
-            const appName = appDetails.name || "Unknown";
-            const initialPageKey = appDetails.initialPageKeyRef?.key;
-            const routing = appDetails.routingSettings;
-            const routingEnabled = routing?.enableRouting === true;
-            const subroutes = routing?.pagesAreSubroutesOfRoot === true;
-            let initialPageLine = "not set";
-            if (initialPageKey) {
-                const name = await resolvePageName(projectId, initialPageKey);
-                initialPageLine = `${name} (${initialPageKey})`;
-            }
-            sections.push(`\n## App Details`, `Name: ${appName}`, `Initial page: ${initialPageLine}`, `Routing: ${routingEnabled ? "enabled" : "disabled"}, pages are subroutes: ${subroutes ? "yes" : "no"}`);
-        }
-        else {
-            sections.push(`\n## App Details`, `(not cached)`);
-        }
-        // --- Authentication ---
-        if (authRaw) {
-            const auth = YAML.parse(authRaw);
-            const active = auth.active === true;
-            if (active) {
-                let provider = "Unknown";
-                const firebaseConfigs = auth.firebaseConfigFileInfos;
-                const supabase = auth.supabase;
-                if (firebaseConfigs && firebaseConfigs.length > 0) {
-                    provider = "Firebase";
-                }
-                else if (supabase && Object.keys(supabase).length > 0) {
-                    provider = "Supabase";
-                }
-                sections.push(`\n## Authentication`, `Status: Active`, `Provider: ${provider}`);
-            }
-            else {
-                sections.push(`\n## Authentication`, `Status: Inactive`);
-            }
-        }
-        else {
-            sections.push(`\n## Authentication`, `Status: Inactive`);
-        }
-        // Auth page info comes from app-details
-        if (appDetailsRaw) {
-            const appDetails = YAML.parse(appDetailsRaw);
-            const authPageInfo = appDetails.authPageInfo;
-            if (authPageInfo) {
-                const homeRef = authPageInfo.homePageNodeKeyRef?.key;
-                const signInRef = authPageInfo.signInPageNodeKeyRef?.key;
-                if (homeRef) {
-                    const name = await resolvePageName(projectId, homeRef);
-                    sections.push(`Home page: ${name} (${homeRef})`);
-                }
-                if (signInRef) {
-                    const name = await resolvePageName(projectId, signInRef);
-                    sections.push(`Sign-in page: ${name} (${signInRef})`);
-                }
-            }
-        }
-        // --- Nav Bar ---
-        if (navBarRaw) {
-            const navBar = YAML.parse(navBarRaw);
-            const visible = navBar.show === true;
-            if (visible) {
-                const navType = navBar.navBarType || "UNKNOWN";
-                const labels = navBar.labels === true;
-                const pageRefs = navBar.pageKeyRefOrder;
-                sections.push(`\n## Nav Bar`, `Visible: Yes`, `Type: ${navType}`, `Labels: ${labels ? "Yes" : "No"}`);
-                if (pageRefs && pageRefs.length > 0) {
-                    const tabs = [];
-                    for (let i = 0; i < pageRefs.length; i++) {
-                        const scaffoldId = pageRefs[i].key;
-                        const name = await resolvePageName(projectId, scaffoldId);
-                        tabs.push(`  ${i + 1}. ${name} (${scaffoldId})`);
-                    }
-                    sections.push(`Tabs:`, ...tabs);
-                }
-            }
-            else {
-                sections.push(`\n## Nav Bar`, `Visible: No`);
-            }
-        }
-        else {
-            sections.push(`\n## Nav Bar`, `Visible: No`);
-        }
-        // --- Permissions ---
-        if (permissionsRaw) {
-            const permissions = YAML.parse(permissionsRaw);
-            const builtIn = permissions.permissionMessages;
-            const custom = permissions.userDefinedPermissions;
-            const hasBuiltIn = builtIn && builtIn.length > 0;
-            const hasCustom = custom && custom.length > 0;
-            if (hasBuiltIn || hasCustom) {
-                sections.push(`\n## Permissions`);
-                if (hasBuiltIn) {
-                    sections.push(`Built-in:`);
-                    for (const perm of builtIn) {
-                        const permType = perm.permissionType || "UNKNOWN";
-                        const msg = perm.message?.textValue?.inputValue;
-                        sections.push(`  - ${permType}: ${msg ? `"${msg}"` : "(no message)"}`);
-                    }
-                }
-                if (hasCustom) {
-                    sections.push(`Custom:`);
-                    for (const perm of custom) {
-                        const names = perm.names;
-                        const iosName = names?.iosName || "?";
-                        const androidName = names?.androidName || "?";
-                        const msg = perm.message?.textValue?.inputValue;
-                        sections.push(`  - ${iosName} / ${androidName}: ${msg ? `"${msg}"` : "(no message)"}`);
-                    }
-                }
-            }
-        }
-        // --- Services ---
-        sections.push(`\n## Services`);
-        if (revenueCatRaw) {
-            const revenueCat = YAML.parse(revenueCatRaw);
-            sections.push(`RevenueCat: ${revenueCat.enabled === true ? "enabled" : "disabled"}`);
-        }
-        else {
-            sections.push(`RevenueCat: disabled`);
-        }
-        // --- Lifecycle Actions (main.dart) ---
-        sections.push(`\n## Lifecycle Actions (main.dart)`);
-        const mainFileRaw = await cacheRead(projectId, "custom-file/id-MAIN");
-        if (mainFileRaw) {
-            const mainFile = YAML.parse(mainFileRaw);
-            const actions = mainFile.actions;
-            if (actions && actions.length > 0) {
-                const initialActions = actions.filter((a) => a.type === "INITIAL_ACTION");
-                const finalActions = actions.filter((a) => a.type === "FINAL_ACTION");
-                const formatAction = (action, index) => {
-                    const identifier = action.identifier;
-                    const name = identifier?.name || "(unnamed)";
-                    const key = identifier?.key;
-                    const fromProject = identifier?.projectId;
-                    const fromSuffix = fromProject ? `, from: ${fromProject}` : "";
-                    return `  ${index + 1}. ${name} (key: ${key}${fromSuffix})`;
-                };
-                if (initialActions.length > 0) {
-                    sections.push(`Initial Actions:`);
-                    initialActions.forEach((a, i) => sections.push(formatAction(a, i)));
-                }
-                if (finalActions.length > 0) {
-                    sections.push(`Final Actions:`);
-                    finalActions.forEach((a, i) => sections.push(formatAction(a, i)));
-                }
-            }
-            else {
-                sections.push(`(none)`);
-            }
-        }
-        else {
-            sections.push(`(none)`);
-        }
-        // --- Project File Map ---
-        const allKeys = await listCachedKeys(projectId);
-        sections.push(`\n## Project File Map`);
-        const categoryPatterns = [
-            { label: "Pages", pattern: /^page\/id-[^/]+$/ },
-            { label: "Components", pattern: /^component\/id-[^/]+$/ },
-            { label: "Custom Actions", pattern: /^custom-actions\/id-[^/]+$/ },
-            { label: "Custom Functions", pattern: /^custom-functions\/id-[^/]+$/ },
-            { label: "Custom Widgets", pattern: /^custom-widgets\/id-[^/]+$/ },
-            { label: "Custom Files", pattern: /^custom-file\/id-[^/]+$/ },
-            { label: "App Action Components", pattern: /^app-action-components\/id-[^/]+$/ },
-            { label: "API Endpoints", prefix: "api-endpoint/" },
-            { label: "Collections", prefix: "collections/" },
-            { label: "AI Agents", pattern: /^agent\/id-[^/]+$/ },
-        ];
-        for (const cat of categoryPatterns) {
-            const count = cat.pattern
-                ? allKeys.filter((k) => cat.pattern.test(k)).length
-                : allKeys.filter((k) => k.startsWith(cat.prefix)).length;
-            if (count > 0) {
-                sections.push(`${cat.label}: ${count}`);
-            }
-        }
-        return {
-            content: [{ type: "text", text: sections.join("\n") }],
-        };
-    });
-}