Penpot MCP Server
Penpot MCP-сервер 🎨🤖
🚀 Что такое Penpot MCP?
Penpot MCP — это революционный сервер Model Context Protocol (MCP), который заполняет пробел между моделями языка ИИ и Penpot , платформой проектирования и прототипирования с открытым исходным кодом. Эта интеграция позволяет помощникам ИИ, таким как Claude (как в Claude Desktop, так и в Cursor IDE), понимать, анализировать и взаимодействовать с вашими файлами дизайна программным способом.
🎯 Основные преимущества
🤖 Анализ дизайна AI-Native : позвольте Claude AI проанализировать ваши UI/UX-дизайны, предоставить обратную связь и предложить улучшения
⚡ Автоматизированные рабочие процессы проектирования : оптимизируйте повторяющиеся задачи проектирования с помощью автоматизации на базе ИИ
🔍 Интеллектуальный поиск по дизайну : находите компоненты и шаблоны дизайна в своих проектах, используя естественный язык
📊 Управление дизайн-системами : автоматическое документирование и поддержка дизайн-систем с помощью ИИ
🎨 Кроссплатформенная интеграция : работает с любым совместимым с MCP помощником на основе искусственного интеллекта (Claude Desktop, Cursor IDE и т. д.)
Related MCP server: AI-Canvas MCP Server
🎥 Демонстрационное видео
Посмотрите наше демонстрационное видео, чтобы увидеть Penpot MCP в действии:

