Bar Assistant MCP Server

Instructions

Implementation Reference

• src/bar-assistant-mcp-server.ts:1075-1257 (registration)

  Registration of the 'get_recipe' tool in the MCP server, including detailed description, input schema matching GetRecipeParams, and output schema definition.

              name: 'get_recipe',
              description: `🍸 Advanced recipe retrieval with powerful batch processing for multiple cocktails.
  
  **🚀 BATCH PROCESSING SYSTEM:**
  - **High Performance**: 5-10x faster than sequential requests
  - **Parallel Processing**: Simultaneous API calls with error isolation
  - **Smart Caching**: 70%+ cache hit rate for repeated requests
  - **Flexible Input**: Mix cocktail names and IDs in single request
  - **Error Resilience**: Individual failures don't break entire batch
  
  **📋 LLM Usage Patterns:**
  - **Single Recipe**: When user asks for "how to make [cocktail]"
  - **Recipe Comparison**: When user wants to compare multiple cocktails
  - **Menu Planning**: Batch retrieve recipes for event planning
  - **Variation Exploration**: Get base recipe + similar cocktails
  - **Research Mode**: Efficient lookup of multiple specific recipes
  
  **🎯 Input Methods (Choose Based on Use Case):**
  
  1. **Single Recipe (Backwards Compatible)**:
     - cocktail_name: "Manhattan" → One complete recipe
     - cocktail_id: 123 → Recipe by database ID
  
  2. **Batch by Names (Most Common)**:
     - cocktail_names: ["Negroni", "Manhattan", "Martini"] → Multiple complete recipes
  
  3. **Batch by IDs (When Available)**:
     - cocktail_ids: [1, 2, 3] → Multiple recipes by database IDs
  
  4. **Mixed Batch (Maximum Flexibility)**:
     - cocktail_names: ["Aviation"] + cocktail_ids: [123, 456] → Combined approach
  
  5. **With Variations (Exploration)**:
     - Any above + include_variations: true → Base recipes + similar cocktails
  
  **📊 Response Format:**
  Structured output with complete recipe data:
  - Precise ingredient measurements (auto-converted to oz)
  - Step-by-step preparation instructions
  - Cocktail specifications (ABV, glassware, method, garnish)
  - Direct database links for each recipe
  - Performance metrics (timing, cache usage)
  - Similar recipes when requested
  - Rich formatting with emojis and clear sections
  
  **⚡ Performance Examples:**
  - Single recipe: ~150-300ms (cached responses faster)
  - Batch (3 cocktails): ~250-400ms (vs 900ms+ sequential)
  - Mixed batch (5 cocktails): ~300-500ms with parallel processing
  - Cache hit: <50ms instant response
  
  **🎛️ Batch Control Parameters:**
  - limit: 1-20 recipes (default: 10) - controls batch size
  - include_variations: Boolean - adds similar cocktails to results`,
              inputSchema: {
                type: 'object',
                description: '🎛️ Flexible input schema supporting single recipes and high-performance batch processing',
                properties: {
                  // Single recipe parameters (backwards compatible)
                  cocktail_id: {
                    type: 'number',
                    description: '🆔 Single cocktail database ID. Use for specific recipe lookup when ID is known.',
                  },
                  cocktail_name: {
                    type: 'string',
                    description: '🍸 Single cocktail name. Use for individual recipe requests (e.g., "Manhattan", "Negroni").',
                  },
                  
                  // Batch processing parameters (high performance)
                  cocktail_ids: {
                    type: 'array',
                    items: { type: 'number' },
                    description: '🚀 Array of cocktail IDs for batch processing. Enables parallel retrieval of multiple recipes by database ID. More efficient than multiple single requests.',
                  },
                  cocktail_names: {
                    type: 'array',
                    items: { type: 'string' },
                    description: '🚀 Array of cocktail names for batch processing. Enables parallel retrieval of multiple recipes by name (e.g., ["Manhattan", "Negroni", "Martini"]). Triggers name resolution + batch fetching.',
                  },
                  
                  // Enhancement parameters
                  include_variations: {
                    type: 'boolean',
                    description: '🔄 Include similar/variation recipes in results. Adds related cocktails to expand exploration (default: false).',
                    default: false,
                  },
                  
                  // Batch control parameters
                  limit: {
                    type: 'number',
                    description: '🎛️ Maximum number of recipes to return. Controls batch size for optimal performance (default: 10, max: 20). Higher limits may impact response time.',
                    default: 10,
                    minimum: 1,
                    maximum: 20,
                  },
                },
                // Schema validation rules for LLMs
                oneOf: [
                  {
                    description: 'Single recipe by name',
                    required: ['cocktail_name']
                  },
                  {
                    description: 'Single recipe by ID', 
                    required: ['cocktail_id']
                  },
                  {
                    description: 'Batch processing by names',
                    required: ['cocktail_names']
                  },
                  {
                    description: 'Batch processing by IDs',
                    required: ['cocktail_ids']
                  },
                  {
                    description: 'Mixed batch processing',
                    anyOf: [
                      { required: ['cocktail_names', 'cocktail_ids'] },
                      { required: ['cocktail_names', 'cocktail_id'] },
                      { required: ['cocktail_name', 'cocktail_ids'] }
                    ]
                  }
                ],
              },
              outputSchema: {
          type: 'object',
          properties: {
            recipes: {
              type: 'array',
              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' },
                        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' },
                      glass: { type: 'string' },
                      method: { type: 'string' },
                      garnish: { type: 'string' },
                      direct_link: { type: 'string' },
                      tags: { type: 'array', items: { type: 'string' } }
                    }
                  }
                }
              }
            },
            performance: {
              type: 'object',
              properties: {
                processing_time: { type: 'number' },
                recipes_fetched: { type: 'number' },
                cache_hits: { type: 'number' },
                batch_processing: { type: 'boolean' }
              }
            }
          }
        },
            },

