mirror of
https://github.com/github/awesome-copilot.git
synced 2026-02-24 04:15:14 +00:00
Add Penpot MCP server setup and troubleshooting guide
This commit is contained in:
Jacrdif
@@ -16,10 +16,69 @@ Create professional, user-centered designs in Penpot using the `penpot/penpot-mc
|
||||
| `mcp__penpot__import_image` | Import images (icons, photos, logos) into designs |
|
||||
| `mcp__penpot__penpot_api_info` | Retrieve Penpot API documentation |
|
||||
|
||||
## MCP Server Setup
|
||||
|
||||
The Penpot MCP tools require the `penpot/penpot-mcp` server running locally. For detailed installation and troubleshooting, see [setup-troubleshooting.md](references/setup-troubleshooting.md).
|
||||
|
||||
### Before Setup: Check If Already Running
|
||||
|
||||
**Always check if the MCP server is already available before attempting setup:**
|
||||
|
||||
1. **Try calling a tool first**: Attempt `mcp__penpot__penpot_api_info` - if it succeeds, the server is running and connected. No setup needed.
|
||||
|
||||
2. **If the tool fails**, ask the user:
|
||||
> "The Penpot MCP server doesn't appear to be connected. Is the server already installed and running? If so, I can help troubleshoot. If not, I can guide you through the setup."
|
||||
|
||||
3. **Only proceed with setup instructions if the user confirms the server is not installed.**
|
||||
|
||||
### Quick Start (Only If Not Installed)
|
||||
|
||||
```bash
|
||||
# Clone and install
|
||||
git clone https://github.com/penpot/penpot-mcp.git
|
||||
cd penpot-mcp
|
||||
npm install
|
||||
|
||||
# Build and start servers
|
||||
npm run bootstrap
|
||||
```
|
||||
|
||||
Then in Penpot:
|
||||
1. Open a design file
|
||||
2. Go to **Plugins** → **Load plugin from URL**
|
||||
3. Enter: `http://localhost:4400/manifest.json`
|
||||
4. Click **"Connect to MCP server"** in the plugin UI
|
||||
|
||||
### VS Code Configuration
|
||||
|
||||
Add to `settings.json`:
|
||||
```json
|
||||
{
|
||||
"mcp": {
|
||||
"servers": {
|
||||
"penpot": {
|
||||
"url": "http://localhost:4401/sse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Troubleshooting (If Server Is Installed But Not Working)
|
||||
|
||||
| Issue | Solution |
|
||||
| ----- | -------- |
|
||||
| Plugin won't connect | Check servers are running (`npm run start:all` in penpot-mcp dir) |
|
||||
| Browser blocks localhost | Allow local network access prompt, or disable Brave Shield, or try Firefox |
|
||||
| Tools not appearing in client | Restart VS Code/Claude completely after config changes |
|
||||
| Tool execution fails/times out | Ensure Penpot plugin UI is open and shows "Connected" |
|
||||
| "WebSocket connection failed" | Check firewall allows ports 4400, 4401, 4402 |
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Reference File |
|
||||
| ---- | -------------- |
|
||||
| MCP server installation & troubleshooting | [setup-troubleshooting.md](references/setup-troubleshooting.md) |
|
||||
| Component specs (buttons, forms, nav) | [component-patterns.md](references/component-patterns.md) |
|
||||
| Accessibility (contrast, touch targets) | [accessibility.md](references/accessibility.md) |
|
||||
| Screen sizes & platform specs | [platform-guidelines.md](references/platform-guidelines.md) |
|
||||
|
||||
328
skills/penpot-uiux-design/references/setup-troubleshooting.md
Normal file
328
skills/penpot-uiux-design/references/setup-troubleshooting.md
Normal file
@@ -0,0 +1,328 @@
|
||||
# Penpot MCP Server Setup & Troubleshooting
|
||||
|
||||
Complete guide for installing, configuring, and troubleshooting the Penpot MCP Server.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
The Penpot MCP integration requires **three components** working together:
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ MCP Client │────▶│ MCP Server │◀───▶│ Penpot Plugin │
|
||||
│ (VS Code/Claude)│ │ (port 4401) │ │ (in browser) │
|
||||
└─────────────────┘ └────────┬────────┘ └────────┬────────┘
|
||||
│ │
|
||||
│ WebSocket │
|
||||
│ (port 4402) │
|
||||
└───────────────────────┘
|
||||
```
|
||||
|
||||
1. **MCP Server** - Exposes tools to your AI client (HTTP on port 4401)
|
||||
2. **Plugin Server** - Serves the Penpot plugin files (HTTP on port 4400)
|
||||
3. **Penpot MCP Plugin** - Runs inside Penpot browser, executes design commands
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Node.js v22+** - [Download](https://nodejs.org/)
|
||||
- **Git** - For cloning the repository
|
||||
- **Modern browser** - Chrome, Firefox, or Chromium-based browser
|
||||
|
||||
Verify Node.js installation:
|
||||
```bash
|
||||
node --version # Should be v22.x or higher
|
||||
npm --version
|
||||
npx --version
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
### Step 1: Clone and Install
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/penpot/penpot-mcp.git
|
||||
cd penpot-mcp
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
```
|
||||
|
||||
### Step 2: Build and Start Servers
|
||||
|
||||
```bash
|
||||
# Build all components and start servers
|
||||
npm run bootstrap
|
||||
```
|
||||
|
||||
This command:
|
||||
|
||||
- Installs dependencies for all components
|
||||
- Builds the MCP server and plugin
|
||||
- Starts both servers (MCP on 4401, Plugin on 4400)
|
||||
|
||||
**Expected output:**
|
||||
|
||||
```txt
|
||||
MCP Server listening on http://localhost:4401
|
||||
Plugin server listening on http://localhost:4400
|
||||
WebSocket server listening on port 4402
|
||||
```
|
||||
|
||||
### Step 3: Load Plugin in Penpot
|
||||
|
||||
1. Open [Penpot](https://design.penpot.app/) in your browser
|
||||
2. Open or create a design file
|
||||
3. Go to **Plugins** menu (or press the plugins icon)
|
||||
4. Click **Load plugin from URL**
|
||||
5. Enter: `http://localhost:4400/manifest.json`
|
||||
6. The plugin UI will appear - click **"Connect to MCP server"**
|
||||
7. Status should change to **"Connected to MCP server"**
|
||||
|
||||
> **Important**: Keep the plugin UI open while using MCP tools. Closing it disconnects the server.
|
||||
|
||||
### Step 4: Configure Your MCP Client
|
||||
|
||||
#### VS Code with GitHub Copilot
|
||||
|
||||
Add to your VS Code `settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp": {
|
||||
"servers": {
|
||||
"penpot": {
|
||||
"url": "http://localhost:4401/sse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Or use the HTTP endpoint:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp": {
|
||||
"servers": {
|
||||
"penpot": {
|
||||
"url": "http://localhost:4401/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Claude Desktop
|
||||
|
||||
Claude Desktop requires the `mcp-remote` proxy (stdio-only transport):
|
||||
|
||||
1. Install the proxy:
|
||||
|
||||
```bash
|
||||
npm install -g mcp-remote
|
||||
```
|
||||
|
||||
2. Edit Claude Desktop config:
|
||||
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
|
||||
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
|
||||
|
||||
3. Add the Penpot server:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"penpot": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "mcp-remote", "http://localhost:4401/sse", "--allow-http"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
4. **Fully quit** Claude Desktop (File → Quit, not just close window) and restart
|
||||
|
||||
#### Claude Code (CLI)
|
||||
|
||||
```bash
|
||||
claude mcp add penpot -t http http://localhost:4401/mcp
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Issues
|
||||
|
||||
#### "Plugin cannot connect to MCP server"
|
||||
|
||||
**Symptoms**: Plugin shows "Not connected" even after clicking Connect
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Verify servers are running:
|
||||
```bash
|
||||
# Check if ports are in use
|
||||
lsof -i :4401 # MCP server
|
||||
lsof -i :4402 # WebSocket
|
||||
lsof -i :4400 # Plugin server
|
||||
```
|
||||
|
||||
2. Restart the servers:
|
||||
|
||||
```bash
|
||||
# In the penpot-mcp directory
|
||||
npm run start:all
|
||||
```
|
||||
|
||||
3. Check browser console (F12) for WebSocket errors
|
||||
|
||||
#### Browser Blocks Local Connection
|
||||
|
||||
**Symptoms**: Browser refuses to connect to localhost from Penpot
|
||||
|
||||
**Cause**: Chromium 142+ enforces Private Network Access (PNA) restrictions
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. **Chrome/Chromium**: When prompted, allow access to local network
|
||||
2. **Brave**: Disable Shield for the Penpot website:
|
||||
- Click the Brave Shield icon in address bar
|
||||
- Toggle Shield off for this site
|
||||
3. **Try Firefox**: Firefox doesn't enforce these restrictions as strictly
|
||||
|
||||
#### "WebSocket connection failed"
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Check firewall settings - allow ports 4400, 4401, 4402
|
||||
2. Disable VPN if active
|
||||
3. Check for conflicting applications using the same ports
|
||||
|
||||
### MCP Client Issues
|
||||
|
||||
#### Tools Not Appearing in VS Code/Claude
|
||||
|
||||
1. **Verify endpoint**:
|
||||
|
||||
```bash
|
||||
# Test the SSE endpoint
|
||||
curl http://localhost:4401/sse
|
||||
|
||||
# Test the MCP endpoint
|
||||
curl http://localhost:4401/mcp
|
||||
```
|
||||
|
||||
2. **Check configuration syntax** - JSON must be valid
|
||||
3. **Restart the MCP client** completely
|
||||
4. **Check MCP server logs**:
|
||||
|
||||
```bash
|
||||
# Logs are in mcp-server/logs/
|
||||
tail -f mcp-server/logs/mcp-server.log
|
||||
```
|
||||
|
||||
#### "Tool execution timed out"
|
||||
|
||||
**Cause**: Plugin disconnected or operation took too long
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Ensure plugin UI is still open in Penpot
|
||||
2. Verify plugin shows "Connected" status
|
||||
3. Try reconnecting: click Disconnect then Connect in plugin
|
||||
|
||||
### Plugin Issues
|
||||
|
||||
#### "Plugin failed to load"
|
||||
|
||||
1. Verify plugin server is running on port 4400
|
||||
2. Try accessing `http://localhost:4400/manifest.json` directly in browser
|
||||
3. Clear browser cache and reload Penpot
|
||||
4. Remove and re-add the plugin
|
||||
|
||||
#### "Cannot find penpot object"
|
||||
|
||||
**Cause**: Plugin not properly initialized or design file not open
|
||||
|
||||
**Solutions**:
|
||||
|
||||
1. Make sure you have a design file open (not just the dashboard)
|
||||
2. Wait a few seconds after opening file before connecting
|
||||
3. Refresh Penpot and reload the plugin
|
||||
|
||||
### Server Issues
|
||||
|
||||
#### Port Already in Use
|
||||
|
||||
```bash
|
||||
# Find process using the port
|
||||
lsof -i :4401
|
||||
|
||||
# Kill the process if needed
|
||||
kill -9 <PID>
|
||||
```
|
||||
|
||||
Or configure different ports via environment variables:
|
||||
```bash
|
||||
PENPOT_MCP_SERVER_PORT=4501 npm run start:all
|
||||
```
|
||||
|
||||
#### Server Crashes on Startup
|
||||
|
||||
1. Check Node.js version (must be v22+)
|
||||
2. Delete `node_modules` and reinstall:
|
||||
|
||||
```bash
|
||||
rm -rf node_modules
|
||||
npm install
|
||||
npm run bootstrap
|
||||
```
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `PENPOT_MCP_SERVER_PORT` | 4401 | HTTP/SSE server port |
|
||||
| `PENPOT_MCP_WEBSOCKET_PORT` | 4402 | WebSocket server port |
|
||||
| `PENPOT_MCP_SERVER_LISTEN_ADDRESS` | localhost | Server bind address |
|
||||
| `PENPOT_MCP_LOG_LEVEL` | info | Log level (trace/debug/info/warn/error) |
|
||||
| `PENPOT_MCP_LOG_DIR` | logs | Log file directory |
|
||||
| `PENPOT_MCP_REMOTE_MODE` | false | Enable remote mode (disables file system access) |
|
||||
|
||||
### Example: Custom Configuration
|
||||
|
||||
```bash
|
||||
# Run on different ports with debug logging
|
||||
PENPOT_MCP_SERVER_PORT=5000 \
|
||||
PENPOT_MCP_WEBSOCKET_PORT=5001 \
|
||||
PENPOT_MCP_LOG_LEVEL=debug \
|
||||
npm run start:all
|
||||
```
|
||||
|
||||
## Verifying the Setup
|
||||
|
||||
Run this checklist to confirm everything works:
|
||||
|
||||
1. **Servers Running**:
|
||||
```bash
|
||||
curl -s http://localhost:4401/sse | head -1
|
||||
# Should return SSE stream headers
|
||||
```
|
||||
|
||||
2. **Plugin Connected**: Plugin UI shows "Connected to MCP server"
|
||||
|
||||
3. **Tools Available**: In your MCP client, verify these tools appear:
|
||||
- `mcp__penpot__execute_code`
|
||||
- `mcp__penpot__export_shape`
|
||||
- `mcp__penpot__import_image`
|
||||
- `mcp__penpot__penpot_api_info`
|
||||
|
||||
4. **Test Execution**: Ask your AI assistant to run a simple command:
|
||||
> "Use Penpot to get the current page name"
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **GitHub Issues**: [penpot/penpot-mcp/issues](https://github.com/penpot/penpot-mcp/issues)
|
||||
- **GitHub Discussions**: [penpot/penpot-mcp/discussions](https://github.com/penpot/penpot-mcp/discussions)
|
||||
- **Penpot Community**: [community.penpot.app](https://community.penpot.app/)
|
||||
Reference in New Issue
Block a user