getCardsByArea
Retrieve cards within a specific area on a Heptabase whiteboard using coordinates and radius for focused data analysis and organization.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| radius | No | ||
| whiteboardId | Yes | ||
| x | Yes | ||
| y | Yes |
Implementation Reference
- src/server.ts:628-658 (handler)The main tool handler function that fetches cards by area using the data service, formats a text response listing the cards and their positions, and returns it in the expected MCP content format.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 (string), x/y (numbers), 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)Registration of the 'getCardsByArea' tool with the MCP server, using the schema and delegating to the predefined handler.this.server.tool('getCardsByArea', getCardsByAreaSchema.shape, async (params) => { return this.tools.getCardsByArea.handler(params); });
- Helper method in HeptabaseDataService that computes cards within a given radius on a whiteboard by filtering card instances based on Euclidean distance.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); }