• src/bar-assistant-mcp-server.ts:1829-1852 (handler)

  Primary handler function for executing the get_recipe tool. Determines if batch or single request and delegates accordingly, with error handling and performance timing.

  private async handleGetRecipe(args: GetRecipeParams) {
    const startTime = Date.now();
    
    try {
      // Determine if this is a batch request or single request
      const isBatchRequest = args.cocktail_ids || args.cocktail_names;
      const limit = Math.min(args.limit || 10, 20);
      
      if (isBatchRequest) {
        return await this.handleBatchRecipeRequest(args, startTime, limit);
      } else {
        return await this.handleSingleRecipeRequest(args, startTime);
      }
    } catch (error) {
      const errorText = `# Recipe Error\n\n` +
        `Sorry, I encountered an error while fetching recipes.\n\n` +
        `**Error:** ${error instanceof Error ? error.message : String(error)}\n\n` +
        `Please try again or contact support if the issue persists.`;
      
      return {
        content: [{ type: 'text', text: errorText }]
      };
    }
  }

• src/types.ts:237-244 (schema)

  TypeScript interface defining the input parameters for the get_recipe tool.

  export interface GetRecipeParams {
    cocktail_name?: string;
    cocktail_id?: number;
    cocktail_ids?: number[];
    cocktail_names?: string[];
    include_variations?: boolean;
    limit?: number;
  }

