Heptabase MCP

Implementation Reference

• src/server.ts:414-460 (handler)

  The primary handler for the 'getWhiteboard' MCP tool. Ensures data service initialization, fetches whiteboard data with options, generates a formatted text summary of the whiteboard, cards, and connections, and handles errors gracefully.

  this.tools.getWhiteboard = {
    inputSchema: getWhiteboardSchema,
    handler: async (params) => {
      try {
        await this.ensureDataServiceInitialized();
  
        const options = {
          includeCards: params.includeCards || false,
          includeConnections: params.includeConnections || false,
          depth: params.depth
        };
  
        const result = await this.dataService!.getWhiteboard(params.whiteboardId, options);
        
        let text = `Whiteboard: ${result.whiteboard.name} (ID: ${result.whiteboard.id})\n`;
        text += `Created: ${result.whiteboard.createdTime}\n`;
        text += `Last edited: ${result.whiteboard.lastEditedTime}\n`;
        
        if (result.cards) {
          text += `\nCards: ${result.cards.length}\n`;
          result.cards.forEach(card => {
            text += `- ${card.title || 'Untitled'} (ID: ${card.id})\n`;
          });
        }
        
        if (result.connections) {
          text += `\nConnections: ${result.connections.length}\n`;
        }
  
        return {
          content: [{
            type: 'text',
            text
          }]
        };
      } catch (error) {
        console.error('Error in getWhiteboard:', error);
        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
        return {
          content: [{
            type: 'text',
            text: `Error: ${errorMessage}`
          }]
        };
      }
    }
  };

• src/server.ts:407-412 (schema)

  Zod input schema validation for the getWhiteboard tool, requiring whiteboardId and optionally including cards, connections, and depth.

  const getWhiteboardSchema = z.object({
    whiteboardId: z.string(),
    includeCards: z.boolean().optional(),
    includeConnections: z.boolean().optional(),
    depth: z.number().optional()
  });

• src/server.ts:462-464 (registration)

  MCP server registration of the getWhiteboard tool, linking the schema and handler.

  this.server.tool('getWhiteboard', getWhiteboardSchema.shape, async (params) => {
    return this.tools.getWhiteboard.handler(params);
  });

• src/services/HeptabaseDataService.ts:199-225 (helper)

  Helper method in HeptabaseDataService that retrieves a whiteboard by ID, optionally populating associated cards and connections from the loaded data structures.

  async getWhiteboard(
    whiteboardId: string,
    options: { includeCards?: boolean; includeConnections?: boolean } = {}
  ): Promise<WhiteboardResult> {
    const whiteboard = this.data.whiteboards[whiteboardId];
    if (!whiteboard) {
      throw new Error('Whiteboard not found');
    }
  
    const result: WhiteboardResult = { whiteboard };
  
    if (options.includeCards) {
      const instances = Object.values(this.data.cardInstances).filter(
        instance => instance.whiteboardId === whiteboardId
      );
      const cardIds = instances.map(instance => instance.cardId);
      result.cards = cardIds.map(id => this.data.cards[id]).filter(Boolean);
    }
  
    if (options.includeConnections) {
      result.connections = Object.values(this.data.connections).filter(
        connection => connection.whiteboardId === whiteboardId
      );
    }
  
    return result;
  }