zapcode-figma-mcp 1.1.0 → 1.1.2

package/README.md

@@ -1,112 +1,210 @@
-Generated markdown
-
 # Zapcode Figma MCP Server
 
 [![npm version](https://img.shields.io/npm/v/zapcode-figma-mcp.svg)](https://www.npmjs.com/package/zapcode-figma-mcp)
-<!-- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -->
 
-This package provides a Model Context Protocol (MCP) server that acts as a bridge between your **Figma designs** and any **MCP-compatible AI client** (like Claude for Desktop, Open WebUI, etc.).
 
-When invoked by an AI model, this server connects to the Zapcode Figma plugin to retrieve real-time context from your selected Figma frame, including its HTML/CSS structure, a generated image, and any exportable SVG assets.
+Connect your Figma designs directly to AI tools like Claude Desktop, Cursor, and Cline. Get real-time HTML, CSS, images, and assets from selected Figma frames through the Model Context Protocol.
 
-## ✨ Features
+## Features
 
-- **Real-time Context**: Fetches live data directly from your currently selected frame in Figma.
-- **Rich Information**: Provides the LLM with rich context of the frame.
-- **Automatic Asset Handling**: Automatically extracts any SVG assets from the selection, saves them to your local workspace, and informs the LLM of their location.
-- **Easy Integration**: Runs as a simple command-line tool and can be easily configured with any MCP client.
+- **Real-time Design Context** - Fetches live data from your currently selected Figma frame
+- **Complete Asset Export** - Supports SVG, PNG, JPG, PDF, and all Figma asset types
+- **Configurable Storage** - Save assets to custom paths or default workspace location
+- **Auto-organized Assets** - Assets grouped by type (svg/, png/, jpg/, etc.)
+- **Zero Configuration** - Works out of the box with npx
+- **Rich Context** - Provides HTML structure, CSS styles, images, and design specifications
 
-## 📋 Prerequisites
+## Prerequisites
 
-1.  **Node.js**: You must have Node.js (v16 or higher) installed to use `npx`. You can download it from [nodejs.org](https://nodejs.org/).
-2.  [**Zapcode Figma Plugin**](https://www.figma.com/community/plugin/1454956820198178710/zapcode): You must have the Zapcode plugin installed and running in your Figma desktop application.
+1. **Node.js 16+** - [Download here](https://nodejs.org/)
+2. **Figma Desktop App** - Required for plugin integration
+3. **[Zapcode Figma Plugin](https://www.figma.com/community/plugin/1454956820198178710/zapcode)** - Install from Figma Community
 
-## 🚀 Installation & Usage
+## Installation
 
-You can run this server directly from the npm registry without a manual installation using `npx`.
+### Claude Desktop
 
-## Integration with an MCP Client
+Add to your `claude_desktop_config.json`:
 
-This is the most common use case. You configure your client to launch the server automatically. Below are examples for common clients.
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
 
-### Generic MCP Client Configuration
+```json
+{
+  "mcpServers": {
+    "zapcode-figma": {
+      "command": "npx",
+      "args": ["-y", "zapcode-figma-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after making changes.
 
-For clients that use a similar JSON configuration, the structure is the same. This server does not require any environment variables.
+### Cursor
+
+Add to your MCP settings configuration:
 
 ```json
 {
   "mcpServers": {
-    "zapcode-figma-mcp": {
+    "zapcode-figma": {
       "command": "npx",
-      "args": ["zapcode-figma-mcp"]
+      "args": ["-y", "zapcode-figma-mcp"]
     }
   }
 }
 ```
 
-### GitHub Copilot
+### Cline (VS Code Extension)
+
+Add to Cline's MCP settings:
 
 ```json
 {
-  "servers": {
-    "Zapcode stdio mcp": {
-      "type": "stdio",
+  "mcpServers": {
+    "zapcode-figma": {
       "command": "npx",
-      "args": ["zapcode-figma-mcp"]
+      "args": ["-y", "zapcode-figma-mcp"]
     }
-  },
-  "inputs": []
+  }
 }
 ```
 
-### Claude for Desktop
+### Windsurf
 
-Open your claude_desktop_config.json file and add the following entry to mcpServers.
-
-macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
-Windows: %APPDATA%\Claude\claude_desktop_config.json
+Add to your Windsurf MCP configuration:
 
 ```json
 {
   "mcpServers": {
-    "zapcode-figma-mcp": {
+    "zapcode-figma": {
       "command": "npx",
-      "args": ["zapcode-figma-mcp"]
+      "args": ["-y", "zapcode-figma-mcp"]
     }
   }
 }
 ```
 
-**Note:** Restart Claude for Desktop for the changes to take effect.
+### Zed Editor
 
-The server will start and wait for connections from both the Figma plugin and an MCP client.
+Add to your Zed settings (MCP support currently in preview):
 
-## 🛠️ Tool Details
+```json
+{
+  "context_servers": {
+    "zapcode-figma": {
+      "command": "npx",
+      "args": ["-y", "zapcode-figma-mcp"]
+    }
+  }
+}
+```
 
-This server exposes a single, powerful tool to the LLM.
+### Continue (VS Code/JetBrains)
 
-get_figma_context
+Add to Continue's configuration:
+
+```json
+{
+  "mcpServers": {
+    "zapcode-figma": {
+      "command": "npx",
+      "args": ["-y", "zapcode-figma-mcp"]
+    }
+  }
+}
+```
 
-- **Description**: Retrieves the selected Figma frame context. Saves any provided SVG assets to the local 'assets/svg' directory.
-- **Input Schema**: {} (No input arguments are required).
-- **Output**: A combination of prompts and Figma context
+### GitHub Copilot
 
-## ⚠️ Troubleshooting
+Add to your GitHub Copilot MCP configuration:
 
-```error
-Error: Figma plugin is not connected.
+```json
+{
+  "servers": {
+    "zapcode-figma": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "zapcode-figma-mcp"]
+    }
+  }
+}
 ```
 
-This is the most common error. It means the MCP server is running, but it cannot find the Zapcode Figma plugin to talk to.
-Solution: Make sure you have opened Figma and are running the Zapcode plugin on the design file you wish to query.
+## How It Works
+
+1. **Install Plugin** - Add Zapcode plugin to Figma Desktop
+2. **Run Plugin** - Launch Zapcode plugin from Figma
+3. **Select Frame** - Choose any frame in your Figma design
+4. **Ask AI** - Ask AI to bring you the figma context
+5. **Get Context** - Receive complete design data and assets
+
 
-```error
-Port Conflict / EADDRINUSE Error
+## Troubleshooting
+
+### "Figma plugin is not connected"
+
+**Cause**: MCP server cannot reach the Zapcode Figma plugin.
+
+**Solution**:
+1. Open Figma Desktop App
+2. Open your design file
+3. Run Zapcode plugin (Plugins → Zapcode)
+4. Ensure plugin window stays open
+5. Retry connecting using toggle
+5. Try the MCP tool again
+
+### Assets Not Saving
+
+**Cause**: Permission issues or invalid path.
+
+**Solution**:
+1. Ensure the assets path exists or parent directory is writable
+2. Use absolute paths for clarity
+3. Check file permissions on the target directory
+
+## Asset Organization
+
+Assets are automatically organized by type:
+
+```
+assets/
+├── svg/
+│   ├── icon_component.svg
+│   └── logo.svg
+├── png/
+│   ├── screenshot_1.png
+│   └── image_export.png
+└── jpg/
+    └── photo.jpg
 ```
 
-If you see an error that the port is already in use, it means another application is using port 3001 or 32896.
-Solution: You need to stop the other application.
+## Supported Clients
+
+This server works with any MCP-compatible client, including:
+
+- [Claude Desktop](https://modelcontextprotocol.io/clients#claude-desktop) - Anthropic's desktop application
+- [Cursor](https://www.cursor.com/) - AI-first code editor
+- [Cline](https://github.com/cline/cline) - Autonomous coding agent for VS Code
+- [Windsurf](https://codeium.com/windsurf) - AI-powered IDE with MCP Plugin Store
+- [Zed](https://zed.dev/) - High-performance code editor (MCP in preview)
+- [Continue](https://continue.dev/) - Open-source IDE extension
+- [GitHub Copilot](https://github.com/features/copilot) - With MCP support in VS Code
+
+
+## Links
+
+- [NPM Package](https://www.npmjs.com/package/zapcode-figma-mcp)
+- [Zapcode Figma Plugin](https://www.figma.com/community/plugin/1454956820198178710/zapcode)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [MCP Servers Collection](https://github.com/modelcontextprotocol/servers)
 
-## 📄 License
+---
 
-This project is licensed under the MIT License. See the LICENSE.md file for details.
+**Sources:**
+- [Model Context Protocol Official Servers](https://github.com/modelcontextprotocol/servers)
+- [GitHub MCP Server](https://github.com/github/github-mcp-server)
+- [MCP Clients Directory](https://github.com/punkpeye/awesome-mcp-clients)
+- [Official MCP Client Examples](https://modelcontextprotocol.io/clients)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "zapcode-figma-mcp",
-    "version": "1.1.0",
+    "version": "1.1.2",
     "description": "An MCP server that exposes Figma context via a plugin and saves assets, from Zapcode.",
     "type": "module",
     "bin": {