getCardsByArea
Retrieve cards within a specified area on a Heptabase whiteboard by providing coordinates and a search radius for targeted data extraction and analysis.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| radius | No | ||
| whiteboardId | Yes | ||
| x | Yes | ||
| y | Yes |
Implementation Reference
- src/server.ts:626-659 (handler)The primary handler for the 'getCardsByArea' MCP tool. It initializes the data service if needed, fetches cards within a specified radius on a whiteboard using the data service, retrieves position details for each card, and returns a formatted text summary of the results.this.tools.getCardsByArea = { inputSchema: getCardsByAreaSchema, handler: async (params) => { await this.ensureDataServiceInitialized(); const radius = params.radius || 100; const cards = await this.dataService!.getCardsByArea( params.whiteboardId, params.x, params.y, radius ); let text = `Found ${cards.length} cards within radius ${radius} of (${params.x}, ${params.y})\n`; for (const card of cards) { text += `\n- ${card.title || 'Untitled'} (ID: ${card.id})\n`; // Get instance info to show position const result = await this.dataService!.getCard(card.id); const instance = result.instances.find(i => i.whiteboardId === params.whiteboardId); if (instance) { text += ` Position: (${instance.x}, ${instance.y})\n`; } } return { content: [{ type: 'text', text }] }; } };
- src/server.ts:619-624 (schema)Zod schema defining the input parameters for the getCardsByArea tool: whiteboardId (required string), x and y coordinates (required numbers), and optional radius (number).const getCardsByAreaSchema = z.object({ whiteboardId: z.string(), x: z.number(), y: z.number(), radius: z.number().optional() });
- src/server.ts:661-663 (registration)MCP server tool registration for 'getCardsByArea', linking the tool name, input schema shape, and delegating to the predefined handler.this.server.tool('getCardsByArea', getCardsByAreaSchema.shape, async (params) => { return this.tools.getCardsByArea.handler(params); });
- Core data service method that implements the spatial query: filters card instances on the given whiteboard within the Euclidean distance radius from (x,y), then returns the corresponding unique cards.async getCardsByArea( whiteboardId: string, x: number, y: number, radius: number ): Promise<Card[]> { const instances = Object.values(this.data.cardInstances).filter(instance => { if (instance.whiteboardId !== whiteboardId) return false; const distance = Math.sqrt( Math.pow(instance.x - x, 2) + Math.pow(instance.y - y, 2) ); return distance <= radius; }); const cardIds = instances.map(instance => instance.cardId); return cardIds.map(id => this.data.cards[id]).filter(Boolean); }