query_elements
Search for diagram elements in Excalidraw by type, locked status, or group ID to filter and locate specific components.
Instructions
Search for elements by type, locked status, or group ID
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | ||
| locked | No | ||
| groupId | No |
Implementation Reference
- src/mcp/tools/query-elements.ts:4-16 (handler)The main handler function queryElementsTool that executes the query_elements tool logic. It parses input arguments using QuerySchema, builds a search filter object from type/locked/groupId parameters, calls client.searchElements(), and returns the results with success status and count.
export async function queryElementsTool( args: unknown, client: CanvasClient ) { const filter = QuerySchema.parse(args); const searchFilter: Record<string, string> = {}; if (filter.type) searchFilter.type = filter.type; if (filter.locked !== undefined) searchFilter.locked = String(filter.locked); if (filter.groupId) searchFilter.groupId = filter.groupId; const elements = await client.searchElements(searchFilter); return { success: true, elements, count: elements.length }; } - src/mcp/schemas/element.ts:176-182 (schema)QuerySchema defines the input validation schema for the query_elements tool. It accepts optional type (enum of element types), locked (boolean), and groupId (string) fields for filtering elements.
export const QuerySchema = z .object({ type: ElementTypeSchema.optional(), locked: z.boolean().optional(), groupId: z.string().max(LIMITS.MAX_GROUP_ID_LENGTH).optional(), }) .strict(); - src/mcp/index.ts:155-182 (registration)Registration of the query_elements tool in the MCP server. Defines the tool name, description, input schema using zod validation for optional type/locked/groupId filters, and the async handler function that builds search filters and returns JSON-formatted results.
// --- Tool: query_elements --- server.tool( 'query_elements', 'Search for elements by type, locked status, or group ID', { type: z.enum(ELEMENT_TYPES).optional(), locked: z.boolean().optional(), groupId: z.string().max(LIMITS.MAX_GROUP_ID_LENGTH).optional(), }, async (filter) => { try { const searchFilter: Record<string, string> = {}; if (filter.type) searchFilter.type = filter.type; if (filter.locked !== undefined) searchFilter.locked = String(filter.locked); if (filter.groupId) searchFilter.groupId = filter.groupId; const elements = await client.searchElements(searchFilter); return { content: [{ type: 'text', text: JSON.stringify({ elements, count: elements.length }, null, 2), }], }; } catch (err) { return { content: [{ type: 'text', text: `Error: ${(err as Error).message}` }], isError: true }; } } );