diff --git a/mcp/.serena/memories/project_overview.md b/mcp/.serena/memories/project_overview.md index 528976b077..7e80a5e2d5 100644 --- a/mcp/.serena/memories/project_overview.md +++ b/mcp/.serena/memories/project_overview.md @@ -1,7 +1,10 @@ # Penpot MCP Project Overview - Updated ## Purpose -This project is a Model Context Protocol (MCP) server for Penpot integration. It provides a TypeScript-based server that can be used to extend Penpot's functionality through custom tools with bidirectional WebSocket communication. +This project is a Model Context Protocol (MCP) server for Penpot integration. +The MCP server communicates with a Penpot plugin via WebSockets, allowing +the MCP server to send tasks to the plugin and receive results, +enabling advanced AI-driven features in Penpot. ## Tech Stack - **Language**: TypeScript @@ -13,21 +16,22 @@ This project is a Model Context Protocol (MCP) server for Penpot integration. It ## Project Structure ``` -penpot-mcp/ -├── common/ # Shared type definitions +/ (project root) +├── packages/common/ # Shared type definitions │ ├── src/ │ │ ├── index.ts # Exports for shared types │ │ └── types.ts # PluginTaskResult, request/response interfaces │ └── package.json # @penpot-mcp/common package -├── mcp-server/ # Main MCP server implementation +├── packages/server/ # Main MCP server implementation │ ├── src/ │ │ ├── index.ts # Main server entry point │ │ ├── PenpotMcpServer.ts # Enhanced with request/response correlation │ │ ├── PluginTask.ts # Now supports result promises │ │ ├── tasks/ # PluginTask implementations │ │ └── tools/ # Tool implementations +| ├── data/ # Contains resources, such as API info and prompts │ └── package.json # Includes @penpot-mcp/common dependency -├── penpot-plugin/ # Penpot plugin with response capability +├── packages/plugin/ # Penpot plugin with response capability │ ├── src/ │ │ ├── main.ts # Enhanced WebSocket handling with response forwarding │ │ └── plugin.ts # Now sends task responses back to server @@ -37,55 +41,24 @@ penpot-mcp/ ## Key Tasks +### Adjusting the System Prompt + +The system prompt file is located in `packages/server/data/initial_instructions.md`. + ### Adding a new Tool -1. Implement the tool class in `mcp-server/src/tools/` following the `Tool` interface. +1. Implement the tool class in `packages/server/src/tools/` following the `Tool` interface. IMPORTANT: Do not catch any exceptions in the `executeCore` method. Let them propagate to be handled centrally. 2. Register the tool in `PenpotMcpServer`. -Look at `PrintTextTool` as an example. - -Many tools are linked to tasks that are handled in the plugin, i.e. they have an associated `PluginTask` implementation in `mcp-server/src/tasks/`. +Tools can be associated with a `PluginTask` that is executed in the plugin. +Many tools build on `ExecuteCodePluginTask`, as many operations can be reduced to code execution. ### Adding a new PluginTask -1. Implement the input data interface for the task in `common/src/types.ts`. -2. Implement the `PluginTask` class in `mcp-server/src/tasks/`. -3. Implement the corresponding task handler class in the plugin (`penpot-plugin/src/task-handlers/`). +1. Implement the input data interface for the task in `packages/common/src/types.ts`. +2. Implement the `PluginTask` class in `packages/server/src/tasks/`. +3. Implement the corresponding task handler class in the plugin (`packages/plugin/src/task-handlers/`). * In the success case, call `task.sendSuccess`. * In the failure case, just throw an exception, which will be handled centrally! - * Look at `PrintTextTaskHandler` as an example. -4. Register the task handler in `penpot-plugin/src/plugin.ts` in the `taskHandlers` list. - - -## Key Components - -### Enhanced WebSocket Protocol -- **Request Format**: `{id: string, task: string, params: any}` -- **Response Format**: `{id: string, result: {success: boolean, error?: string, data?: any}}` -- **Request/Response Correlation**: Using unique UUIDs for task tracking -- **Timeout Handling**: 30-second timeout with automatic cleanup -- **Type Safety**: Shared definitions via @penpot-mcp/common package - -### Core Classes -- **PenpotMcpServer**: Enhanced with pending task tracking and response handling -- **PluginTask**: Now creates result promises that resolve when plugin responds -- **Tool implementations**: Now properly await task completion and report results -- **Plugin handlers**: Send structured responses back to server - -### New Features -1. **Bidirectional Communication**: Plugin now responds with success/failure status -2. **Task Result Promises**: Every executePluginTask() sets and returns a promise -3. **Error Reporting**: Failed tasks properly report error messages to tools -4. **Shared Type Safety**: Common package ensures consistency across projects -5. **Timeout Protection**: Tasks don't hang indefinitely (30s limit) -6. **Request Correlation**: Unique IDs match requests to responses - -## Task Flow - -``` -LLM Tool Call → MCP Server → WebSocket (Request) → Plugin → Penpot API - ↑ ↓ - Tool Response ← MCP Server ← WebSocket (Response) ← Plugin Result -``` - +4. Register the task handler in `packages/plugin/src/plugin.ts` in the `taskHandlers` list. diff --git a/mcp/.serena/project.yml b/mcp/.serena/project.yml index c9ed0f7330..e869fbb9f4 100644 --- a/mcp/.serena/project.yml +++ b/mcp/.serena/project.yml @@ -19,7 +19,7 @@ read_only: false # list of tool names to exclude. We recommend not excluding any tools, see the readme for more details. # Below is the complete list of tools for convenience. -# To make sure you have the latest list of tools, and to view their descriptions, +# To make sure you have the latest list of tools, and to view their descriptions, # execute `uv run scripts/print_tool_overview.py`. # # * `activate_project`: Activates a project by name. @@ -62,16 +62,19 @@ excluded_tools: [] # (contrary to the memories, which are loaded on demand). initial_prompt: | IMPORTANT: You use an idiomatic, object-oriented style. - In particular, this implies that, for any non-trivial interfaces, you use interfaces that expect explicitly typed abstractions + In particular, this implies that, for any non-trivial interfaces, you use interfaces that expect explicitly typed abstractions rather than mere functions (i.e. use the strategy pattern, for example). - Comments: + Always read the "project_overview" memory. + + Comments: When describing parameters, methods/functions and classes, you use a precise style, where the initial (elliptical) phrase clearly defines *what* it is. Any details then follow in subsequent sentences. When describing what blocks of code do, you also use an elliptical style and start with a lower-case letter unless - the comment is a lengthy explanation with at least two sentences (in which case you start with a capital letter, as is + the comment is a lengthy explanation with at least two sentences (in which case you start with a capital letter, as is required for sentences). + # the name by which the project can be referenced within Serena project_name: "penpot-mcp"