Files

chema 0d4d34904c Add CLAUDE.md for project guidance and enhance get_object_subtree_with_fields to handle circular references

- Introduced CLAUDE.md to provide comprehensive guidance on the Penpot MCP Server, including project overview, key commands, architecture, and common workflows.
- Enhanced the `get_object_subtree_with_fields` function to track visited nodes and handle circular references, ensuring robust tree structure retrieval.
- Added tests for circular reference handling in `test_penpot_tree.py` to validate new functionality.

2025-06-29 17:21:17 +02:00

3.5 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Penpot MCP Server is a Python-based Model Context Protocol (MCP) server that bridges AI language models with Penpot, an open-source design platform. It enables programmatic interaction with design files through a well-structured API.

Key Commands

Development Setup

# Install dependencies (recommended)
uv sync --extra dev

# Run the MCP server
uv run penpot-mcp

# Run tests
uv run pytest
uv run pytest --cov=penpot_mcp tests/  # with coverage

# Lint and fix code
uv run python lint.py              # check issues
uv run python lint.py --autofix    # auto-fix issues

Running the Server

# Default stdio mode (for Claude Desktop/Cursor)
make mcp-server

# SSE mode (for debugging with inspector)
make mcp-server-sse

# Launch MCP inspector (requires SSE mode)
make mcp-inspector

CLI Tools

# Generate tree visualization
penpot-tree path/to/penpot_file.json

# Validate Penpot file
penpot-validate path/to/penpot_file.json

Architecture Overview

Core Components

MCP Server (penpot_mcp/server/mcp_server.py)
- Built on FastMCP framework
- Implements resources and tools for Penpot interaction
- Memory cache with 10-minute TTL
- Supports stdio (default) and SSE modes
API Client (penpot_mcp/api/penpot_api.py)
- REST client for Penpot platform
- Transit+JSON format handling
- Cookie-based authentication with auto-refresh
- Lazy authentication pattern
Key Design Patterns
- Authentication: Cookie-based with automatic re-authentication on 401/403
- Caching: In-memory file cache to reduce API calls
- Resource/Tool Duality: Resources can be exposed as tools via RESOURCES_AS_TOOLS config
- Transit Format: Special handling for UUIDs (~u prefix) and keywords (~: prefix)

Available Tools/Functions

list_projects: Get all Penpot projects
get_project_files: List files in a project
get_file: Retrieve and cache file data
search_object: Search design objects by name (regex)
get_object_tree: Get filtered object tree with screenshot
export_object: Export design objects as images
penpot_tree_schema: Get schema for object tree fields

Environment Configuration

Create a .env file with:

PENPOT_API_URL=https://design.penpot.app/api
PENPOT_USERNAME=your_username
PENPOT_PASSWORD=your_password
ENABLE_HTTP_SERVER=true  # for image serving
RESOURCES_AS_TOOLS=false # MCP resource mode
DEBUG=true               # debug logging

Working with the Codebase

Adding New Tools: Decorate functions with @self.mcp.tool() in mcp_server.py
API Extensions: Add methods to PenpotAPI class following existing patterns
Error Handling: Always check for "error" keys in API responses
Testing: Use test_mode=True when creating server instances in tests
Transit Format: Remember to handle Transit+JSON when working with raw API

Common Workflow for Code Generation

List projects → Find target project
Get project files → Locate design file
Search for component → Find specific element
Get tree schema → Understand available fields
Get object tree → Retrieve structure with screenshot
Export if needed → Get rendered component image

Testing Patterns

Mock fixtures in tests/conftest.py
Test both stdio and SSE modes
Verify Transit format conversions
Check cache behavior and expiration

3.5 KiB Raw Blame History