• src/bar-assistant-mcp-server.ts:1857-1959 (handler)

  Batch processing handler for get_recipe tool. Handles multiple cocktail requests with parallel API calls, caching, name resolution, and complete recipe formatting.

  private async handleBatchRecipeRequest(args: any, startTime: number, limit: number) {
    const cocktailRequests: Array<{id?: number, name?: string}> = [];
    
    // Collect all cocktail requests
    if (args.cocktail_ids) {
      cocktailRequests.push(...args.cocktail_ids.slice(0, limit).map((id: number) => ({ id })));
    }
    if (args.cocktail_names) {
      const remainingSlots = limit - cocktailRequests.length;
      cocktailRequests.push(...args.cocktail_names.slice(0, remainingSlots).map((name: string) => ({ name })));
    }
    
    if (cocktailRequests.length === 0) {
      return {
        content: [{
          type: 'text',
          text: `# No Cocktails Specified\n\n` +
            `Please provide cocktail_ids, cocktail_names, cocktail_id, or cocktail_name.`
        }]
      };
    }
    
    // Resolve names to IDs first (with caching)
    const resolvedCocktails: Array<{id: number, originalRequest: any}> = [];
    
    for (const request of cocktailRequests) {
      if (request.id) {
        resolvedCocktails.push({ id: request.id, originalRequest: request });
      } else if (request.name) {
        try {
          const searchResults = await this.barClient.findCocktailByName(request.name);
          if (searchResults.data.length > 0) {
            resolvedCocktails.push({ 
              id: searchResults.data[0].id, 
              originalRequest: request 
            });
          } else {
            console.warn(`Cocktail not found: ${request.name}`);
          }
        } catch (error) {
          console.warn(`Error searching for ${request.name}:`, error);
        }
      }
    }
    
    if (resolvedCocktails.length === 0) {
      return {
        content: [{
          type: 'text',
          text: `# No Cocktails Found\n\n` +
            `None of the specified cocktails could be found in the database.\n\n` +
            `**Tried:** ${cocktailRequests.map(r => r.name || `ID ${r.id}`).join(', ')}\n\n` +
            `**Suggestions:**\n` +
            `• Check spelling of cocktail names\n` +
            `• Use \`smart_search_cocktails\` to find available cocktails\n` +
            `• Verify cocktail IDs are correct`
        }]
      };
    }
    
    // Use existing batch fetching infrastructure
    const mockCocktails = resolvedCocktails.map(r => ({ id: r.id }));
    const completeRecipes = await this.fetchCompleteRecipes(mockCocktails);
    
    const processingTime = Date.now() - startTime;
    
    // Build response
    let response = `# 📖 Batch Recipe Results\n\n`;
    response += `Successfully retrieved ${completeRecipes.length} of ${cocktailRequests.length} requested recipes in ${processingTime}ms\n\n`;
    
    if (completeRecipes.length > 1) {
      response += this.formatMultipleCocktails(completeRecipes);
    } else if (completeRecipes.length === 1) {
      response += this.formatSingleRecipeDetailed(completeRecipes[0]);
    }
    
    // Add variations if requested
    if (args.include_variations && completeRecipes.length === 1) {
      try {
        const variations = await this.barClient.findSimilarCocktails(completeRecipes[0].id, 3);
        if (variations.length > 0) {
          response += `\n\n# 🔄 Similar Recipes\n\n`;
          const variationRecipes = await this.fetchCompleteRecipes(
            variations.map(v => v.cocktail)
          );
          response += this.formatMultipleCocktails(variationRecipes);
        }
      } catch (error) {
        console.warn('Failed to fetch variations:', error);
      }
    }
    
    // Add performance summary
    response += `\n\n---\n\n**⚡ Performance Summary:**\n`;
    response += `• **Total time:** ${processingTime}ms\n`;
    response += `• **Recipes fetched:** ${completeRecipes.length}\n`;
    response += `• **Cache utilization:** Enabled\n`;
    response += `• **Batch processing:** ${completeRecipes.length > 1 ? 'Used' : 'Single recipe'}`;
    
    return {
      content: [{ type: 'text', text: response }]
    };
  }

• src/bar-assistant-client.ts:115-121 (helper)

  Core API client method that fetches detailed cocktail recipe data from the Bar Assistant backend API, used by the tool handlers.

  async getCocktailRecipe(cocktailId: number): Promise<DetailedRecipe> {
    // Try different include parameters to get ingredients and instructions
    const response: AxiosResponse<{ data: DetailedRecipe }> = await this.client.get(
      `/api/cocktails/${cocktailId}?include=ingredients,instructions,tags,glass,method,images`
    );
    return response.data.data; // Extract the nested data
  }