Deduplication | Reducing tokens by 45% almost

.changeset/giant-crabs-rescue.md

@@ -0,0 +1,5 @@
+---
+"figma-flutter-mcp": minor
+---
+
+Break-even point: ~22 component analyses

.gitignore

@@ -2,4 +2,5 @@ node_modules/
 .env
 package-lock.json
 dist/
-output/
+output/
+reports/

CONTRIBUTING.md

@@ -0,0 +1,202 @@
+# Contributing to Figma Flutter MCP
+
+Thank you for your interest in contributing to Figma Flutter MCP! This guide will help you get started with development and testing.
+
+## 🚀 Quick Start for Contributors
+
+### Prerequisites
+- Node.js 18+
+- npm or yarn
+- Figma API Key (for testing)
+- Git
+
+### Setup Development Environment
+
+1. **Fork and Clone**
+   ```bash
+   git clone https://github.com/your-username/figma-flutter-mcp.git
+   cd figma-flutter-mcp
+   npm install
+   ```
+
+2. **Create .env file**
+   ```bash
+   # Create .env file with your Figma API key
+   echo "FIGMA_API_KEY=your-figma-api-key-here" > .env
+   ```
+
+3. **Start Development Server**
+   ```bash
+   npm run dev
+   ```
+
+## 📋 Development Guidelines
+
+### Code Style
+- Use TypeScript for all new code
+- Follow existing code patterns and conventions
+- Use meaningful variable and function names
+- Add docs in `docs/` if you think its neccessary
+
+### Project Structure
+```
+src/
+├── cli.mts              # CLI entry point
+├── server.mts           # MCP server implementation
+├── config.mts           # Configuration handling
+├── extractors/          # Figma data extractors
+│   ├── colors/
+│   ├── components/
+│   ├── screens/
+│   └── typography/
+├── tools/               # Flutter code generators
+├── services/            # External service integrations
+├── types/               # TypeScript type definitions
+└── utils/               # Utility functions
+```
+
+### Making Changes
+
+1. **Create a Branch**
+   ```bash
+   git checkout -b feature/your-feature-name
+   # or
+   git checkout -b fix/issue-description
+   ```
+
+2. **Make Your Changes**
+   - Write clean, documented code
+   - Add tests for new features
+   - Update documentation as needed
+
+3. **Test Your Changes**
+   ```bash
+   # Build and check for errors
+   npm run build
+
+   # Test locally
+   npm run dev
+   ```
+
+4. **Commit and Push**
+   ```bash
+   git add .
+   git commit -m "feat: add new feature description"
+   git push origin feature/your-feature-name
+   ```
+
+5. **Create Pull Request**
+   - Use descriptive titles and descriptions
+   - Reference any related issues
+   - Include screenshots/examples if applicable
+
+## 🧪 Local Testing & Development
+
+The project supports HTTP server mode for easier development and testing. This allows you to test MCP tools without setting up a full MCP client.
+
+### Setting Up Your Environment
+
+If you haven't already set up your Figma API key:
+```bash
+# Create .env file
+echo "FIGMA_API_KEY=your-figma-api-key-here" > .env
+```
+
+**Get your Figma API Key:**
+1. Go to [Figma Settings > Personal Access Tokens](https://www.figma.com/developers/api#access-tokens)
+2. Generate a new personal access token
+3. Copy the token and add it to your `.env` file
+
+⚠️ **Important**: Never commit your `.env` file to version control. It's already included in `.gitignore`.
+
+### Development Server Options
+
+#### Using npm scripts (recommended)
+```bash
+# Start HTTP server on default port 3333
+npm run dev
+
+# Start HTTP server on a specific port
+npm run dev:port 4000
+
+# Start in stdio mode (for MCP clients)
+npm run dev:stdio
+```
+
+#### Using direct commands
+```bash
+# Start HTTP server
+npx tsx src/cli.mts --http
+
+# Start HTTP server on specific port
+npx tsx src/cli.mts --http --port 4000
+
+# Start in stdio mode
+npx tsx src/cli.mts --stdio
+```
+
+#### Using built version
+```bash
+# Build first
+npm run build
+
+# Start HTTP server
+node dist/cli.mjs --http
+
+# Start HTTP server on specific port
+node dist/cli.mjs --http --port 4000
+```
+
+## Connecting to the Server
+
+### MCP Client Configuration
+
+To connect an MCP client to the local HTTP server, add this configuration to your MCP JSON config file:
+
+```json
+{
+  "mcpServers": {
+    "local-figma-flutter-mcp": {
+      "url": "http://localhost:3333/mcp"
+    }
+  }
+}
+```
+
+## Available Endpoints
+
+When the HTTP server is running, the following endpoints are available:
+
+- **POST /mcp** - Main Streamable HTTP endpoint for MCP communication
+- **GET /mcp** - Session management for StreamableHTTP
+- **DELETE /mcp** - Session termination for StreamableHTTP  
+- **GET /sse** - Server-Sent Events endpoint (alternative transport)
+- **POST /messages** - Message endpoint for SSE transport
+
+## Environment Variables
+
+You can configure the server using environment variables. The recommended approach is to use a `.env` file:
+
+### Using .env file (Recommended)
+```env
+# Required: Your Figma API key
+FIGMA_API_KEY=your-figma-api-key-here
+
+# Optional: Enable HTTP mode by default
+HTTP_MODE=true
+
+# Optional: Set default HTTP port
+HTTP_PORT=3333
+```
+
+## 📋 Pull Request Checklist
+
+Before submitting a PR:
+- [ ] Code builds without errors (`npm run build`)
+- [ ] Tests pass (if applicable)
+- [ ] Documentation updated
+- [ ] PR description explains changes
+- [ ] Related issues referenced
+- [ ] Follows existing code style
+
+Thank you for contributing to Figma Flutter MCP! 🚀

README.md

@@ -117,8 +117,37 @@ Once you've the FIGMA API KEY, you can setup the MCP in cursor as follows:
 
 > NOTE: If you've installed this MCP as `npm` package make sure to keep it updated to latest version. Sometimes, it caches the old version and keep showing you error like "Not being able to use tool call" or "Figma API key setup is not working" etc.
 
-### 🧑🏼‍💻 Local Setup
-Please ensure that in local setup your version remains updated with your local server, sometimes `npm i` has installed the server globally for you and the keeps on overriding your local changes because of which you might not see any update.
+
+### 🚀 Quick Start for Local Testing
+
+For quick local testing, you can run the server via HTTP instead of stdio:
+
+```bash
+# Clone and setup
+git clone <your-repo-url> figma-flutter-mcp
+cd figma-flutter-mcp
+npm install
+
+# Create .env file with your Figma API key
+echo "FIGMA_API_KEY=your-figma-api-key-here" > .env
+
+# Start HTTP server for local testing
+npm run dev
+```
+
+Then add this to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "local-figma-flutter": {
+      "url": "http://localhost:3333/mcp"
+    }
+  }
+}
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions.
 
 #### 0. Prerequisites
 - Node.js 18+

