create_shopping_list

Instructions

Implementation Reference

• src/tools/createShoppingList.ts:66-128 (handler)

  The executeCreateShoppingList function is the main handler that executes the tool's logic: validates inputs implicitly via types, calls the API client's createShoppingList method, handles success/error responses, formats a user-friendly summary, and returns structured content.

  export async function executeCreateShoppingList(
    client: SuperPrecioApiClient,
    args: {
      name: string;
      description?: string;
      userId?: number;
      items?: Array<{
        productName: string;
        barcode?: string;
        quantity?: number;
        notes?: string;
      }>;
    }
  ) {
    const response = await client.createShoppingList(args);
  
    if (!response.success) {
      return {
        content: [
          {
            type: 'text',
            text: `Failed to create shopping list: ${response.message || 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  
    const list = response.data;
    const itemCount = list.items?.length || 0;
  
    const summary = `
  ✅ Shopping List Created Successfully!
  
  📝 Name: ${list.name}
  ${list.description ? `📄 Description: ${list.description}` : ''}
  🆔 List ID: ${list.id}
  🛒 Items: ${itemCount} ${itemCount === 1 ? 'item' : 'items'}
  📅 Created: ${new Date(list.createdAt).toLocaleDateString('es-AR')}
  
  ${itemCount > 0 ? `
  Items in list:
  ${list.items.map((item: any, i: number) => `${i + 1}. ${item.productName} (x${item.quantity})`).join('\n')}
  ` : 'No items yet. Use add_items_to_list to add products.'}
  
  Next steps:
  - Use add_items_to_list to add more products
  - Use optimize_shopping_list to find the best supermarket for this list
  `;
  
    return {
      content: [
        {
          type: 'text',
          text: summary,
        },
        {
          type: 'text',
          text: JSON.stringify(response.data, null, 2),
        },
      ],
    };
  }

• src/tools/createShoppingList.ts:7-64 (schema)

  The createShoppingListTool object defines the tool schema, including name 'create_shopping_list', detailed description, and inputSchema with properties for name (required), description, userId, and items array (with productName required per item). This is used for MCP tool listing and input validation.

  export const createShoppingListTool = {
    name: 'create_shopping_list',
    description: `Create a new shopping list to organize your purchases.
  
  You can create an empty list and add items later, or create a list with items right away.
  This is useful for planning your shopping and then optimizing which supermarket to buy from.
  
  Features:
  - Create named lists (e.g., "Weekly groceries", "Party supplies")
  - Add optional description
  - Include initial items with quantities
  - Link to user ID (optional)`,
    inputSchema: {
      type: 'object',
      properties: {
        name: {
          type: 'string',
          description: 'Name of the shopping list (e.g., "Weekly groceries", "Monthly shopping")',
        },
        description: {
          type: 'string',
          description: 'Optional description of what this list is for',
        },
        userId: {
          type: 'number',
          description: 'Optional user ID to associate this list with',
        },
        items: {
          type: 'array',
          description: 'Optional initial items to add to the list',
          items: {
            type: 'object',
            properties: {
              productName: {
                type: 'string',
                description: 'Product name (e.g., "Leche descremada", "Arroz integral")',
              },
              barcode: {
                type: 'string',
                description: 'Optional product barcode/EAN for exact matching',
              },
              quantity: {
                type: 'number',
                description: 'Quantity needed (default: 1)',
                minimum: 1,
              },
              notes: {
                type: 'string',
                description: 'Optional notes (e.g., "1 liter", "2kg bag")',
              },
            },
            required: ['productName'],
          },
        },
      },
      required: ['name'],
    },
  };

• src/index.ts:89-116 (registration)

  The tool is registered in the MCP server's ListToolsRequestSchema handler by including createShoppingListTool in the returned tools array (specifically at line 101).

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        // V1 Tools
        searchProductsTool,
        searchByCodeTool,
        comparePriceTool,
        getBestDealsTool,
        sendNotificationTool,
        subscribeDeviceTool,
  
        // V2 Tools - Shopping Lists
        createShoppingListTool,
        addItemsToListTool,
        getShoppingListsTool,
        optimizeShoppingListTool,
        removeShoppingListTool,
  
        // V2 Tools - Price Alerts
        setPriceAlertTool,
        getMyAlertsTool,
        removePriceAlertTool,
  
        // V2 Tools - Location
        findNearbySupermarketsTool,
      ],
    };
  });

• src/index.ts:119-187 (registration)

  The tool execution handler is registered in the MCP server's CallToolRequestSchema via a switch statement that dispatches 'create_shopping_list' calls to executeCreateShoppingList (lines 144-145).

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
  
    try {
      switch (name) {
        // V1 Tools
        case 'search_products':
          return await executeSearchProducts(apiClient, args as any);
  
        case 'search_by_code':
          return await executeSearchByCode(apiClient, args as any);
  
        case 'compare_prices':
          return await executeComparePrice(apiClient, args as any);
  
        case 'get_best_deals':
          return await executeGetBestDeals(apiClient, args as any);
  
        case 'send_notification':
          return await executeSendNotification(apiClient, args as any);
  
        case 'subscribe_device':
          return await executeSubscribeDevice(apiClient, args as any);
  
        // V2 Tools - Shopping Lists
        case 'create_shopping_list':
          return await executeCreateShoppingList(apiClient, args as any);
  
        case 'add_items_to_list':
          return await executeAddItemsToList(apiClient, args as any);
  
        case 'get_shopping_lists':
          return await executeGetShoppingLists(apiClient, args as any);
  
        case 'optimize_shopping_list':
          return await executeOptimizeShoppingList(apiClient, args as any);
  
        case 'remove_shopping_list':
          return await executeRemoveShoppingList(apiClient, args as any);
  
        // V2 Tools - Price Alerts
        case 'set_price_alert':
          return await executeSetPriceAlert(apiClient, args as any);
  
        case 'get_my_alerts':
          return await executeGetMyAlerts(apiClient, args as any);
  
        case 'remove_price_alert':
          return await executeRemovePriceAlert(apiClient, args as any);
  
        // V2 Tools - Location
        case 'find_nearby_supermarkets':
          return await executeFindNearbySupermarkets(apiClient, args as any);
  
        default:
          throw new Error(`Unknown tool: ${name}`);
      }
    } catch (error: any) {
      return {
        content: [
          {
            type: 'text',
            text: `Error executing tool ${name}: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  });