Heptabase MCP

Implementation Reference

• src/services/HeptabaseDataService.ts:113-149 (handler)

  Core implementation of the searchWhiteboards function in the data service. Filters whiteboards by query string, date range, excludes trashed ones, and supports caching.

  async searchWhiteboards(query: SearchQuery): Promise<Whiteboard[]> {
    const cacheKey = `whiteboards:${JSON.stringify(query)}`;
    
    if (this.config.cacheEnabled) {
      const cached = this.getFromCache(cacheKey);
      if (cached) return cached;
    }
  
    const results = Object.values(this.data.whiteboards).filter(whiteboard => {
      // Filter out trashed whiteboards
      if (whiteboard.isTrashed) return false;
  
      // Search by query
      if (query.query) {
        const searchTerm = query.query.toLowerCase();
        if (!whiteboard.name.toLowerCase().includes(searchTerm)) {
          return false;
        }
      }
  
      // Filter by date range
      if (query.dateRange) {
        const createdDate = new Date(whiteboard.createdTime);
        if (createdDate < query.dateRange.start || createdDate > query.dateRange.end) {
          return false;
        }
      }
  
      return true;
    });
  
    if (this.config.cacheEnabled) {
      this.setCache(cacheKey, results);
    }
  
    return results;
  }

• src/server.ts:285-293 (schema)

  Zod input schema validation for the searchWhiteboards tool parameters.

  const searchWhiteboardsSchema = z.object({
    query: z.string().optional(),
    dateRange: z.object({
      start: z.string(),
      end: z.string()
    }).optional(),
    hasCards: z.boolean().optional(),
    spaceId: z.string().optional()
  });

• src/server.ts:335-337 (registration)

  MCP server registration of the searchWhiteboards tool.

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

• src/server.ts:295-333 (handler)

  Tool wrapper handler that prepares parameters, calls the data service searchWhiteboards, and formats results for MCP response.

  this.tools.searchWhiteboards = {
    inputSchema: searchWhiteboardsSchema,
    handler: async (params) => {
      await this.ensureDataServiceInitialized();
  
      const searchQuery: any = {};
      
      if (params.query) {
        searchQuery.query = params.query;
      }
      
      if (params.dateRange) {
        searchQuery.dateRange = {
          start: new Date(params.dateRange.start),
          end: new Date(params.dateRange.end)
        };
      }
      
      if (params.hasCards !== undefined) {
        searchQuery.hasCards = params.hasCards;
      }
      
      if (params.spaceId) {
        searchQuery.spaceId = params.spaceId;
      }
  
      const results = await this.dataService!.searchWhiteboards(searchQuery);
      
      const text = `Found ${results.length} whiteboards${results.length > 0 ? ':\n' : ''}` +
        results.map(wb => `- ${wb.name} (ID: ${wb.id}, Last edited: ${wb.lastEditedTime})`).join('\n');
  
      return {
        content: [{
          type: 'text',
          text
        }]
      };
    }
  };