package.json

@@ -15,21 +15,25 @@
   "scripts": {
     "build": "tsc",
     "start": "node dist/cli.mjs",
-    "dev": "tsx src/cli.mts",
+    "dev": "tsx src/cli.mts --http",
+    "dev:stdio": "tsx src/cli.mts --stdio",
+    "dev:port": "tsx src/cli.mts --http --port",
     "changeset": "changeset add",
     "version": "changeset version && npm install --lockfile-only",
     "release": "changeset publish"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "dotenv": "^17.2.1",
+    "express": "^4.18.2",
     "node-fetch": "^3.3.2",
     "yargs": "^17.7.2",
     "zod": "^3.22.4"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.1",
     "@changesets/cli": "^2.29.6",
+    "@types/express": "^4.17.21",
     "@types/node": "^20.10.0",
     "@types/node-fetch": "^2.6.9",
     "@types/yargs": "^17.0.32",

src/cli.mts

@@ -1,15 +1,20 @@
 #!/usr/bin/env node
 import {getServerConfig} from './config.mjs';
-import {startMcpServer} from './server.mjs';
+import {startMcpServer, startHttpServer} from './server.mjs';
 
 async function startServer(): Promise<void> {
     const config = getServerConfig();
 
     if (config.isStdioMode) {
         await startMcpServer(config.figmaApiKey);
+    } else if (config.isHttpMode) {
+        console.log('Starting Figma Flutter MCP Server in HTTP mode...');
+        await startHttpServer(config.httpPort, config.figmaApiKey);
     } else {
         console.log('Starting Figma Flutter MCP Server...');
         console.log('Use --stdio flag for MCP client communication');
+        console.log('Use --http flag for local testing via HTTP');
+        console.log('Use --help for more options');
     }
 }
 

src/config.mts

@@ -7,10 +7,14 @@ export interface ServerConfig {
     figmaApiKey: string;
     outputFormat: "yaml" | "json";
     isStdioMode: boolean;
+    isHttpMode: boolean;
+    httpPort: number;
     configSources: {
         figmaApiKey: "cli" | "env";
         envFile: "cli" | "default";
         stdio: "cli" | "env" | "default";
+        http: "cli" | "env" | "default";
+        port: "cli" | "env" | "default";
     };
 }
 
@@ -23,6 +27,8 @@ interface CliArgs {
     "figma-api-key"?: string;
     env?: string;
     stdio?: boolean;
+    http?: boolean;
+    port?: number;
 }
 
 export function getServerConfig(): ServerConfig {
@@ -42,6 +48,16 @@ export function getServerConfig(): ServerConfig {
                 description: "Run in stdio mode for MCP client communication",
                 default: false,
             },
+            http: {
+                type: "boolean",
+                description: "Run in HTTP mode for local testing",
+                default: false,
+            },
+            port: {
+                type: "number",
+                description: "Port number for HTTP server",
+                default: 3333,
+            },
         })
         .help()
         .version(process.env.npm_package_version || "0.0.1")
