@fridaplatform-stk/figma2frida-mcp 1.0.1 → 1.0.3

package/README.md

@@ -1,216 +1,176 @@
 # Figma2Frida MCP Server
 
-Figma to Frida MCP Server - Bridge between Figma Desktop MCP and design system components with Pinecone search.
+> AI-powered bridge between Figma designs and your organization's design system components
 
-## Overview
+## 🎯 What Is Figma2Frida?
 
-This MCP server connects Figma Desktop MCP to your design system components stored in Pinecone, enabling intelligent component suggestions based on Figma designs.
+**Figma2Frida MCP Server** is a bridge that connects your AI coding assistant (Claude, Cursor, GitHub Copilot) with Figma designs and your organization's design system. It enables you to:
 
-## Features
+- **Generate production-ready code** directly from Figma designs
+- **Automatically use components** from your design system library
+- **Match components intelligently** using AI-powered semantic search
+- **Preserve exact layouts** - spacing, alignment, and visual hierarchy from Figma
+- **Get component documentation** - props, types, and usage examples included
 
-- 🔗 **Figma Integration**: Connects to Figma Desktop MCP
-- 🔍 **Pinecone Search**: Semantic search for design system components
-- 🤖 **Frida AI**: Intelligent component recommendations
-- 🎨 **Component Suggestions**: Suggests matching components based on Figma designs
-- 📸 **Screenshot Support**: Get visual screenshots from Figma
-- 🚀 **Fast Code Generation**: Optimized for rapid code generation
+### Available Tools
 
-## Prerequisites
+Your AI assistant gets four specialized tools:
 
-- Node.js 18+ 
-- Figma Desktop with MCP enabled (running at `http://127.0.0.1:3845/sse`)
-- Pinecone account with API key
-- Frida AI account with bearer token
+1. **`figma_get_design_context`** - Generate code from Figma with automatic component matching *(main tool)*
+2. **`figma_suggest_components`** - Browse and discover design system components
+3. **`figma_get_screenshot`** - Quick visual reference from Figma
+4. **`figma_improve_layout`** - Fine-tune generated code to match Figma exactly
 
-## Installation
+## 🔄 How It Works
 
-```bash
-# Clone the repository
-git clone <your-repo-url>
-cd figma2frida_mcp
-
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
 ```
-
-## Configuration
-
-### Environment Variables
-
-Create a `.env` file in the project root with the following variables:
-
-```bash
-# Pinecone Configuration
-PINECONE_API_KEY=your_pinecone_api_key_here
-PINECONE_INDEX_NAME=your_index_name
-# PINECONE_NAMESPACE is passed as argument (not in .env)
-
-# Frida AI Configuration
-FRIDA_BEARER_TOKEN=your_frida_bearer_token_here
-FRIDA_BASE_URL=https://api.frida.ai
-
-# Server Configuration (optional)
-HTTP_STREAM=true  # Set to true for HTTP mode, false for stdio
-PORT=8080         # Port for HTTP stream mode
+1. Select design in Figma
+   ↓
+2. Ask your AI: "Generate code for this design"
+   ↓
+3. MCP fetches design → Searches your component library → Uses Frida AI
+   ↓
+4. Get production-ready code with your design system components
 ```
 
-**Important**: `PINECONE_NAMESPACE` should NOT be in `.env` - it's passed as a command-line argument.
-
-## Local Development
+**Behind the scenes:**
+- Connects to Figma Desktop (local MCP server)
+- Searches your component library in Pinecone
+- Uses Frida AI for intelligent component matching
+- Validates your API token via Firebase
 
-### Running Locally
+## 📦 Installation
 
-Use the `run-local.sh` script for local testing:
+### Step 1: Install the Package
 
 ```bash
-# Make sure the script is executable
-chmod +x run-local.sh
-
-# With default namespace (org01_proj01)
-./run-local.sh
-
-# With custom namespace
-./run-local.sh org02_proj02
+npm install -g @fridaplatform-stk/figma2frida-mcp
 ```
 
-The script will:
-- Start the server in HTTP Stream mode
-- Use the namespace from the command-line argument
-- Load all other settings from `.env` file
-- Make the server available at `http://localhost:8080/mcp`
+### Step 2: Configure Your AI Assistant
 
-### Testing the Server
+Add to your configuration file:
 
