add_items_to_list

Instructions

Implementation Reference

• src/tools/addItemsToList.ts:59-115 (handler)

  The handler function that executes the tool logic: calls the API client's addItemsToList method, handles errors, and formats a success response with summary and full data.

  export async function executeAddItemsToList(
    client: SuperPrecioApiClient,
    args: {
      listId: number;
      items: Array<{
        productName: string;
        barcode?: string;
        quantity?: number;
        notes?: string;
      }>;
    }
  ) {
    const response = await client.addItemsToList(args.listId, args.items);
  
    if (!response.success) {
      return {
        content: [
          {
            type: 'text',
            text: `Failed to add items: ${response.message || 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  
    const list = response.data;
    const addedCount = response.addedItems || args.items.length;
  
    const summary = `
  ✅ Items Added Successfully!
  
  📝 List: ${list.name}
  ➕ Added: ${addedCount} ${addedCount === 1 ? 'item' : 'items'}
  🛒 Total items in list: ${list.items?.length || 0}
  
  Newly added:
  ${args.items.map((item, i) => `${i + 1}. ${item.productName} (x${item.quantity || 1})${item.notes ? ` - ${item.notes}` : ''}`).join('\n')}
  
  Your list is ready! Next steps:
  - Add more items with add_items_to_list
  - Find the best supermarket with optimize_shopping_list
  `;
  
    return {
      content: [
        {
          type: 'text',
          text: summary,
        },
        {
          type: 'text',
          text: JSON.stringify(response.data, null, 2),
        },
      ],
    };
  }

• src/tools/addItemsToList.ts:7-57 (schema)

  The tool specification defining name, description, and detailed inputSchema for listId (number) and items (array of products with productName required, optional barcode/quantity/notes).

  export const addItemsToListTool = {
    name: 'add_items_to_list',
    description: `Add products to an existing shopping list.
  
  You can add multiple items at once, each with:
  - Product name (required)
  - Barcode for exact matching (optional)
  - Quantity (default: 1)
  - Notes for specifications (optional)
  
  Perfect for building up your shopping list before optimizing.`,
    inputSchema: {
      type: 'object',
      properties: {
        listId: {
          type: 'number',
          description: 'ID of the shopping list to add items to',
        },
        items: {
          type: 'array',
          description: 'Items to add to the list',
          items: {
            type: 'object',
            properties: {
              productName: {
                type: 'string',
                description: 'Product name (e.g., "Coca Cola 2.25L", "Pan lactal")',
              },
              barcode: {
                type: 'string',
                description: 'Optional barcode/EAN for exact product matching',
              },
              quantity: {
                type: 'number',
                description: 'Quantity needed (default: 1)',
                minimum: 1,
                default: 1,
              },
              notes: {
                type: 'string',
                description: 'Optional notes (e.g., "sin sal", "integral")',
              },
            },
            required: ['productName'],
          },
          minItems: 1,
        },
      },
      required: ['listId', 'items'],
    },
  };

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

  Registration of the tool in the ListToolsRequestHandler: addItemsToListTool is included in the array of available tools.

  ✅ Items Added Successfully!
  
  📝 List: ${list.name}
  ➕ Added: ${addedCount} ${addedCount === 1 ? 'item' : 'items'}
  🛒 Total items in list: ${list.items?.length || 0}
  
  Newly added:
  ${args.items.map((item, i) => `${i + 1}. ${item.productName} (x${item.quantity || 1})${item.notes ? ` - ${item.notes}` : ''}`).join('\n')}
  
  Your list is ready! Next steps:
  - Add more items with add_items_to_list
  - Find the best supermarket with optimize_shopping_list
  `;
  
    return {
      content: [
        {
          type: 'text',
          text: summary,
        },
        {
          type: 'text',
          text: JSON.stringify(response.data, null, 2),
        },
      ],
    };
  }

• src/index.ts:147-148 (registration)

  Dispatch/execution registration in the CallToolRequestHandler switch statement.

  case 'add_items_to_list':
    return await executeAddItemsToList(apiClient, args as any);

• src/client/superPrecioApi.ts:230-245 (helper)

  Supporting API client method that performs the actual HTTP POST to /api/lists/{id}/items to add items to the list.

  async addItemsToList(
    id: number,
    items: Array<{
      productName: string;
      barcode?: string;
      quantity?: number;
      notes?: string;
    }>
  ): Promise<any> {
    try {
      const response = await this.client.post(`/api/lists/${id}/items`, { items });
      return response.data;
    } catch (error) {
      throw this.handleError(error);
    }
  }