@@ -66,10 +82,14 @@ export function getServerConfig(): ServerConfig {
         figmaApiKey: "",
         outputFormat: "json",
         isStdioMode: false,
+        isHttpMode: false,
+        httpPort: 3333,
         configSources: {
             figmaApiKey: "env",
             envFile: envFileSource,
             stdio: "default",
+            http: "default",
+            port: "default",
         },
     };
 
@@ -91,6 +111,24 @@ export function getServerConfig(): ServerConfig {
         config.configSources.stdio = "env";
     }
 
+    // Handle HTTP mode
+    if (argv.http) {
+        config.isHttpMode = true;
+        config.configSources.http = "cli";
+    } else if (process.env.HTTP_MODE === "true") {
+        config.isHttpMode = true;
+        config.configSources.http = "env";
+    }
+
+    // Handle port configuration
+    if (argv.port) {
+        config.httpPort = argv.port;
+        config.configSources.port = "cli";
+    } else if (process.env.HTTP_PORT) {
+        config.httpPort = parseInt(process.env.HTTP_PORT, 10);
+        config.configSources.port = "env";
+    }
+
     // Validate configuration
     if (!config.figmaApiKey) {
         console.error("Error: FIGMA_API_KEY is required (via CLI argument or .env file)");
@@ -105,6 +143,10 @@ export function getServerConfig(): ServerConfig {
             `- FIGMA_API_KEY: ${maskApiKey(config.figmaApiKey)} (source: ${config.configSources.figmaApiKey})`
         );
         console.log(`- STDIO_MODE: ${config.isStdioMode} (source: ${config.configSources.stdio})`);
+        console.log(`- HTTP_MODE: ${config.isHttpMode} (source: ${config.configSources.http})`);
+        if (config.isHttpMode) {
+            console.log(`- HTTP_PORT: ${config.httpPort} (source: ${config.configSources.port})`);
+        }
         console.log(); // Empty line for better readability
     }