planning/archive/shopping_list_setup.md

Shopping List Setup & Testing Guide 🛒 (Archived)

This document has been archived. The shopping list tools, resources, and prompts are implemented and reflected in the main documentation.

See active docs in src/foodwise/mcp_server/README.md and top-level README.md for current usage.

---

Shopping List Setup & Testing Guide 🛒

🎯 What We Built

Your FoodWise MCP server now includes comprehensive shopping list management with:

🔧 7 New Tools:

• get_shopping_list - Retrieve items with filtering (store, priority, status)
• add_shopping_item - Add new items with store preferences and pricing
• update_shopping_item - Modify existing items and track purchase status
• remove_shopping_item - Archive completed items
• create_shopping_from_recipe - Generate shopping lists from recipe ingredients
• optimize_shopping_by_store - Organize shopping by store for efficient trips
• move_purchased_to_inventory - Move bought items to inventory automatically

📂 2 New Resources:

• shopping://list - Current shopping list overview with organization by status and counts
• shopping://by-store - Items organized by preferred store with unassigned items and estimated totals per store

📝 2 New Prompts:

• shopping_list_optimizer - Optimize shopping routes and store strategies
• smart_shopping_assistant - Intelligent list building with duplicate prevention

📋 Step 1: Create Notion Shopping Database

Required Database Properties:

1. Item Name (Title) - Primary identifier
2. Quantity (Number) - Amount needed
3. Unit (Text) - Measurement (lbs, gallons, pieces, etc.)
4. Store (Select) with options:
   • Costco
   • Trader Joe's
   • Safeway
   • Whole Foods
   • Target
5. Priority (Select) with options:
   • Essential
   • Nice to Have
   • Stock Up
6. Status (Select) with options:
   • Needed
   • Purchased
   • Skipped
7. Category (Select) with options:
   • Produce
   • Dairy
   • Meat
   • Pantry
   • Beverages
   • Snacks
   • Household

Optional Properties (Recommended):

8. Estimated Price (Number) - For budget tracking
9. Brand Preference (Text) - Specific brand requests
10. Size/Package (Text) - Package details (24-pack, organic, etc.)
11. Notes (Text) - Additional shopping notes
12. Recipe Source (Text) - Which recipe needs this ingredient
13. Date Added (Date) - Auto-populated when created

🔧 Step 2: Environment Configuration

Add to your .env file:

# Existing inventory database
NOTION_INVENTORY_DB_ID=your_inventory_database_id

# New shopping list database
NOTION_SHOPPING_DB_ID=your_shopping_database_id

🧪 Step 3: Test Shopping List Integration

Run the Test Script:

# Test shopping list operations
python scripts/test_shopping_list.py

This will:

• Add sample shopping items to different stores
• Test filtering and querying
• Verify store-specific organization
• Calculate budget estimates

Test MCP Server:

# Start the MCP server
uv run python -m foodwise.mcp_server

# Or with debug logging
MCP_LOG_LEVEL=DEBUG uv run python -m foodwise.mcp_server

🖥 Step 4: Claude Desktop Integration

Your existing Claude Desktop config should work automatically! The shopping tools will appear alongside your inventory tools.

Available in Claude Desktop:

Shopping Tools:

• Add items: "Add milk to my shopping list for Whole Foods"
• Organize by store: "Show me my shopping list organized by store"
• Budget tracking: "What's my estimated shopping cost by store?"
• Recipe integration: "Create shopping list for chicken stir-fry recipe"

Shopping Resources:

• shopping://list - Live view of all shopping items organized by status
• shopping://by-store - Live store organization with estimated totals

Shopping Prompts:

• "Use the shopping_list_optimizer prompt to plan my shopping trip"
• "Use the smart_shopping_assistant to avoid buying duplicates"

🎯 Usage Examples

Add Items to Shopping List:

"Add the following to my shopping list:
- 2 lbs ground beef for Costco 
- Organic spinach for Whole Foods
- TJ's seasonal soup for Trader Joe's"

Optimize Shopping Trip:

"Use the shopping_list_optimizer prompt to plan my most efficient 
shopping route across Costco, Trader Joe's, and Whole Foods"

Check Budget:

"Use the shopping://by-store resource or the optimize_shopping_by_store tool to show my estimated
shopping costs by store and priority"

Move Purchased Items:

"I bought milk, bread, and eggs. Move these from my shopping list 
to my inventory and mark them as purchased today"

🚨 Troubleshooting

Common Issues:

1. "NOTION_SHOPPING_DB_ID not set"

   • Add the shopping database ID to your .env file
   • Restart the MCP server

2. "Failed to query shopping list"

   • Verify your Notion integration has access to the shopping database
   • Check database property names match the schema

3. "Shopping tools not appearing in Claude"

   • Restart Claude Desktop
   • Check MCP server logs: tail -f ~/Library/Logs/Claude/mcp-server-foodwise.log

Debug Commands:

# Check if shopping database is accessible
python scripts/test_shopping_list.py

# Test MCP server registration
uv run fastmcp dev src/foodwise/mcp_server/main.py

# Monitor logs in real-time
tail -f ~/Library/Logs/Claude/mcp-server-foodwise.log

🎉 Success Indicators

You'll know it's working when:

• ✅ Test script adds items successfully
• ✅ MCP server starts without errors
• ✅ Shopping tools appear in Claude Desktop
• ✅ Store-specific organization works
• ✅ Budget tracking calculates correctly

🚀 Next Steps

Once shopping lists are working:

1. Create sample shopping items for testing
2. Test store optimization features
3. Try recipe-to-shopping workflows
4. Move to recipes database implementation

---

The shopping list system is designed to work seamlessly with your existing inventory management, creating a complete food management ecosystem!