Bar Assistant MCP Server

Instructions

Implementation Reference

• src/types.ts:221-235 (schema)

  Type definition for input parameters of the smart_search_cocktails tool

  export interface SmartSearchCocktailsParams {
    query?: string;
    similar_to?: string;
    similar_to_id?: number;
    ingredient?: string;
    must_include?: string[];
    must_exclude?: string[];
    preferred_flavors?: string[];
    preferred_strength?: 'light' | 'medium' | 'strong';
    abv_min?: number;
    abv_max?: number;
    glass_type?: string;
    preparation_method?: string;
    limit?: number;
  }

• src/bar-assistant-mcp-server.ts:870-1073 (registration)

  Tool registration in ListToolsRequestSchema handler, defining name, description, inputSchema, and outputSchema

              name: 'smart_search_cocktails',
              description: `🚀 PREFERRED TOOL: Advanced cocktail search with intelligent batch processing and complete recipes.
  
  **🎯 BATCH PROCESSING SYSTEM:**
  - **High Performance**: Parallel processing with 5-10x speed improvement
  - **Smart Caching**: Automatic caching for 70%+ faster repeated searches
  - **Error Resilience**: Individual failures don't break entire batch operations
  - **Flexible Limits**: Configure result count (default: 20, max: 50)
  
  **📋 Use Cases:**
  - General searches: "gin cocktails", "winter drinks", "classic cocktails"
  - Similarity queries: "cocktails like Manhattan", "similar to Negroni"
  - Ingredient-based: "cocktails with bourbon", "drinks using Campari"
  - Flavor profiles: "bitter cocktails", "sweet drinks", "herbal spirits"
  - Complex filtering: combine ingredients, ABV ranges, glass types, methods
  - Batch comparisons: Multiple ingredient searches simultaneously
  
  **🔄 Batch Processing Examples:**
  - Single search: {query: "Manhattan"} → Complete recipe + similar cocktails
  - Multi-ingredient: {ingredient: "gin", must_include: ["vermouth", "bitters"]}
  - Similarity batch: {similar_to: "Negroni", limit: 10} → 10 similar cocktails
  - Complex filter: {preferred_flavors: ["bitter"], abv_min: 25, limit: 15}
  
  **📊 Response Format:**
  Returns structured data with complete recipes including:
  - Ingredients with precise measurements in oz (auto-converted from ml)
  - Step-by-step preparation instructions
  - Cocktail specifications (ABV, glass, method, garnish)
  - Direct links to cocktail database pages
  - Performance metrics (processing time, cache hits)
  - Similar cocktail recommendations with full recipes
  
  **⚡ Performance Features:**
  - Parallel API processing for multiple results
  - Intelligent caching system with TTL management
  - Batch fetching of complete recipe details
  - Error isolation and fallback handling`,
              inputSchema: {
                type: 'object',
                properties: {
                  // Core search parameters
                  query: {
                    type: 'string',
                    description: '🔍 Natural language search query (e.g., "Negroni", "gin cocktails", "bitter drinks")',
                  },
                  similar_to: {
                    type: 'string',
                    description: '🔄 Find cocktails similar to this name (e.g., "Manhattan", "Negroni"). Triggers similarity batch processing.',
                  },
                  similar_to_id: {
                    type: 'number',
                    description: '🆔 Find cocktails similar to this ID. Use similar_to (by name) unless you have the specific ID.',
                  },
                  
                  // Ingredient filtering (supports batch processing)
                  ingredient: {
                    type: 'string',
                    description: '🥃 Primary ingredient filter (e.g., "gin", "whiskey", "campari"). Combines with other filters for batch processing.',
                  },
                  must_include: {
                    type: 'array',
                    items: { type: 'string' },
                    description: '✅ Required ingredients array. Batch processes cocktails containing ALL these ingredients.',
                  },
                  must_exclude: {
                    type: 'array',
                    items: { type: 'string' },
                    description: '❌ Excluded ingredients array. Filters out cocktails with ANY of these ingredients.',
                  },
                  
                  // Advanced filtering (enhances batch results)
                  preferred_flavors: {
                    type: 'array',
                    items: { type: 'string' },
                    description: '🎯 Flavor profile preferences: ["bitter", "sweet", "sour", "spicy", "herbal"]. Improves batch ranking.',
                  },
                  preferred_strength: {
                    type: 'string',
                    enum: ['light', 'medium', 'strong'],
                    description: '💪 Alcohol strength preference. Filters batch results by ABV ranges.',
                  },
                  abv_min: {
                    type: 'number',
                    description: '📊 Minimum ABV percentage. Lower bound for batch filtering.',
                  },
                  abv_max: {
                    type: 'number',
                    description: '📊 Maximum ABV percentage. Upper bound for batch filtering.',
                  },
                  
                  // Presentation filtering
                  glass_type: {
                    type: 'string',
                    description: '🥂 Required glassware (e.g., "coupe", "rocks", "martini"). Filters entire batch.',
                  },
                  preparation_method: {
                    type: 'string',
                    description: '🔧 Required method (e.g., "shake", "stir", "build"). Filters batch by technique.',
                  },
                  
                  // Batch control parameters
                  limit: {
                    type: 'number',
                    description: '🎛️ Maximum results to return (default: 20, max: 50). Controls batch size for optimal performance.',
                    default: 20,
                    minimum: 1,
                    maximum: 50,
                  },
                },
              },
              outputSchema: {
                type: 'object',
                description: '🎯 Batch processing response with complete cocktail data and performance metrics',
                properties: {
                  search_results: {
                    type: 'object',
                    properties: {
                      total_found: { 
                        type: 'number',
                        description: 'Total cocktails found matching criteria' 
                      },
                      returned: { 
                        type: 'number',
                        description: 'Number of cocktails returned (limited by batch size)' 
                      },
                      search_type: { 
                        type: 'string',
                        description: 'Type of search performed (query, similarity, ingredient, etc.)' 
                      }
                    }
                  },
                  cocktails: {
                    type: 'array',
                    description: 'Complete cocktail recipes with full details',
                    items: {
                      type: 'object',
                      properties: {
                        id: { type: 'number' },
                        name: { type: 'string' },
                        description: { type: 'string' },
                        ingredients: {
                          type: 'array',
                          items: {
                            type: 'object',
                            properties: {
                              name: { type: 'string' },
                              formatted: { type: 'string', description: 'Human-readable amount with units' },
                              amount: { type: 'string' },
                              optional: { type: 'boolean' }
                            }
                          }
                        },
                        instructions: {
                          type: 'array',
                          items: {
                            type: 'object',
                            properties: {
                              step: { type: 'number' },
                              instruction: { type: 'string' }
                            }
                          }
                        },
                        details: {
                          type: 'object',
                          properties: {
                            abv: { type: 'number', description: 'Alcohol by volume percentage' },
                            glass: { type: 'string', description: 'Recommended glassware' },
                            method: { type: 'string', description: 'Preparation method' },
                            garnish: { type: 'string', description: 'Garnish instructions' },
                            direct_link: { type: 'string', description: 'URL to full recipe page' },
                            tags: { type: 'array', items: { type: 'string' } }
                          }
                        }
                      }
                    }
                  },
                  similar_cocktails: {
                    type: 'array',
                    description: 'Additional similar cocktails (when using similarity search)',
                    items: { $ref: '#/properties/cocktails/items' }
                  },
                  performance_metrics: {
                    type: 'object',
                    description: 'Batch processing performance data',
                    properties: {
                      processing_time_ms: { type: 'number' },
                      api_calls_made: { type: 'number' },
                      cache_hits: { type: 'number' },
                      cache_misses: { type: 'number' },
                      batch_processing_used: { type: 'boolean' },
                      parallel_requests: { type: 'number' }
                    }
                  },
                  search_metadata: {
                    type: 'object',
                    properties: {
                      enhanced_query: { type: 'string', description: 'Processed natural language query' },
                      applied_filters: { type: 'array', items: { type: 'string' } },
                      search_strategy: { type: 'string', description: 'Batch processing strategy used' }
                    }
                  }
                }
              },
            },

