github/penpot-mcp
1
0
Fork 0
mirror of https://github.com/penpot/penpot-mcp.git synced 2026-04-25 11:18:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update README

Browse Source
This commit is contained in:
Dominik Jain 2025-09-11 12:00:44 +02:00
parent f8b6c05df4
commit 966a39eb5c
2 changed files with 46 additions and 143 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
mcp-server/.prettierignore Normal file
View File

@ -0,0 +1 @@
*.md

188
mcp-server/README.md
View File

@ -2,61 +2,36 @@
A Model Context Protocol (MCP) server that provides Penpot integration capabilities for Claude Desktop and other MCP-compatible clients.
## Overview
This MCP server implements a clean, object-oriented architecture that allows easy extension with new tools.
It currently includes a demonstration tool and provides a foundation for adding Penpot-specific functionality.
## Prerequisites
- Node.js 18+
- Node.js (tested with v20+)
- npm
## Installation & Setup
### 1. Install Dependencies
1. Install Dependencies
```bash
cd mcp-server
npm install
```
cd mcp-server
npm install
### 2. Build the Project
2. Build the Project
```bash
npm run build
```
npm run build
### 3. Run the Server
3. Run the Server
**Development Mode** (with TypeScript compilation):
- Development Mode (with TypeScript compilation):
```bash
npm run dev
```
npm run dev
**Production Mode** (requires build first):
- Production Mode (requires build first):
```bash
npm start
```
npm start
**With Custom Port**:
A custom port can be specified: `npm start -- --port 8080`
```bash
npm start -- --port 8080
# OR in development
npm run dev -- --port 8080
# OR directly
node dist/index.js --port 8080
```
**Available Options**:
- `--port, -p <number>`: Port number for the HTTP/SSE server (default: 4401)
- `--help, -h`: Show help message
## Available Commands
### Summary of Commands
| Command | Description |
| ---------------------- | -------------------------------------- |
@ -67,16 +42,20 @@ node dist/index.js --port 8080
| `npm run format` | Format all files with Prettier |
| `npm run format:check` | Check if files are properly formatted |
## Claude Desktop Integration
The MCP server now supports both modern Streamable HTTP and legacy SSE transports, providing compatibility with various MCP clients.
## Client Integration
### 1. Start the Server
The MCP server supports both Streamable HTTP and legacy SSE transports, providing compatibility with various MCP clients.
Note that we do not support stdio transport directly, as clients tend to spawn multiple instances of the MCP server,
and since the MCP server is also a WebSocket server, this would lead to port conflicts.
Therefore, we recommend using a proxy like `mcp-remote` for clients that support stdio transport only (e.g., Claude Desktop).
### Starting the Server
First, build and start the MCP server:
```bash
cd mcp-server
npm run build
npm start
```
@ -86,22 +65,27 @@ By default, the server runs on port 4401 and provides:
- **Modern Streamable HTTP endpoint**: `http://localhost:4401/mcp`
- **Legacy SSE endpoint**: `http://localhost:4401/sse`
### 2. Configure Claude Desktop
### Using a Proxy for stdio Transport
For Claude Desktop integration, you'll need to use a proxy since Claude Desktop requires stdio transport.
The `mcp-remote` package can proxy stdio transport to HTTP/SSE.
**Option A: Using mcp-remote (Recommended)**
1. Install `mcp-remote` globally if you haven't already:
Install mcp-remote globally if you haven't already:
npm install -g mcp-remote
```bash
npm install -g mcp-remote
```
2. Use `mcp-remote` to provide the launch command for your MCP client:
Add this to your Claude Desktop configuration file:
npx -y mcp-remote http://localhost:4401/sse --allow-http
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
### Claude Desktop
For Claude Desktop integration, you will need to use a proxy like `mcp-remote` since it only supports stdio transport.
So install it as described above.
To add the server to Claude Desktop's configuration, locate the configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
```json
{
@ -114,98 +98,16 @@ Add this to your Claude Desktop configuration file:
}
```
**Option B: Direct HTTP Integration (for other MCP clients)**
After updating the configuration file, restart Claude Desktop completely for the changes to take effect.
Be sure to fully quit the app! On Windows, right-click the tray icon and select "Quit".
After the restart, you should see the MCP server listed when clicking on the "Search and tools" icon at the bottom
of the prompt input area.
### Other MCP Clients
For MCP clients that support HTTP transport directly, use:
- Modern clients: `http://localhost:4401/mcp`
- Legacy clients: `http://localhost:4401/sse`
- Streamable HTTP for modern clients: `http://localhost:4401/mcp`
- SSE for legacy clients: `http://localhost:4401/sse`
### 3. Restart Claude Desktop
After updating the configuration file, restart Claude Desktop completely for the changes to take effect.
### 4. Verify Integration
Once Claude Desktop restarts, you should be able to use the MCP server's tools in your conversations. You can test with the included `hello_world` tool:
```
Can you use the hello_world tool to greet me?
```
## Adding New Tools
To add new tools to the MCP server:
1. **Create Tool Class**: Implement the `Tool` interface in `src/tools/`
2. **Register Tool**: Add your tool instance to the `registerTools()` method in `src/index.ts`
3. **Build**: Run `npm run build` to compile changes
4. **Restart**: Restart Claude Desktop to load the new functionality
Example tool implementation:
```typescript
import { Tool } from "../interfaces/Tool.js";
import { Tool as MCPTool } from "@modelcontextprotocol/sdk/types.js";
export class MyCustomTool implements Tool {
readonly definition: MCPTool = {
name: "my_tool",
description: "Description of what this tool does",
inputSchema: {
type: "object",
properties: {
// Define your parameters here
},
required: [],
additionalProperties: false,
},
};
async execute(args: unknown): Promise<{ content: Array<{ type: string; text: string }> }> {
// Implement your tool logic here
return {
content: [
{
type: "text",
text: "Tool result",
},
],
};
}
}
```
## Troubleshooting
### Server Won't Start
- Ensure all dependencies are installed: `npm install`
- Check that the project builds without errors: `npm run build`
- Verify Node.js version is 18 or higher: `node --version`
### Claude Desktop Can't Find Server
- Verify the absolute path in your configuration is correct
- Ensure the server is built (`npm run build`) before referencing `dist/index.js`
- Check that the JSON configuration file is valid
- Restart Claude Desktop completely after config changes
### Tools Not Available
- Confirm the server is listed in Claude Desktop's configuration
- Check the Claude Desktop console/logs for any error messages
- Verify tools are properly registered in the `registerTools()` method
## Development
This project uses:
- **TypeScript** for type safety and better development experience
- **Prettier** with 4-space indentation for consistent code formatting
- **ESM modules** for modern JavaScript compatibility
- **Object-oriented design** with the Strategy pattern for tool implementations
## License
MIT