README.md

---
title: FoodWise Remote MCP
emoji: 🥗
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
hf_oauth: false
---

# FoodWise

A smart food management system with recipe organization and meal planning, designed for detailed inventory tracking.

## Core Concepts

FoodWise is built around a detailed data model to track food items across different storage areas: the pantry, refrigerator, and freezer. The goal is to provide a clear, organized overview of your food inventory to reduce waste and improve meal planning.

### Key Features

-   **Pantry Tracking**: Keep a detailed inventory of your pantry items, including purchase and best-by dates, location, and whether a package has been opened.
-   **Refrigerator Tracking**: Manage refrigerated items with attention to food safety, including temperature zones and sensitivity flags.
-   **Freezer Tracking**: A detailed system for your multi-drawer freezer, tracking freeze dates, cooked/raw status, and preparation notes.
-   **Notion Integration**: Seamlessly sync your food inventory with a Notion database for ultimate organization.
-   **LangGraph Agent**: Conversational AI agent for natural language inventory management using LangGraph's React agent framework.
-   **Discord Bot Ready**: Architecture designed for Discord integration (future implementation).

## Development Setup

This project uses `uv` for fast and efficient package and virtual environment management.

### Prerequisites

-   Python 3.12+
-   `uv` package manager

### Installation

1.  **Clone the repository:**
    ```bash
    git clone https://github.com/your-username/FoodWise.git
    cd FoodWise
    ```

2.  **Create and activate the virtual environment:**
    ```bash
    uv venv
    source .venv/bin/activate
    ```

3.  **Install dependencies:**
    ```bash
    uv pip install -e ".[dev]"
    ```

This command installs the project in editable mode (`-e`) along with all main and development dependencies.

### Notion Integration Setup

