Heptabase MCP

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);
  });

• src/services/HeptabaseDataService.ts:240-258 (helper)

  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);
  }