search_object
Locate objects within a Penpot design file by name using regex-compatible search queries to streamline design analysis and automation workflows.
Instructions
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)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | ||
| query | Yes |
Implementation Reference
- penpot_mcp/server/mcp_server.py:341-369 (handler)The core handler function for the 'search_object' tool. It retrieves the cached file data, compiles a case-insensitive regex pattern from the query, iterates through pages and objects to find matching names, and returns a list of matching objects with their details.def search_object(file_id: str, query: str) -> dict: """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) """ try: file_data = get_cached_file(file_id) if "error" in file_data: return file_data pattern = re.compile(query, re.IGNORECASE) matches = [] data = file_data.get('data', {}) for page_id, page_data in data.get('pagesIndex', {}).items(): page_name = page_data.get('name', 'Unnamed') for obj_id, obj_data in page_data.get('objects', {}).items(): obj_name = obj_data.get('name', '') if pattern.search(obj_name): matches.append({ 'id': obj_id, 'name': obj_name, 'page_id': page_id, 'page_name': page_name, 'object_type': obj_data.get('type', 'unknown') }) return {'objects': matches} except Exception as e: return self._handle_api_error(e)
- Internal helper function used by search_object (and other tools) to retrieve and cache Penpot file data from the API.def get_cached_file(file_id: str) -> dict: """Internal helper to retrieve a file, using cache if available. Args: file_id: The ID of the Penpot file """ cached_data = self.file_cache.get(file_id) if cached_data is not None: return cached_data try: file_data = self.api.get_file(file_id=file_id) self.file_cache.set(file_id, file_data) return file_data except Exception as e: return self._handle_api_error(e)