diff --git a/.serena/memories/code_style_conventions.md b/.serena/memories/code_style_conventions.md index ff271b0..917e47c 100644 --- a/.serena/memories/code_style_conventions.md +++ b/.serena/memories/code_style_conventions.md @@ -1,7 +1,7 @@ # Code Style and Conventions ## General Principles -- **Object-Oriented Design**: Use idiomatic, object-oriented style with explicit abstractions +- **Object-Oriented Design**: VERY IMPORTANT: Use idiomatic, object-oriented style with explicit abstractions - **Strategy Pattern**: Prefer explicitly typed interfaces over bare functions for non-trivial functionality - **Clean Architecture**: Tools implement a common interface for consistent registration and execution @@ -20,39 +20,6 @@ ## Documentation Style - **JSDoc**: Use comprehensive JSDoc comments for classes, methods, and interfaces -- **Description Format**: Initial elliptical phrase defines *what* it is, followed by details -- **Comment Style**: Start with lowercase for comments of code blocks (unless lengthy explanation with multiple sentences) +- **Description Format**: Initial elliptical phrase that defines *what* it is, followed by details +- **Comment Style**: VERY IMPORTANT: Start with lowercase for comments of code blocks (unless lengthy explanation with multiple sentences) -## Code Organization -- **Separation of Concerns**: Interfaces in separate directory from implementations -- **Tool Pattern**: All tools implement the `Tool` interface with `definition` and `execute` methods -- **Error Handling**: Comprehensive error handling with descriptive messages -- **Import Style**: Use explicit .js extensions for imports (required for ES modules) - -## Examples -```typescript -/** - * A simple demonstration tool that returns a greeting message. - * - * This tool serves as a basic example of the Tool interface implementation - * and provides a minimal "Hello, World!" functionality for testing purposes. - */ -export class HelloWorldTool implements Tool { - /** - * The tool definition as required by the MCP protocol. - */ - readonly definition: MCPTool = { - // configuration - }; - - /** - * Executes the hello world functionality. - * - * @param args - Tool arguments validated against schema - * @returns A promise resolving to the execution result - */ - async execute(args: unknown): Promise { - // implementation - } -} -``` diff --git a/.serena/memories/project_overview.md b/.serena/memories/project_overview.md index 86dacdd..f786cce 100644 --- a/.serena/memories/project_overview.md +++ b/.serena/memories/project_overview.md @@ -14,7 +14,7 @@ This project is a Model Context Protocol (MCP) server for Penpot integration. It ## Project Structure ``` penpot-mcp/ -├── common/ # NEW: Shared type definitions +├── common/ # Shared type definitions │ ├── src/ │ │ ├── index.ts # Exports for shared types │ │ └── types.ts # PluginTaskResult, request/response interfaces @@ -24,20 +24,40 @@ penpot-mcp/ │ │ ├── index.ts # Main server entry point │ │ ├── PenpotMcpServer.ts # Enhanced with request/response correlation │ │ ├── PluginTask.ts # Now supports result promises -│ │ ├── tasks/ # Task implementations -│ │ │ └── PrintTextPluginTask.ts # Uses shared types +│ │ ├── tasks/ # PluginTask implementations │ │ └── tools/ # Tool implementations -│ │ ├── HelloWorldTool.ts -│ │ └── PrintTextTool.ts # Now waits for task completion │ └── package.json # Includes @penpot-mcp/common dependency -└── penpot-plugin/ # Penpot plugin with response capability - ├── src/ - │ ├── main.ts # Enhanced WebSocket handling with response forwarding - │ └── plugin.ts # Now sends task responses back to server - └── package.json # Includes @penpot-mcp/common dependency +├── penpot-plugin/ # Penpot plugin with response capability +│ ├── src/ +│ │ ├── main.ts # Enhanced WebSocket handling with response forwarding +│ │ └── plugin.ts # Now sends task responses back to server +│ └── package.json # Includes @penpot-mcp/common dependency +└── prepare-api-docs # Python project for the generation of API docs ``` -## Key Components - Updated +## Key Tasks + +### Adding a new Tool + +* Implement the tool class in `mcp-server/src/tools/` following the `Tool` interface. +* IMPORTANT: Do not catch any exceptions in the `executeCore` method. Let them propagate to be handled centrally. + +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/`. + +### 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/`). + * 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}` @@ -60,11 +80,11 @@ penpot-mcp/ 5. **Timeout Protection**: Tasks don't hang indefinitely (30s limit) 6. **Request Correlation**: Unique IDs match requests to responses -## Protocol Flow +## Task Flow + ``` LLM Tool Call → MCP Server → WebSocket (Request) → Plugin → Penpot API ↑ ↓ Tool Response ← MCP Server ← WebSocket (Response) ← Plugin Result ``` -All components now properly handle the full request/response lifecycle with comprehensive error handling and type safety. diff --git a/.serena/memories/task_completion_guidelines.md b/.serena/memories/task_completion_guidelines.md index 32d6c34..678fd83 100644 --- a/.serena/memories/task_completion_guidelines.md +++ b/.serena/memories/task_completion_guidelines.md @@ -40,7 +40,6 @@ npm run dev ## File Organization - Place new tools in `src/tools/` directory -- Add interfaces to `src/interfaces/` if needed - Update main server registration in `src/index.ts` - Follow existing naming conventions diff --git a/.serena/project.yml b/.serena/project.yml index 71a0f91..58f7348 100644 --- a/.serena/project.yml +++ b/.serena/project.yml @@ -73,7 +73,7 @@ initial_prompt: | 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 to 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).