-Once running, test with curl:
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 
-```bash
-curl -X POST http://localhost:8080/mcp \
-  -H "Content-Type: application/json" \
-  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+```json
+{
+  "mcpServers": {
+    "figma2frida": {
+      "command": "npx",
+      "args": [
+        "@fridaplatform-stk/figma2frida-mcp",
+        "--project-id",
+        "YOUR_PROJECT_ID",
+        "--frida-api-token",
+        "YOUR_API_TOKEN"
+      ]
+    }
+  }
+}
 ```
 
-## Visual Studio / GitHub Copilot Setup
-
-### Configuration
-
-Add this to your MCP configuration file (location depends on your IDE):
+**Cursor** (similar configuration in settings):
 
 ```json
 {
   "mcpServers": {
     "figma2frida": {
-      "command": "node",
+      "command": "npx",
       "args": [
-        "/absolute/path/to/figma2frida_mcp/dist/figma2frida.js",
-        "--pinecone-namespace",
-        "org01_proj01"
+        "@fridaplatform-stk/figma2frida-mcp",
+        "--project-id",
+        "YOUR_PROJECT_ID",
+        "--frida-api-token",
+        "YOUR_API_TOKEN"
       ]
     }
   }
 }
 ```
 
-**Important**:
-- Use the **absolute path** to `dist/figma2frida.js`
-- Replace `org01_proj01` with your namespace
-- Make sure you've run `npm run build` first
-- The `.env` file should be in the project root
+### Step 3: Restart Your AI Assistant
 
-### Restart Your IDE
+Restart Claude Desktop, Cursor, or your IDE to load the MCP server.
 
-After adding the configuration, restart Visual Studio / GitHub Copilot to load the MCP server.
+## 🔑 Getting Access Tokens
 
-## Available Tools
+To use Figma2Frida, you need:
+- **Project ID** - Your organization's project identifier
+- **Frida API Token** - Authentication token for Frida services
 
-- `figma_get_screenshot` - Get visual screenshot from Figma (fast)
-- `figma_get_design_context` - Get design data and generated code (with caching & streaming)
-- `figma_suggest_components` - Suggest design system components based on Figma design (with Pinecone & Frida AI)
-- `figma_improve_layout` - Trigger layout improvement to match Figma frame reference
+### How to Get Tokens
 
-## Project Structure
+**Contact the Softtek Frida Team:**
 
-```
-figma2frida_mcp/
-├── src/
-│   └── figma2frida/
-│       ├── figma2frida.ts          # Main MCP server
-│       ├── clients/
-│       │   └── figma-client.ts     # Figma Desktop MCP client
-│       ├── handlers/
-│       │   └── component-suggestion-handler.ts
-│       ├── services/
-│       │   ├── component-lookup.ts
-│       │   ├── frida/
-│       │   │   └── frida-client.ts
-│       │   └── pinecone/
-│       │       └── pinecone-service.ts
-│       └── utils/
-│           ├── component-extractor.ts
-│           ├── design-query-extractor.ts
-│           └── formatters.ts
-├── dist/
-│   ├── figma2frida.js              # Built server (for production)
-│   └── figma2frida.d.ts
-├── run-local.sh                     # Local development script
-├── .env                             # Environment variables (create this)
-└── package.json
-```
+📧 Reach out to your organization's Frida team or Softtek Frida support to request access.
 
-## Development
+You'll need to provide:
+- Your organization name
+- Intended use case
+- Team/project information
 
-### Build
+The Frida team will provide your credentials securely.
 
-```bash
-npm run build
-```
+### 💡 Recommended: Frida Code Copilot Extension
 
-### Development Mode
+For the best experience, also install the **[Frida Code Copilot VS Code Extension](https://marketplace.visualstudio.com/)**:
 
-```bash
-npm run dev
-```
+- Automatically manages your projects and components
+- Visual component browser in VS Code
+- Real-time component library updates
+- Works seamlessly with this MCP server
 
-## Publishing to npm
+## 📋 Prerequisites
 
-```bash
-# Build first
-npm run build
+- **Node.js 18+**
+- **Figma Desktop** with MCP enabled
+- **Frida API Token** (contact Softtek Frida team)
+
+## 🚀 Example Usage
+
+Once configured, simply ask your AI assistant:
 
-# Publish
-npm publish
+```
+"Generate React code for this Figma button component"
 ```
 
-After publishing, users can install globally:
+```
+"What card components are available in my design system?"
+```
 
-```bash
-npm install -g @fridaplatform-stk/figma2frida-mcp
-figma2frida-mcp --pinecone-namespace org01_proj01
 ```
+"Update this code to match the Figma spacing exactly"
+```
+
+The AI will automatically use the Figma2Frida tools to help you.
+
+## 🐛 Troubleshooting
+
+**"Authentication failed"**
+→ Verify your Frida API token with the Softtek team
+
+**"Not connected to Figma MCP"**
+→ Make sure Figma Desktop is running with MCP enabled
 
-## Troubleshooting
+**"Missing required argument"**
+→ Check both `--project-id` and `--frida-api-token` are in your config
 
-### "Cannot find module 'fastmcp'"
-Run `npm install` to install dependencies.
+**"Rate limit exceeded"**
+→ Wait a few minutes before trying again
 
-### "Figma MCP connection failed"
-Make sure Figma Desktop is running with MCP enabled at `http://127.0.0.1:3845/sse`.
+## 🤝 Support
 
-### "Pinecone namespace not found"
-Make sure you're passing `--pinecone-namespace` as an argument (not in `.env`).
+- **Softtek Frida Team**: Contact for access tokens and support
 
-### Visual Studio can't find the MCP server
-- Check the absolute path is correct
-- Make sure `dist/figma2frida.js` exists (run `npm run build`)
-- Check Visual Studio's MCP logs for errors
+## 📄 License
 
-## License
+MIT License
 
-MIT
+## 👥 Author
 
-## Author
+**Frida Platform STK** - Softtek
 
-Frida Platform STK
+---
 
+Made with ❤️ by the Frida team