From 966a39eb5cf7cb0a47e6269e47bbba18f3c5fe97 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Thu, 11 Sep 2025 12:00:44 +0200 Subject: [PATCH] Update README --- mcp-server/.prettierignore | 1 + mcp-server/README.md | 188 +++++++++---------------------------- 2 files changed, 46 insertions(+), 143 deletions(-) create mode 100644 mcp-server/.prettierignore diff --git a/mcp-server/.prettierignore b/mcp-server/.prettierignore new file mode 100644 index 0000000..dd44972 --- /dev/null +++ b/mcp-server/.prettierignore @@ -0,0 +1 @@ +*.md diff --git a/mcp-server/README.md b/mcp-server/README.md index f6baf6d..ac44821 100644 --- a/mcp-server/README.md +++ b/mcp-server/README.md @@ -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 `: 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