4.  **Create a Notion integration:**
    - Visit [Notion Integrations](https://www.notion.so/my-integrations)
    - Create a new integration and copy the "Internal Integration Token"
    - Share your food inventory database with the integration

5.  **Configure environment variables:**
    ```bash
    cp env.example .env  # or create .env file
    ```
    Add your credentials to `.env`:
    ```
    NOTION_SECRET=your_notion_integration_token
    NOTION_INVENTORY_DB_ID=your_inventory_database_id
    NOTION_SHOPPING_DB_ID=your_shopping_database_id  # NEW! For shopping lists
    OPENAI_API_KEY=your_openai_key  # for LangGraph agent
    
    # MCP Server Configuration (for FastMCP implementation)
    MCP_TRANSPORT=stdio
    MCP_SERVER_NAME=FoodWise
    ```

6.  **Verify setup:**
    ```bash
    # Discover your Notion databases
    python scripts/list_databases.py
    
    # Verify schema compatibility  
    python scripts/verify_schema.py
    
# Inventory demo (uses TEST DB if provided, auto-cleanup)
python scripts/inventory_demo.py
    
# Shopping list demo (uses TEST DB if provided)
python scripts/shopping_list_demo.py
    ```

## Quick Start

### Test the Notion Integration
```bash
# Activate virtual environment
source .venv/bin/activate

# Run database verification
python scripts/verify_schema.py

# Test inventory CRUD (Create, Read, Update, Delete)
python scripts/inventory_demo.py

# Run comprehensive unit tests
python -m pytest tests/ -v
```

### Use the LangGraph Agent
```python
from src.foodwise.agent.agent import run_agent_query

# Query your inventory
response = run_agent_query("What items are expiring soon?")
print(response)

# Add new items
response = run_agent_query("Add 2 lbs of ground beef to the refrigerator")
print(response)

# Update existing items
response = run_agent_query("Update the milk quantity to 1 gallon")
print(response)

# Search for specific items
response = run_agent_query("Search for apples in my inventory")
print(response)
```

### Test the Agent Locally
```bash
# Quick agent functionality test
python scripts/agent_smoke.py
```

### Use with Claude Desktop (MCP) ✅ WORKING

#### Local MCP Server
```bash
# The FastMCP server runs automatically via Claude Desktop configuration
# Just update ~/.config/claude/claude_desktop_config.json with:

{
  "mcpServers": {
    "foodwise": {
      "command": "/path/to/FoodWise/.venv/bin/python",
      "args": ["/path/to/FoodWise/mcp_server_entry.py"],
      "cwd": "/path/to/FoodWise"
    }
  }
}
```

#### Remote MCP Server ✅ NEW!
```bash
# Access the remote FoodWise MCP server deployed on HuggingFace Spaces
# Add this to your ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "foodwise-remote": {
      "command": "npx",
      "args": ["supergateway", "--streamableHttp", "https://leowalker-foodwise-remote-mcp.hf.space/mcp/"]
    }
  }
}
```

**🌐 Remote Access**: The FoodWise MCP server is now available as a cloud service! Use the remote server for:
- ✅ Access from multiple devices
- ✅ No local setup required
- ✅ Always up-to-date
- ✅ Shared inventory access (when using shared Notion databases)

**💡 Tip**: You can have both `foodwise` (local) and `foodwise-remote` configured simultaneously for maximum flexibility!

```bash
# In Claude Desktop, you'll now have access to:
# 🔧 Tools: 12 total (5 inventory + 7 shopping management)
# 📂 Resources: 4 focused (inventory items, expiring items, shopping list, by-store)
# 📝 Prompts: 5 concise (add_item_helper, meal_planning_assistant, expiration_manager,
#                        shopping_list_optimizer, smart_shopping_assistant)
```

**✅ Production Ready**: Complete MCP integration tested and working with Claude Desktop. Both local and remote servers automatically load environment configurations and provide full functionality.

## Development Status

**🎯 Current Status:** ✅ STREAMLINED! Clean, focused MCP server optimized for learning and production use!
**✅ Completed Features:**
- Complete Notion integration with full CRUD (Create, Read, Update, Delete) for **inventory & shopping**
- LangGraph React agent with 5 inventory management tools
- **Streamlined shopping list management system** 🛒 OPTIMIZED!
- **Store-specific optimization** for Costco, Trader Joe's, Safeway, Whole Foods, Target
- Pydantic validation for data integrity and partial updates
- Comprehensive testing suite (manual + automated)
- Schema compatibility verification
- **FastMCP server with secure environment handling**
- **Claude Desktop integration tested and working**
- **Clean, focused MCP architecture (42% code reduction!)**
- **🌐 Remote MCP Server deployed on HuggingFace Spaces** ✅ NEW!
- **Docker containerization with uv and Python 3.12**

**🔧 Available Tools (Working in Claude Desktop):**

*Inventory Management:*
- `get_inventory` - Query inventory with filtering options ✅ Tested
- `add_inventory_item` - Add new food items with full field support  
- `search_inventory_items` - Search for specific items by name/category
- `update_inventory_item` - Update existing items with validation ✅ Tested
- `remove_inventory_item` - Archive/remove items from inventory ✅ Tested

*Shopping List Management:* 🛒 **STREAMLINED!**
- `get_shopping_list` - Retrieve shopping items with store/priority filtering
- `add_shopping_item` - Add items with store preferences and pricing
- `update_shopping_item` - Modify items and track purchase status
- `remove_shopping_item` - Archive completed shopping items
- `create_shopping_from_recipe` - Generate shopping lists from recipes
- `optimize_shopping_by_store` - Organize by store for efficient shopping
- `move_purchased_to_inventory` - Auto-move purchased items to inventory

**📋 Streamlined MCP Architecture:**
- ✅ FastMCP server with **12 essential tools** (5 inventory + 7 shopping)
- ✅ **4 focused resources** for live data (2 inventory + 2 shopping)
- ✅ **5 concise prompts** for key workflows (mixed domains)
- ✅ **42% code reduction** while maintaining full functionality
- ✅ Claude Desktop integration working and tested
- ✅ Secure environment variable handling (no secrets in config files)
- ✅ Full inventory + shopping management through conversational AI
- ✅ **Store-specific optimization** (Costco, Trader Joe's, Safeway, Whole Foods, Target)
- ✅ **Clean, learning-focused design** - perfect for understanding MCP patterns

**🚀 Ready for:**
- Enhanced documentation and deployment guides
- Additional MCP client integrations (OpenAI, LiteLLM, etc.)
- Discord bot implementation (architecture ready)

---
*Last updated: August 2025 - Remote MCP deployment optimized and simplified*