• src/bar-assistant-mcp-server.ts:1304-1305 (registration)

  Dispatch to handler in CallToolRequestSchema switch statement

  case 'smart_search_cocktails':
    return await this.handleSmartSearchCocktails(args as any);

• src/bar-assistant-mcp-server.ts:1756-1827 (handler)

  Main handler function that implements the smart_search_cocktails tool logic, including caching, similarity search, cocktail search, recipe fetching, and response formatting

  private async handleSmartSearchCocktails(args: SmartSearchCocktailsParams) {
    const startTime = Date.now();
    
    try {
      // Parse natural language query if provided
      let enhancedArgs = { ...args };
      if (args.query && typeof args.query === 'string') {
        const parsedQuery = QueryParser.parse(args.query);
        enhancedArgs = QueryParser.enhanceSearchArgs(args, parsedQuery);
      }
      
      // Check cache for search results
      const cacheKey = JSON.stringify(enhancedArgs);
      const cachedResult = this.cacheManager.getCachedSearch(cacheKey);
      if (cachedResult) {
        return cachedResult;
      }
      
      // Handle similarity queries first (by name or ID)
      if (enhancedArgs.similar_to || enhancedArgs.similar_to_id) {
        const result = await this.handleSimilaritySearch(enhancedArgs, startTime);
        // Cache similarity search results
        this.cacheManager.setCachedSearch(cacheKey, result);
        return result;
      }
  
      // Perform the main search
      const { results, searchType, appliedFilters } = await this.performCocktailSearch(enhancedArgs);
      
      // Build structured response
      const structuredData: ResponseSchemas.CocktailSearchResponse = {
        results: await this.fetchCompleteRecipes(results.slice(0, enhancedArgs.limit || 20)),
        query: {
          terms: enhancedArgs.query || undefined,
          filters: appliedFilters,
          search_type: searchType
        },
        metadata: this.createResponseMetadata('bar_assistant_api', results.length, startTime)
      };
  
      // Build human-readable response
      const humanText = this.formatSearchResultsText(structuredData, enhancedArgs);
  
      const result = this.createStructuredResponse(humanText, structuredData);
      
      // Cache regular search results
      this.cacheManager.setCachedSearch(cacheKey, result);
      
      return result;
      
    } catch (error) {
      const errorData: ResponseSchemas.ErrorResponse = {
        error: error instanceof Error ? error.message : String(error),
        error_code: 'SEARCH_ERROR',
        suggestions: [
          'Check your search criteria and try again',
          'Try broader search terms',
          'Remove some filters',
          'Check ingredient spelling'
        ],
        query: args,
        metadata: this.createResponseMetadata('error', 0, startTime)
      };
  
      const errorText = `# Smart Search Error\n\n` +
        `Sorry, I encountered an error while searching for cocktails.\n\n` +
        `**Error:** ${errorData.error}\n\n` +
        `**Suggestions:**\n${errorData.suggestions?.map(s => `• ${s}`).join('\n')}`;
  
      return this.createStructuredResponse(errorText, errorData);
    }
  }

