searchCards

Implementation Reference

• src/server.ts:353-397 (handler)

  The primary handler function for the 'searchCards' MCP tool. It constructs a SearchQuery from input parameters, calls the data service's searchCards method, and formats a text response listing matching cards (title and ID only, due to MCP limits).

  handler: async (params) => {
    await this.ensureDataServiceInitialized();
  
    const searchQuery: any = {};
    
    if (params.query) {
      searchQuery.query = params.query;
    }
    
    if (params.tags) {
      searchQuery.tags = params.tags;
    }
    
    if (params.whiteboardId) {
      searchQuery.whiteboardId = params.whiteboardId;
    }
    
    if (params.contentType) {
      searchQuery.contentType = params.contentType;
    }
    
    if (params.dateRange) {
      searchQuery.dateRange = {
        start: new Date(params.dateRange.start),
        end: new Date(params.dateRange.end)
      };
    }
  
    const results = await this.dataService!.searchCards(searchQuery);
    
    // Due to MCP response size limits, only show basic info in search results
    // Use getCard for full content
    const text = `Found ${results.length} cards:\n` +
      results.map(card => {
        return `- ${card.title || 'Untitled'} (ID: ${card.id})`;
      }).join('\n') +
      '\n\nUse getCard with specific card ID to get full content.';
  
    return {
      content: [{
        type: 'text',
        text
      }]
    };
  }

• src/server.ts:340-349 (schema)

  Zod schema defining the input parameters for the searchCards tool: optional query string, tags array, whiteboardId, contentType enum, and dateRange object.

  const searchCardsSchema = z.object({
    query: z.string().optional(),
    tags: z.array(z.string()).optional(),
    whiteboardId: z.string().optional(),
    contentType: z.enum(['text', 'image', 'link']).optional(),
    dateRange: z.object({
      start: z.string(),
      end: z.string()
    }).optional()
  });

• src/server.ts:400-402 (registration)

  Registers the 'searchCards' tool with the MCP server using the defined schema and delegates execution to the pre-defined handler in this.tools.searchCards.

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

• src/services/HeptabaseDataService.ts:151-197 (helper)

  Supporting method in HeptabaseDataService that implements the core filtering logic for cards: excludes trashed, matches query in title/content, filters by whiteboard instances and creation date range, with optional caching.

  async searchCards(query: SearchQuery): Promise<Card[]> {
    const cacheKey = `cards:${JSON.stringify(query)}`;
    
    if (this.config.cacheEnabled) {
      const cached = this.getFromCache(cacheKey);
      if (cached) return cached;
    }
  
    const results = Object.values(this.data.cards).filter(card => {
      // Filter out trashed cards
      if (card.isTrashed) return false;
  
      // Search by query in title and content
      if (query.query) {
        const searchTerm = query.query.toLowerCase();
        const titleMatch = card.title?.toLowerCase().includes(searchTerm) || false;
        const contentMatch = card.content.toLowerCase().includes(searchTerm);
        if (!titleMatch && !contentMatch) {
          return false;
        }
      }
  
      // Filter by whiteboard
      if (query.whiteboardId) {
        const hasInstance = Object.values(this.data.cardInstances).some(
          instance => instance.cardId === card.id && instance.whiteboardId === query.whiteboardId
        );
        if (!hasInstance) return false;
      }
  
      // Filter by date range
      if (query.dateRange) {
        const createdDate = new Date(card.createdTime);
        if (createdDate < query.dateRange.start || createdDate > query.dateRange.end) {
          return false;
        }
      }
  
      return true;
    });
  
    if (this.config.cacheEnabled) {
      this.setCache(cacheKey, results);
    }
  
    return results;
  }