Skip to content

Latest commit

 

History

History
202 lines (154 loc) · 4.83 KB

CONTRIBUTING.md

File metadata and controls

202 lines (154 loc) · 4.83 KB

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

    git clone https://github.com/your-username/figma-flutter-mcp.git
cd figma-flutter-mcp
npm install

  2. Create .env file

    # Create .env file with your Figma API key
echo "FIGMA_API_KEY=your-figma-api-key-here" > .env

  3. Start Development Server

    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

    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

    # Build and check for errors
npm run build

# Test locally
npm run dev

  4. Commit and Push

    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:

# 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
  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)

# 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

# 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

# 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:

{
  "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)

# 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! 🚀