• src/bar-assistant-mcp-server.ts:542-642 (helper)

  Helper method that performs the core cocktail search with filtering and returns structured results used by the main handler

  private async performCocktailSearch(args: any) {
    // Build search parameters
    const searchParams: SearchCocktailsParams = {
      limit: args.limit || 20,
    };
  
    let searchType = 'general';
    const appliedFilters: Record<string, any> = {};
  
    // Handle basic queries
    if (args.query) {
      searchParams.query = args.query;
      searchType = 'name';
      appliedFilters.query = args.query;
    }
    if (args.ingredient) {
      searchParams.ingredient = args.ingredient;
      searchType = 'ingredient';
      appliedFilters.ingredient = args.ingredient;
    }
  
    // Handle ABV filtering
    if (args.abv_min !== undefined) {
      searchParams.abv_min = args.abv_min;
      appliedFilters.abv_min = args.abv_min;
    }
    if (args.abv_max !== undefined) {
      searchParams.abv_max = args.abv_max;
      appliedFilters.abv_max = args.abv_max;
    }
    
    // Convert strength preferences to ABV ranges
    if (args.preferred_strength && !args.abv_min && !args.abv_max) {
      searchType = 'strength';
      appliedFilters.preferred_strength = args.preferred_strength;
      switch (args.preferred_strength) {
        case 'light':
          searchParams.abv_max = 15;
          break;
        case 'medium':
          searchParams.abv_min = 15;
          searchParams.abv_max = 30;
          break;
        case 'strong':
          searchParams.abv_min = 30;
          break;
      }
    }
  
    // Handle flavor-based searches
    if (args.preferred_flavors?.length > 0) {
      searchType = 'flavor';
      appliedFilters.preferred_flavors = args.preferred_flavors;
      if (!args.ingredient) {
        const flavorIngredientMap: { [key: string]: string } = {
          'bitter': 'campari',
          'sweet': 'vermouth',
          'sour': 'lemon',
          'herbal': 'chartreuse',
          'spicy': 'ginger',
        };
        
        for (const flavor of args.preferred_flavors) {
          if (flavorIngredientMap[flavor.toLowerCase()]) {
            searchParams.ingredient = flavorIngredientMap[flavor.toLowerCase()];
            break;
          }
        }
      }
    }
  
    // Handle must_include ingredients
    if (args.must_include?.length > 0) {
      appliedFilters.must_include = args.must_include;
      if (!searchParams.ingredient) {
        searchParams.ingredient = args.must_include[0];
      }
    }
  
    // Handle exclusions
    if (args.must_exclude?.length > 0) {
      appliedFilters.must_exclude = args.must_exclude;
    }
  
    // Glass and method filters
    if (args.glass_type) appliedFilters.glass_type = args.glass_type;
    if (args.preparation_method) appliedFilters.preparation_method = args.preparation_method;
  
    // Perform the search
    let results = await this.barClient.searchCocktails(searchParams);
    let filteredResults = results.data;
  
    // Apply post-search filtering
    filteredResults = this.applyAdvancedFilters(filteredResults, args);
  
    return {
      results: filteredResults,
      searchType,
      appliedFilters
    };
  }