Penpot MCP 는 AI 언어 모델과 오픈소스 디자인 및 프로토타입 플랫폼 인 Penpot 간의 간극을 메우는 혁신적인 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이러한 통합을 통해 Claude(Claude Desktop 및 Cursor IDE 모두)와 같은 AI 비서가 디자인 파일을 프로그래밍 방식으로 이해하고 분석하며 상호 작용할 수 있습니다.
🤖 AI 기반 디자인 분석 : Claude AI가 UI/UX 디자인을 분석하고 피드백을 제공하며 개선 사항을 제안합니다.
⚡ 자동화된 디자인 워크플로 : AI 기반 자동화로 반복적인 디자인 작업을 간소화하세요
🔍 지능형 디자인 검색 : 자연어를 사용하여 프로젝트 전반의 디자인 구성 요소와 패턴을 찾으세요
📊 디자인 시스템 관리 : AI 지원을 통해 디자인 시스템을 자동으로 문서화하고 유지 관리합니다.
🎨 크로스 플랫폼 통합 : 모든 MCP 호환 AI 어시스턴트(Claude Desktop, Cursor IDE 등)와 호환됩니다.
Related MCP server: AI-Canvas MCP Server
Penpot MCP가 실제로 작동하는 모습을 보려면 데모 영상을 확인하세요.
MCP 프로토콜 구현 : 모델 컨텍스트 프로토콜 표준을 완벽하게 준수합니다.
실시간 디자인 액세스 : 라이브 디자인 데이터를 위한 Penpot API와 직접 통합
구성 요소 분석 : AI 기반 디자인 구성 요소 및 레이아웃 분석
내보내기 자동화 : 다양한 형식으로 디자인 자산을 프로그래밍 방식으로 내보내기
설계 검증 : 자동화된 설계 시스템 준수 검사
명령줄 유틸리티 : 설계 파일 분석 및 검증을 위한 강력한 CLI 도구
Python SDK : 사용자 정의 통합을 위한 포괄적인 Python 라이브러리
REST API : 웹 애플리케이션 통합을 위한 HTTP 엔드포인트
확장 가능한 아키텍처 : 맞춤형 AI 워크플로를 위한 플러그인 시스템
Claude Desktop 및 Cursor 통합 : Claude Desktop 및 Cursor IDE 모두에서 Claude AI 어시스턴트에 대한 기본 지원
디자인 컨텍스트 공유 : 더 나은 응답을 위해 AI 모델에 디자인 컨텍스트 제공
시각적 구성 요소 인식 : AI는 디자인 구성 요소를 "보고" 이해할 수 있습니다.
자연어 질의 : 쉬운 영어로 디자인에 대한 질문을 해보세요
IDE 통합 : 최신 개발 환경과의 원활한 통합
디자인 검토 자동화 : 접근성, 사용성 및 디자인 원칙에 대한 즉각적인 AI 피드백을 받으세요
구성 요소 문서화 : 디자인 시스템에 대한 문서를 자동으로 생성합니다.
디자인 일관성 검사 : 프로젝트 전반에 걸쳐 브랜드 가이드라인 준수 보장
자산 구성 : AI 기반 태그 지정 및 디자인 구성 요소 분류
디자인-코드 워크플로 : AI 지원을 통해 디자인과 개발 간의 격차 해소
API 통합 : 사용자 정의 도구 및 워크플로를 위한 디자인 데이터에 대한 프로그래밍 방식 액세스
자동화된 테스트 : 설계 사양에서 시각적 회귀 테스트 생성
디자인 시스템 동기화 : 디자인 토큰과 코드 구성 요소를 동기화 상태로 유지
디자인 분석 : 디자인 시스템 도입 및 구성 요소 사용 추적
협업 강화 : AI 기반 디자인 검토 및 피드백 수집
워크플로 최적화 : 반복적인 설계 작업 및 승인 자동화
도구 간 통합 : 디자인 워크플로에서 Penpot을 다른 도구와 연결하세요
Python 3.12+ (최적의 성능을 위해 최신 Python 권장)
펜팟 계정 ( 무료 가입 )
Claude Desktop 또는 Cursor IDE (선택 사항, AI 통합용)
파이썬 3.12+
Penpot 계정 자격 증명
지엑스피1
# Install directly with uvx (when published to PyPI)
uvx penpot-mcp
# For local development, use uvx with local path
uvx --from . penpot-mcp
# Or install in a project with uv
uv add penpot-mcp# Clone the repository
git clone https://github.com/montevive/penpot-mcp.git
cd penpot-mcp
# Using uv (recommended)
uv sync
uv run penpot-mcp
# Or using traditional pip
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -e .Penpot 자격 증명을 사용하여 env.example 기반으로 .env 파일을 만듭니다.
PENPOT_API_URL=https://design.penpot.app/api
PENPOT_USERNAME=your_penpot_username
PENPOT_PASSWORD=your_penpot_password
PORT=5000
DEBUG=true# Using uvx (when published to PyPI)
uvx penpot-mcp
# Using uvx for local development
uvx --from . penpot-mcp
# Using uv in a project (recommended for local development)
uv run penpot-mcp
# Using the entry point (if installed)
penpot-mcp
# Or using the module directly
python -m penpot_mcp.server.mcp_serverMCP 서버를 디버깅하려면 다음을 수행할 수 있습니다.
DEBUG=true 설정하여 .env 파일에서 디버그 모드를 활성화합니다.
API 작업을 테스트하려면 Penpot API CLI를 사용하세요.
# Test API connection with debug output
python -m penpot_mcp.api.penpot_api --debug list-projects
# Get details for a specific project
python -m penpot_mcp.api.penpot_api --debug get-project --id YOUR_PROJECT_ID
# List files in a project
python -m penpot_mcp.api.penpot_api --debug list-files --project-id YOUR_PROJECT_ID
# Get file details
python -m penpot_mcp.api.penpot_api --debug get-file --file-id YOUR_FILE_ID패키지에는 유틸리티 명령줄 도구가 포함되어 있습니다.
# Generate a tree visualization of a Penpot file
penpot-tree path/to/penpot_file.json
# Validate a Penpot file against the schema
penpot-validate path/to/penpot_file.json# Start your MCP server in one terminal
python -m penpot_mcp.server.mcp_server
# In another terminal, use mcp-cli to monitor and interact with your server
python -m mcp.cli monitor python -m penpot_mcp.server.mcp_server
# Or connect to an already running server on a specific port
python -m mcp.cli monitor --port 5000# Start your MCP server in one terminal
python -m penpot_mcp.server.mcp_server
# In another terminal, run the MCP Inspector (requires Node.js)
npx @modelcontextprotocol/inspector# Run the example client
penpot-clientserver://info - 서버 상태 및 정보
penpot://schema - JSON 형태의 Penpot API 스키마
penpot://tree-schema - JSON 형태의 Penpot 객체 트리 스키마
rendered-component://{component_id} - 렌더링된 구성 요소 이미지
penpot://cached-files - 캐시된 Penpot 파일 목록
list_projects - 모든 Penpot 프로젝트 나열
get_project_files - 특정 프로젝트에 대한 파일 가져오기
get_file - ID로 Penpot 파일을 검색하고 캐시합니다.
export_object - Penpot 객체를 이미지로 내보내기
get_object_tree - Penpot 객체의 객체 트리 구조를 가져옵니다.
search_object - Penpot 파일 내에서 이름으로 객체 검색
Penpot MCP 서버는 모델 컨텍스트 프로토콜(Model Context Protocol)을 사용하여 AI 어시스턴트와 통합될 수 있습니다. Claude Desktop과 Cursor IDE를 모두 지원하여 원활한 디자인 워크플로 자동화를 구현합니다.
Claude Desktop 설정에 대한 자세한 지침은 CLAUDE_INTEGRATION.md를 참조하세요.
Claude Desktop 구성 파일에 다음 구성을 추가합니다(macOS에서는 ~/Library/Application Support/Claude/claude_desktop_config.json , Windows에서는 %APPDATA%\Claude\claude_desktop_config.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"
}
}
}
}Cursor IDE는 AI 통합 기능을 통해 MCP 서버를 지원합니다. Penpot MCP를 Cursor와 함께 구성하려면 다음 단계를 따르세요.
MCP 서버를 설치합니다 (아직 설치되지 않은 경우):
pip install penpot-mcp커서 구성에 MCP 서버를 추가하여 커서 설정을 구성하세요 . 커서 설정을 열고 다음을 추가하세요.
{
"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"
}
}
}
}대안: 프로젝트 루트에 .env 파일을 만들어 환경 변수를 사용하세요 .
PENPOT_API_URL=https://design.penpot.app/api
PENPOT_USERNAME=your_penpot_username
PENPOT_PASSWORD=your_penpot_password프로젝트에서 MCP 서버를 시작합니다 .
# In your project directory
penpot-mcp커서에서 사용 : 구성이 완료되면 다음과 같은 질문을 통해 커서에서 Penpot 디자인과 직접 상호 작용할 수 있습니다.
"내 Penpot 계정의 모든 프로젝트를 보여주세요"
"프로젝트 X의 디자인 구성 요소를 분석하세요"
"메인 버튼 구성 요소를 이미지로 내보내기"
"이 파일에서는 어떤 디자인 패턴이 사용되었나요?"
Claude Desktop과 Cursor 통합은 다음을 제공합니다.
Penpot 프로젝트 및 파일에 직접 액세스
AI 기반 통찰력을 통한 시각적 구성 요소 분석
자산 및 구성 요소에 대한 설계 내보내기 기능
디자인 파일에 대한 자연어 쿼리
실시간 디자인 피드백 및 제안
디자인 시스템 문서 생성
penpot_mcp/
├── api/ # Penpot API client
├── server/ # MCP server implementation
│ ├── mcp_server.py # Main MCP server
│ └── client.py # Client implementation
├── tools/ # Utility tools
│ ├── cli/ # Command-line interfaces
│ └── penpot_tree.py # Penpot object tree visualization
├── resources/ # Resource files and schemas
└── utils/ # Helper utilities이 프로젝트에서는 테스트를 위해 pytest를 사용합니다.
# Using uv (recommended)
uv sync --extra dev
uv run pytest
# Run with coverage
uv run pytest --cov=penpot_mcp tests/
# Using traditional pip
pip install -e ".[dev]"
pytest
pytest --cov=penpot_mcp tests/# Using uv (recommended)
uv sync --extra dev
# Set up pre-commit hooks
uv run pre-commit install
# Run linting
uv run python lint.py
# Auto-fix linting issues
uv run python lint.py --autofix
# Using traditional pip
pip install -r requirements-dev.txt
pre-commit install
./lint.py
./lint.py --autofix기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.
저장소를 포크하세요
기능 브랜치를 생성합니다( git checkout -b feature/amazing-feature )
변경 사항을 커밋하세요( git commit -m 'Add some amazing feature' )
브랜치에 푸시( git push origin feature/amazing-feature )
풀 리퀘스트 열기
귀하의 코드가 프로젝트의 코딩 표준을 따르고 적절한 테스트를 포함하고 있는지 확인하세요.
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.
Penpot - 오픈소스 디자인 및 프로토타입 제작 플랫폼
모델 컨텍스트 프로토콜 - AI 모델 컨텍스트를 위한 표준화된 프로토콜
Export a Penpot design object as an image.
Args:
file_id: The ID of the Penpot file
page_id: The ID of the page containing the object
object_id: The ID of the object to export
export_type: Image format (png, svg, etc.)
scale: Scale factor for the exported image
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | ||
| page_id | Yes | ||
| object_id | Yes | ||
| export_type | No | png | |
| scale | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Export') but lacks details on permissions needed, whether it's a read-only or write operation, rate limits, or what the output entails (e.g., file download link, binary data). This is inadequate for a tool with potential side effects like file generation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with the core purpose in the first sentence. The parameter explanations are listed efficiently in bullet-point style under 'Args:', though some could be more concise (e.g., 'etc.' in export_type is vague). Overall, it avoids unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, 0% schema description coverage, and no output schema, the description is incomplete. It covers the basic action and parameters but misses critical behavioral context (e.g., output format, side effects) and usage guidelines relative to siblings. For a 5-parameter tool with potential file operations, this leaves significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It lists all 5 parameters with brief explanations (e.g., 'Image format (png, svg, etc.)' for export_type), adding basic semantics beyond the schema's titles. However, it doesn't provide deeper context like valid export_type values beyond examples or scale constraints, leaving gaps in understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Export') and resource ('a Penpot design object as an image'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from sibling tools like 'get_rendered_component' or 'search_object', which might also involve object retrieval or rendering, so it falls short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'get_rendered_component' and 'search_object' available, there's no indication of scenarios where 'export_object' is preferred, such as for image file generation versus in-app viewing, leaving the agent to guess based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all files currently stored in the cache.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool lists files from the cache, implying a read-only operation, but does not specify details like whether the list is paginated, sorted, filtered, or includes metadata. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that directly states the tool's function without unnecessary words. It is front-loaded and efficiently conveys the core purpose, making it easy to understand at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description adequately covers the basic purpose. However, it lacks details on behavioral aspects (e.g., output format, caching specifics) and usage guidelines, which are important for an agent to invoke it correctly. The simplicity of the tool means the description is minimally viable but could be more informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the schema description coverage is 100%, so there are no parameters to document. The description does not need to add parameter semantics, but it correctly implies no inputs are required. A baseline score of 4 is appropriate as it aligns with the lack of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('files currently stored in the cache'), making the purpose unambiguous. However, it does not explicitly differentiate from sibling tools like 'get_file' or 'get_project_files', which might also retrieve files but from different sources or with different scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as 'get_file' (which might retrieve a specific file) or 'get_project_files' (which might list files in a project context). There is no mention of prerequisites, exclusions, or recommended contexts for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a Penpot file by its ID and cache it. Don't use this tool for code generation, use 'get_object_tree' instead.
Args:
file_id: The ID of the Penpot file
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals two important behavioral traits: 1) the tool caches the retrieved file, and 2) it's specifically not intended for code generation purposes. However, it doesn't mention potential side effects, error conditions, or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with two main sentences and a parameter section. The first sentence states the purpose, the second provides usage guidance, and the Args section documents the parameter. There's minimal waste, though the formatting could be cleaner.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and 0% schema description coverage, the description provides adequate basics (purpose, usage guidance, parameter meaning) but lacks details about return values, error handling, caching behavior specifics, or authentication requirements that would be helpful for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate for the lack of parameter documentation. It provides the parameter name 'file_id' and clarifies it's 'The ID of the Penpot file', which adds meaningful context beyond the bare schema. However, it doesn't specify format requirements or validation rules.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Retrieve a Penpot file by its ID') and resource ('Penpot file'), and distinguishes it from sibling tools by explicitly naming 'get_object_tree' as an alternative for code generation. This provides excellent differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when NOT to use this tool ('Don't use this tool for code generation') and names a specific alternative ('use get_object_tree instead'). This gives clear context for tool selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the object tree structure for a Penpot object ("tree" field) with rendered screenshot image of the object ("image.mcp_uri" field). Args: file_id: The ID of the Penpot file object_id: The ID of the object to retrieve fields: Specific fields to include in the tree (call "penpot_tree_schema" resource/tool for available fields) depth: How deep to traverse the object tree (-1 for full depth) format: Output format ('json' or 'yaml')
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | ||
| object_id | Yes | ||
| fields | Yes | ||
| depth | No | ||
| format | No | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It describes what the tool returns (tree structure and screenshot) but lacks behavioral details such as whether this is a read-only operation, potential rate limits, authentication needs, error handling, or how the screenshot is generated (e.g., rendering time, size). For a tool with 5 parameters and no annotations, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with the core purpose followed by parameter details in a structured list. Every sentence adds value, such as explaining parameter purposes and referencing other tools. Minor improvements could include briefer phrasing, but overall it's efficient and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no annotations, and no output schema, the description is moderately complete. It covers parameter semantics well and references another tool for schema details, but lacks information on return values, error cases, or behavioral traits. For a tool with this complexity, it should provide more context on output structure and usage constraints to be fully helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides clear semantics for all 5 parameters: 'file_id' and 'object_id' identify the target, 'fields' specifies what to include with a reference to another tool, 'depth' controls traversal with -1 meaning full depth, and 'format' sets output format. This adds substantial meaning beyond the bare schema, though it could elaborate on default behaviors beyond the schema's defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('object tree structure for a Penpot object'), including specific output fields like 'tree' and 'image.mcp_uri'. It distinguishes from siblings like 'get_file' or 'search_object' by focusing on tree structure and screenshot rendering. However, it doesn't explicitly contrast with 'penpot_tree_schema', which is mentioned as a reference tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing object tree structure with a rendered screenshot, but doesn't explicitly state when to use this versus alternatives like 'get_file' for basic file info or 'search_object' for finding objects. It references 'penpot_tree_schema' for field details, providing some context, but lacks clear exclusions or comparative guidance with other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all files contained within a specific Penpot project.
Args:
project_id: The ID of the Penpot project
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves files but doesn't describe return format (e.g., list structure, file metadata), pagination, rate limits, authentication needs, or error conditions. For a read operation with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise with two sentences: one for the purpose and one for the parameter. It's front-loaded with the core functionality. However, the formatting includes unnecessary indentation and whitespace, slightly detracting from structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (a read operation with no annotations, no output schema, and 0% schema coverage), the description is incomplete. It doesn't explain what 'files' means in this context (e.g., file types, metadata), how results are returned, or potential limitations. For a tool that likely returns a list of resources, more context is needed to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds minimal parameter semantics: it explains that 'project_id' is 'The ID of the Penpot project.' With 0% schema description coverage (schema has no descriptions), this provides basic meaning. However, it doesn't clarify format (e.g., UUID), sourcing, or validation rules. Since there's only one parameter, the baseline is 4, but the lack of detail beyond a tautological explanation reduces it to 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get all files contained within a specific Penpot project.' It specifies the verb ('Get') and resource ('files'), and distinguishes it from siblings like 'get_file' (singular) and 'list_projects' (different resource). However, it doesn't explicitly differentiate from 'get_cached_files' or 'export_object', which could be related operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when-not scenarios, prerequisites, or compare it to siblings like 'get_file' (for a single file) or 'search_object' (for filtered searches). The agent must infer usage from the tool name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a rendered component image by its ID.
| Name | Required | Description | Default |
|---|---|---|---|
| component_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool returns an image, but doesn't describe format, size, caching behavior, error handling, or authentication needs. For a tool with zero annotation coverage, this leaves critical behavioral traits unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose. It's front-loaded with no wasted words, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (retrieving rendered images), lack of annotations, no output schema, and low parameter coverage, the description is incomplete. It doesn't address return values, error cases, or operational context, leaving the agent with insufficient information for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'component_id' but doesn't explain what a component ID is, its format, or where to find it. With one undocumented parameter, the description adds minimal value beyond the schema's basic structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Return') and resource ('rendered component image by its ID'), making the purpose understandable. However, it doesn't distinguish this tool from siblings like 'get_file' or 'get_cached_files', which might also retrieve files or images, so it lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description doesn't mention prerequisites, context, or exclusions, leaving the agent without usage instructions. This is a significant gap in helping the agent select the correct tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a list of all available Penpot projects.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Retrieve a list') but does not cover critical traits like pagination, rate limits, authentication needs, or what 'all available' entails (e.g., permissions, archived projects). This leaves significant gaps for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any wasted words. It is front-loaded and appropriately sized for a simple retrieval tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is minimally adequate. However, it lacks details on return format, pagination, or error handling, which are important for a list retrieval tool, making it incomplete for optimal agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately does not add parameter details, aligning with the schema's completeness, but could have mentioned implicit constraints like authentication or scope.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Retrieve') and resource ('list of all available Penpot projects'), making the purpose unambiguous. However, it does not differentiate from sibling tools like 'get_project_files' or 'search_object', which might also involve project retrieval, so it misses full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'get_project_files' or 'search_object'. The description implies a broad retrieval but lacks context on use cases or exclusions, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Provide the Penpot API schema as JSON.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool does but fails to describe key traits such as whether it's a read-only operation, potential rate limits, authentication needs, or what the JSON output structure entails. This leaves significant gaps in understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence that efficiently conveys the core function without any wasted words. It is front-loaded with the essential information, making it highly concise and well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema), the description is minimal but insufficient. It lacks context about the schema's scope (e.g., full API vs. partial), format details, or how it differs from 'penpot_tree_schema'. Without annotations or output schema, more completeness is needed to guide effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema has 100% description coverage (though empty). The description doesn't need to add parameter details, so it appropriately avoids redundancy. A baseline of 4 is applied since no parameters exist, and the description doesn't mislead about inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Provide') and resource ('Penpot API schema as JSON'), making the purpose immediately understandable. However, it doesn't differentiate this tool from its sibling 'penpot_tree_schema', which appears to serve a similar schema-related function, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives like 'penpot_tree_schema' or other schema-related operations. It lacks context about prerequisites, timing, or comparisons with sibling tools, leaving the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Provide the Penpot object tree schema as JSON.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states what the tool does but lacks details on traits like whether it's read-only, requires authentication, has rate limits, or returns structured data. For a tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function with zero waste. It is front-loaded and appropriately sized for a simple tool, making it easy for an agent to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema) and lack of annotations, the description is minimally adequate but has clear gaps. It explains what the tool does but omits behavioral context and usage guidelines relative to siblings, making it incomplete for optimal agent decision-making in a server with multiple related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so there is no need for parameter semantics in the description. The baseline for this scenario is 4, as the description appropriately avoids redundant information and focuses on the tool's purpose without unnecessary details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Provide') and resource ('Penpot object tree schema as JSON'), making the purpose specific and understandable. However, it doesn't explicitly distinguish this tool from sibling tools like 'penpot_schema' or 'get_object_tree', which likely serve related but different purposes, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives. With sibling tools such as 'penpot_schema' and 'get_object_tree' available, there is no indication of context, prerequisites, or exclusions, leaving the agent to infer usage based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for objects within a Penpot file by name.
Args:
file_id: The ID of the Penpot file to search in
query: Search string (supports regex patterns)
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | ||
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool searches for objects by name and supports regex patterns, which adds some context. However, it doesn't cover critical aspects like whether this is a read-only operation, what happens if no matches are found, if there are rate limits, or the format of the return value (especially since there's no output schema). For a search tool with zero annotation coverage, this leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, with the main purpose stated first in a clear sentence. The Args section is structured and adds necessary details without redundancy. However, the use of triple quotes and extra whitespace slightly detracts from efficiency, but overall, it's concise and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a search operation with 2 parameters, no annotations, and no output schema, the description is incomplete. It explains the parameters but lacks information on behavioral traits (e.g., error handling, performance), output format, or how results are returned. Without annotations or an output schema, more context is needed for the agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful semantics beyond the input schema, which has 0% description coverage. It explains that 'file_id' is 'The ID of the Penpot file to search in' and 'query' is a 'Search string (supports regex patterns)', providing clarity on their roles. Since the schema only lists titles ('File Id', 'Query') without descriptions, this compensates well, though it doesn't detail constraints like format or length.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search for objects within a Penpot file by name.' It specifies the verb ('Search'), resource ('objects within a Penpot file'), and method ('by name'), making it easy to understand. However, it doesn't explicitly differentiate from sibling tools like 'get_object_tree' or 'get_file', which might also retrieve objects or file data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions searching by name but doesn't compare to siblings like 'get_object_tree' (which might list all objects) or 'get_file' (which might retrieve file metadata). There's no mention of prerequisites, such as needing a valid file ID, or exclusions, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
export_objectget_cached_filesget_fileget_object_treeget_project_filesget_rendered_componentlist_projectspenpot_schemapenpot_tree_schemasearch_objectScored across 10 tools
Most tools have distinct purposes, but 'get_file' and 'get_object_tree' could be confused as both retrieve file/object data, though their descriptions clarify different use cases (caching vs. tree structure with image). Other tools like export_object, list_projects, and search_object are clearly differentiated.
Tools follow a consistent verb_noun pattern (e.g., export_object, get_file, list_projects) with minor deviations: 'penpot_schema' and 'penpot_tree_schema' use noun-only names, breaking the pattern slightly but remaining readable and domain-specific.
With 10 tools, the count is well-scoped for a Penpot design server, covering key operations like listing projects, retrieving files, exporting objects, and searching, without being overwhelming or too sparse.
The toolset covers essential Penpot operations such as listing, retrieving, exporting, and searching, with minor gaps like updating or creating design objects (e.g., no create_file or update_object tools), but agents can likely work around this for basic workflows.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
AI-agent design tools: fonts, font recognition, palettes, color naming, contrast, code, SVG, CSS.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Build and manage your design system with AI: tokens, themes, components, icons, Figma and code.
