diff --git a/.env b/.env new file mode 100644 index 0000000..7e6ad2c --- /dev/null +++ b/.env @@ -0,0 +1,10 @@ +# βœ… Penpot Login-Daten (von deinem Penpot-Server) +PENPOT_USERNAME=dein_benutzername +PENPOT_PASSWORD=dein_passwort + +# βœ… Server-Konfiguration fΓΌr den MCP Server +PORT=5000 +DEBUG=true + +# βœ… API URL deiner lokalen Penpot-Instanz +PENPOT_API_URL=http://192.168.10.102:9010/api diff --git a/.gitignore b/.gitignore index 4fcac19..52ef0d9 100644 --- a/.gitignore +++ b/.gitignore @@ -30,7 +30,7 @@ env/ .python-version # Environment variables -.env +#.env # IDE files .idea/ diff --git a/README.md b/README.md index 8ec6901..41c0e66 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ # Penpot MCP Server πŸŽ¨πŸ€– +

Penpot MCP Logo

@@ -32,11 +33,11 @@ ### 🎯 Key Benefits -- **πŸ€– AI-Native Design Analysis**: Let Claude AI analyze your UI/UX designs, provide feedback, and suggest improvements -- **⚑ Automated Design Workflows**: Streamline repetitive design tasks with AI-powered automation -- **πŸ” Intelligent Design Search**: Find design components and patterns across your projects using natural language -- **πŸ“Š Design System Management**: Automatically document and maintain design systems with AI assistance -- **🎨 Cross-Platform Integration**: Works with any MCP-compatible AI assistant (Claude Desktop, Cursor IDE, etc.) +- **πŸ€– AI-Native Design Analysis**: Let Claude AI analyze your UI/UX designs, provide feedback, and suggest improvements +- **⚑ Automated Design Workflows**: Streamline repetitive design tasks with AI-powered automation +- **πŸ” Intelligent Design Search**: Find design components and patterns across your projects using natural language +- **πŸ“Š Design System Management**: Automatically document and maintain design systems with AI assistance +- **🎨 Cross-Platform Integration**: Works with any MCP-compatible AI assistant (Claude Desktop, Cursor IDE, etc.) ## πŸŽ₯ Demo Video @@ -47,59 +48,65 @@ Check out our demo video to see Penpot MCP in action: ## ✨ Features ### πŸ”Œ Core Capabilities -- **MCP Protocol Implementation**: Full compliance with Model Context Protocol standards -- **Real-time Design Access**: Direct integration with Penpot's API for live design data -- **Component Analysis**: AI-powered analysis of design components and layouts -- **Export Automation**: Programmatic export of design assets in multiple formats -- **Design Validation**: Automated design system compliance checking + +- **MCP Protocol Implementation**: Full compliance with Model Context Protocol standards +- **Real-time Design Access**: Direct integration with Penpot's API for live design data +- **Component Analysis**: AI-powered analysis of design components and layouts +- **Export Automation**: Programmatic export of design assets in multiple formats +- **Design Validation**: Automated design system compliance checking ### πŸ› οΈ Developer Tools -- **Command-line Utilities**: Powerful CLI tools for design file analysis and validation -- **Python SDK**: Comprehensive Python library for custom integrations -- **REST API**: HTTP endpoints for web application integration -- **Extensible Architecture**: Plugin system for custom AI workflows + +- **Command-line Utilities**: Powerful CLI tools for design file analysis and validation +- **Python SDK**: Comprehensive Python library for custom integrations +- **REST API**: HTTP endpoints for web application integration +- **Extensible Architecture**: Plugin system for custom AI workflows ### 🎨 AI Integration Features -- **Claude Desktop & Cursor Integration**: Native support for Claude AI assistant in both Claude Desktop and Cursor IDE -- **Design Context Sharing**: Provide design context to AI models for better responses -- **Visual Component Recognition**: AI can "see" and understand design components -- **Natural Language Queries**: Ask questions about your designs in plain English -- **IDE Integration**: Seamless integration with modern development environments + +- **Claude Desktop & Cursor Integration**: Native support for Claude AI assistant in both Claude Desktop and Cursor IDE +- **Design Context Sharing**: Provide design context to AI models for better responses +- **Visual Component Recognition**: AI can "see" and understand design components +- **Natural Language Queries**: Ask questions about your designs in plain English +- **IDE Integration**: Seamless integration with modern development environments ## πŸ’‘ Use Cases ### For Designers -- **Design Review Automation**: Get instant AI feedback on accessibility, usability, and design principles -- **Component Documentation**: Automatically generate documentation for design systems -- **Design Consistency Checks**: Ensure brand guidelines compliance across projects -- **Asset Organization**: AI-powered tagging and categorization of design components + +- **Design Review Automation**: Get instant AI feedback on accessibility, usability, and design principles +- **Component Documentation**: Automatically generate documentation for design systems +- **Design Consistency Checks**: Ensure brand guidelines compliance across projects +- **Asset Organization**: AI-powered tagging and categorization of design components ### For Developers -- **Design-to-Code Workflows**: Bridge the gap between design and development with AI assistance -- **API Integration**: Programmatic access to design data for custom tools and workflows -- **Automated Testing**: Generate visual regression tests from design specifications -- **Design System Sync**: Keep design tokens and code components in sync + +- **Design-to-Code Workflows**: Bridge the gap between design and development with AI assistance +- **API Integration**: Programmatic access to design data for custom tools and workflows +- **Automated Testing**: Generate visual regression tests from design specifications +- **Design System Sync**: Keep design tokens and code components in sync ### For Product Teams -- **Design Analytics**: Track design system adoption and component usage -- **Collaboration Enhancement**: AI-powered design reviews and feedback collection -- **Workflow Optimization**: Automate repetitive design operations and approvals -- **Cross-tool Integration**: Connect Penpot with other tools in your design workflow + +- **Design Analytics**: Track design system adoption and component usage +- **Collaboration Enhancement**: AI-powered design reviews and feedback collection +- **Workflow Optimization**: Automate repetitive design operations and approvals +- **Cross-tool Integration**: Connect Penpot with other tools in your design workflow ## πŸš€ Quick Start ### Prerequisites -- **Python 3.12+** (Latest Python recommended for optimal performance) -- **Penpot Account** ([Sign up free](https://penpot.app/)) -- **Claude Desktop or Cursor IDE** (Optional, for AI integration) +- **Python 3.12+** (Latest Python recommended for optimal performance) +- **Penpot Account** ([Sign up free](https://penpot.app/)) +- **Claude Desktop or Cursor IDE** (Optional, for AI integration) ## Installation ### Prerequisites -- Python 3.12+ -- Penpot account credentials +- Python 3.12+ +- Penpot account credentials ### Installation @@ -152,6 +159,7 @@ DEBUG=true ``` > **⚠️ CloudFlare Protection Notice**: The Penpot cloud site (penpot.app) uses CloudFlare protection that may occasionally block API requests. If you encounter authentication errors or blocked requests: +> > 1. Open your web browser and navigate to [https://design.penpot.app](https://design.penpot.app) > 2. Log in to your Penpot account > 3. Complete any CloudFlare human verification challenges if prompted @@ -246,19 +254,21 @@ penpot-client ## MCP Resources & Tools ### Resources -- `server://info` - Server status and information -- `penpot://schema` - Penpot API schema as JSON -- `penpot://tree-schema` - Penpot object tree schema as JSON -- `rendered-component://{component_id}` - Rendered component images -- `penpot://cached-files` - List of cached Penpot files + +- `server://info` - Server status and information +- `penpot://schema` - Penpot API schema as JSON +- `penpot://tree-schema` - Penpot object tree schema as JSON +- `rendered-component://{component_id}` - Rendered component images +- `penpot://cached-files` - List of cached Penpot files ### Tools -- `list_projects` - List all Penpot projects -- `get_project_files` - Get files for a specific project -- `get_file` - Retrieve a Penpot file by its ID and cache it -- `export_object` - Export a Penpot object as an image -- `get_object_tree` - Get the object tree structure for a Penpot object -- `search_object` - Search for objects within a Penpot file by name + +- `list_projects` - List all Penpot projects +- `get_project_files` - Get files for a specific project +- `get_file` - Retrieve a Penpot file by its ID and cache it +- `export_object` - Export a Penpot object as an image +- `get_object_tree` - Get the object tree structure for a Penpot object +- `search_object` - Search for objects within a Penpot file by name ## AI Integration @@ -272,17 +282,17 @@ Add the following configuration to your Claude Desktop config file (`~/Library/A ```json { - "mcpServers": { - "penpot": { - "command": "uvx", - "args": ["penpot-mcp"], - "env": { - "PENPOT_API_URL": "https://design.penpot.app/api", - "PENPOT_USERNAME": "your_penpot_username", - "PENPOT_PASSWORD": "your_penpot_password" - } + "mcpServers": { + "penpot": { + "command": "uvx", + "args": ["penpot-mcp"], + "env": { + "PENPOT_API_URL": "https://design.penpot.app/api", + "PENPOT_USERNAME": "your_penpot_username", + "PENPOT_PASSWORD": "your_penpot_password" + } + } } - } } ``` @@ -291,56 +301,60 @@ Add the following configuration to your Claude Desktop config file (`~/Library/A Cursor IDE supports MCP servers through its AI integration features. To configure Penpot MCP with Cursor: 1. **Install the MCP server** (if not already installed): - ```bash - pip install penpot-mcp - ``` + + ```bash + pip install penpot-mcp + ``` 2. **Configure Cursor settings** by adding the MCP server to your Cursor configuration. Open Cursor settings and add: - ```json - { - "mcpServers": { - "penpot": { - "command": "uvx", - "args": ["penpot-mcp"], - "env": { - "PENPOT_API_URL": "https://design.penpot.app/api", - "PENPOT_USERNAME": "your_penpot_username", - "PENPOT_PASSWORD": "your_penpot_password" - } - } - } - } - ``` + ```json + { + "mcpServers": { + "penpot": { + "command": "uvx", + "args": ["penpot-mcp"], + "env": { + "PENPOT_API_URL": "https://design.penpot.app/api", + "PENPOT_USERNAME": "your_penpot_username", + "PENPOT_PASSWORD": "your_penpot_password" + } + } + } + } + ``` 3. **Alternative: Use environment variables** by creating a `.env` file in your project root: - ```bash - PENPOT_API_URL=https://design.penpot.app/api - PENPOT_USERNAME=your_penpot_username - PENPOT_PASSWORD=your_penpot_password - ``` + + ```bash + PENPOT_API_URL=https://design.penpot.app/api + PENPOT_USERNAME=your_penpot_username + PENPOT_PASSWORD=your_penpot_password + ``` 4. **Start the MCP server** in your project: - ```bash - # In your project directory - penpot-mcp - ``` + + ```bash + # In your project directory + penpot-mcp + ``` 5. **Use in Cursor**: Once configured, you can interact with your Penpot designs directly in Cursor by asking questions like: - - "Show me all projects in my Penpot account" - - "Analyze the design components in project X" - - "Export the main button component as an image" - - "What design patterns are used in this file?" + - "Show me all projects in my Penpot account" + - "Analyze the design components in project X" + - "Export the main button component as an image" + - "What design patterns are used in this file?" ### Key Integration Features Both Claude Desktop and Cursor integration provide: -- **Direct access** to Penpot projects and files -- **Visual component analysis** with AI-powered insights -- **Design export capabilities** for assets and components -- **Natural language queries** about your design files -- **Real-time design feedback** and suggestions -- **Design system documentation** generation + +- **Direct access** to Penpot projects and files +- **Visual component analysis** with AI-powered insights +- **Design export capabilities** for assets and components +- **Natural language queries** about your design files +- **Real-time design feedback** and suggestions +- **Design system documentation** generation ## Package Structure @@ -417,5 +431,5 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file ## Acknowledgments -- [Penpot](https://penpot.app/) - The open-source design and prototyping platform -- [Model Context Protocol](https://modelcontextprotocol.io) - The standardized protocol for AI model context +- [Penpot](https://penpot.app/) - The open-source design and prototyping platform +- [Model Context Protocol](https://modelcontextprotocol.io) - The standardized protocol for AI model context