Heptabase MCP

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

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

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