✨ Особенности
🔌 Основные возможности
Реализация протокола MCP : полное соответствие стандартам Model Context Protocol
Доступ к проекту в режиме реального времени : прямая интеграция с API Penpot для получения данных о проекте в режиме реального времени
Анализ компонентов : анализ компонентов и макетов проекта с использованием искусственного интеллекта
Автоматизация экспорта : программный экспорт ресурсов дизайна в различные форматы
Проверка проекта : автоматическая проверка соответствия системы проектирования
🛠️ Инструменты разработчика
Утилиты командной строки : мощные инструменты CLI для анализа и проверки файлов проекта
Python SDK : комплексная библиотека Python для индивидуальной интеграции
REST API : конечные точки HTTP для интеграции веб-приложений
Расширяемая архитектура : система плагинов для пользовательских рабочих процессов ИИ
🎨 Возможности интеграции ИИ
Интеграция Claude Desktop и Cursor : встроенная поддержка помощника Claude AI в Claude Desktop и Cursor IDE
Обмен контекстом проектирования : предоставление контекста проектирования моделям ИИ для более точного реагирования.
Визуальное распознавание компонентов : ИИ может «видеть» и понимать компоненты дизайна
Запросы на естественном языке : задавайте вопросы о своих проектах на простом английском языке.
Интеграция с IDE : бесшовная интеграция с современными средами разработки
💡 Варианты использования
Для дизайнеров
Автоматизация обзора дизайна : получайте мгновенную обратную связь от ИИ по доступности, удобству использования и принципам дизайна.
Компонентная документация : автоматическое создание документации для систем проектирования
Проверки согласованности дизайна : обеспечение соответствия принципам бренда во всех проектах.
Организация активов : маркировка и категоризация компонентов дизайна с помощью искусственного интеллекта
Для разработчиков
Рабочие процессы «дизайн-код» : сократите разрыв между дизайном и разработкой с помощью ИИ
Интеграция API : программный доступ к данным проектирования для пользовательских инструментов и рабочих процессов
Автоматизированное тестирование : создание визуальных регрессионных тестов на основе спецификаций проекта.
Синхронизация системы проектирования : синхронизация токенов дизайна и компонентов кода.
Для продуктовых команд
Аналитика дизайна : отслеживание внедрения системы дизайна и использования компонентов
Улучшение совместной работы : обзоры проектов и сбор отзывов с использованием искусственного интеллекта
Оптимизация рабочего процесса : автоматизация повторяющихся операций проектирования и утверждения
Интеграция между инструментами : подключайте Penpot к другим инструментам в вашем рабочем процессе проектирования.
🚀 Быстрый старт
Предпосылки
Python 3.12+ (для оптимальной производительности рекомендуется последняя версия Python)
Аккаунт Penpot ( регистрация бесплатная )
Claude Desktop или Cursor IDE (опционально, для интеграции ИИ)
Установка
Предпосылки
Питон 3.12+
Данные учетной записи Penpot
Установка
Вариант 1: Установка из PyPI
pip install penpot-mcpВариант 2: Использование uv (рекомендуется для современной разработки на Python)
# 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Вариант 3: Установка из исходного кода
# 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 .Конфигурация
Создайте файл .env на основе env.example с вашими учетными данными Penpot:
PENPOT_API_URL=https://design.penpot.app/api
PENPOT_USERNAME=your_penpot_username
PENPOT_PASSWORD=your_penpot_password
PORT=5000
DEBUG=trueИспользование
Запуск сервера MCP
# 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_serverОтладка сервера MCP
Для отладки сервера MCP вы можете:
Включите режим отладки в файле
.env, установивDEBUG=trueИспользуйте Penpot API CLI для тестирования операций API:
# 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Мониторинг и тестирование MCP
Монитор MCP CLI
# 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-clientРесурсы и инструменты MCP
Ресурсы
server://info- Состояние сервера и информацияpenpot://schema— схема API Penpot в формате JSONpenpot://tree-schema— схема дерева объектов Penpot в формате JSONrendered-component://{component_id}— визуализированные изображения компонентовpenpot://cached-files— Список кэшированных файлов Penpot
Инструменты
list_projects— Список всех проектов Penpotget_project_files— Получить файлы для определенного проектаget_file— извлечь файл Penpot по его идентификатору и кэшировать егоexport_object— экспорт объекта Penpot как изображенияget_object_tree— Получить структуру дерева объектов для объекта Penpotsearch_object— Поиск объектов в файле Penpot по имени
Интеграция ИИ
Сервер Penpot MCP может быть интегрирован с помощниками ИИ с помощью Model Context Protocol. Он поддерживает как Claude Desktop, так и Cursor IDE для бесшовной автоматизации рабочего процесса проектирования.
Интеграция рабочего стола Клода
Подробные инструкции по настройке Claude Desktop см. в CLAUDE_INTEGRATION.md .
Добавьте следующую конфигурацию в файл конфигурации Claude Desktop ( ~/Library/Application Support/Claude/claude_desktop_config.json на macOS или %APPDATA%\Claude\claude_desktop_config.json на Windows):
{
"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"
}
}
}
}Интеграция курсора IDE
Cursor IDE поддерживает серверы MCP через свои функции интеграции AI. Чтобы настроить 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
Визуальный компонентный анализ с использованием идей на основе искусственного интеллекта
Проектирование возможностей экспорта для активов и компонентов
Запросы на естественном языке о ваших файлах дизайна
Отзывы и предложения по дизайну в режиме реального времени
Создание документации по проектированию системы
Структура пакета
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 — подробности см. в файле LICENSE .
Благодарности
Penpot — платформа с открытым исходным кодом для проектирования и создания прототипов
Протокол контекста модели — стандартизированный протокол для контекста модели ИИ.
Available Tools
10 toolsexport_objectC
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 |
TDQS
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.
get_cached_filesB
List all files currently stored in the cache.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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.
get_fileA
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 |
TDQS
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_object_treeB
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 |
TDQS
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_project_filesC
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 |
TDQS
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.
get_rendered_componentC
Return a rendered component image by its ID.
| Name | Required | Description | Default |
|---|---|---|---|
| component_id | Yes |
TDQS
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.
list_projectsB
Retrieve a list of all available Penpot projects.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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.
penpot_schemaB
Provide the Penpot API schema as JSON.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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.
penpot_tree_schemaB
Provide the Penpot object tree schema as JSON.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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_objectB
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 |
TDQS
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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
10 tool updates
- First observed
export_object - First observed
get_cached_files - First observed
get_file - First observed
get_object_tree - First observed
get_project_files - First observed
get_rendered_component - First observed
list_projects - First observed
penpot_schema - First observed
penpot_tree_schema - First observed
search_object
TDQS
Scored 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.
Maintenance
Related MCP Connectors
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.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to read and modify Figma designs programmatically, supporting design analysis, element creation, text replacement, annotations, auto-layout configuration, and prototype visualization through natural language commands.977 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to inspect, modify, export, and validate design documents with 47 tools covering design, code generation, branding, and print/mockup workflows.02MIT
- AlicenseCqualityFmaintenanceEnables AI assistants to create, modify, and manage Penpot designs programmatically, providing full manipulation capabilities for the open-source design tool.8169 npm20MIT
- AlicenseNot gradedqualityFmaintenanceEnables LLMs to query, transform, and create design elements in Penpot via the Model Context Protocol and Penpot's Plugin API.526Mozilla Public 2.0