MCPizza - Enhanced

# 🍕 MCPizza - Enhanced An educational MCP (Model Context Protocol) server demonstrating AI-powered pizza ordering with Domino's API integration. > **⚠️ Important**: This project is for **educational purposes only**. While it integrates with Domino's real API, actual order placement is blocked by CAPTCHA requirements. See [Limitations](#limitations) for details. ## Credits This project is based on [GrahamMcBain/mcpizza](https://github.com/GrahamMcBain/mcpizza), with significant enhancements: ### Original Project - **Author**: Graham McBain - **Purpose**: Educational MCP protocol demonstration - **Design**: Safe-mode ordering without real placement ### Our Enhancements - ✅ **Real API Integration** - Actually calls Domino's pricing and validation APIs - ✅ **Pizza Customization** - `add_pizza_with_toppings` tool for proper coupon + topping configuration - ✅ **Interaction Logging** - Complete 2-way logging system for all MCP interactions - ✅ **Coupon Discovery** - `get_coupons` and `get_ordering_guidance` tools - ✅ **Enhanced Error Handling** - Detailed error reporting and validation - ✅ **Comprehensive Documentation** - WORKFLOW.md with step-by-step instructions ## What This Project Demonstrates 1. **MCP Protocol Integration** - Full implementation of Model Context Protocol 2. **Real-world API Interaction** - Integration with Domino's unofficial API 3. **Complex Tool Orchestration** - 12 tools working together for multi-step workflows 4. **State Management** - Order state management across tool calls 5. **Error Handling** - Graceful handling of API validation and errors ## Features ### Store & Menu Tools - 📍 `find_stores` - Find nearby Domino's by address or zip - 🏪 `get_store_info` - Detailed store information and hours - 📋 `get_menu` - Complete menu with categories - 🔍 `search_menu` - Search for specific items - 🎉 `get_coupons` - Discover available deals and coupons ### Ordering Tools - 📝 `create_order` - Initialize a new order - 🍕 `add_pizza_with_toppings` - Add customized pizzas with toppings (NEW!) - ➕ `add_item_to_order` - Add any menu item - 👁️ `view_order` - Preview order details and pricing - 🗑️ `clear_order` - Clear current order - 💳 `place_order` - Attempt to place order (blocked by CAPTCHA) ### Guidance Tools - 🎯 `get_ordering_guidance` - AI-powered deal recommendations (NEW!) ## Installation ### Prerequisites - Python 3.10+ - [uv](https://github.com/astral-sh/uv) package manager ### Setup ```bash # Clone the repository git clone https://github.com/dshanklin-bv/mcp-pizza.git cd mcp-pizza # Install dependencies uv pip install -e . ``` ### Claude Desktop Integration Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "pizza": { "command": "uv", "args": [ "--directory", "/path/to/mcp-pizza", "run", "mcpizza" ] } } } ``` ## Usage See [WORKFLOW.md](WORKFLOW.md) for complete ordering workflow documentation. ### Basic Example ``` 1. Find stores: "find pizza stores near 76104" 2. Get coupons: "what deals are available at store 8022?" 3. Get guidance: "I want a deep dish sausage and pepperoni pizza" 4. Create order: Create order with your details 5. Add pizza: Use add_pizza_with_toppings with coupon code 6. View order: Review pricing and details 7. (Optional) Place order: Will be blocked by CAPTCHA ``` ## Architecture The codebase follows a clean, modular architecture with separation of concerns: ``` mcp-pizza/ ├── mcpizza/ │ ├── server.py # Main MCP server (303 lines, down from 1308!) │ ├── logger.py # Interaction logging system │ ├── __main__.py # Entry point │ │ │ ├── models/ # Pydantic parameter models │ │ └── params.py # Tool parameter definitions │ │ │ ├── services/ # Business logic layer │ │ ├── store_service.py # Store lookup & menu browsing │ │ ├── order_service.py # Order creation & management │ │ ├── payment_service.py # Payment processing │ │ └── guidance_service.py # AI ordering guidance │ │ │ ├── tools/ # MCP tool handlers │ │ ├── store_tools.py # Store-related tools │ │ ├── menu_tools.py # Menu-related tools │ │ ├── order_tools.py # Order-related tools │ │ └── guidance_tools.py # Guidance tools │ │ │ ├── api/ # Domino's API client │ │ ├── endpoints.py # API endpoint constants │ │ └── client.py # HTTP client wrapper │ │ │ └── utils/ # Utilities │ └── mock_order.py # Mock order object creation │ ├── tests/ # Comprehensive test suite (18 tests) │ ├── test_models.py # Model validation tests │ ├── test_utils.py # Utility function tests │ ├── test_api_client.py # API client tests │ └── test_services.py # Service layer tests │ ├── examples/ # Example scripts │ └── test_mcp_with_ollama.py # Autonomous testing │ ├── logs/ # Interaction logs (gitignored) ├── WORKFLOW.md # Complete workflow documentation └── README.md # This file ``` ### Benefits of This Architecture 1. **Maintainability**: Each module has a single responsibility 2. **Testability**: Services and utilities are easily unit tested 3. **Readability**: Clear separation between MCP layer, business logic, and API calls 4. **Scalability**: Easy to add new tools or services 5. **Reusability**: Services can be reused outside of MCP context ## Logging All MCP interactions are automatically logged to `logs/interactions_YYYYMMDD.log`: - Tool calls with full arguments - Tool responses with previews - State changes (order creation, items added) - Errors with context Log format is JSON for easy parsing and analysis. ## Limitations ### CAPTCHA Requirement Domino's API requires CAPTCHA verification for order placement. Our system successfully: - ✅ Validates pizza configurations - ✅ Prices orders correctly (e.g., $11.90 for medium 2-topping) - ✅ Accepts payment structure - ❌ **Cannot submit final order** (blocked by `recaptchaVerificationRequired`) This is an intentional fraud prevention measure by Domino's and **cannot be bypassed** without violating their terms of service. ### What Works - Store lookup and menu browsing - Coupon discovery and deal analysis - Order validation and pricing - Complete order preparation - All MCP protocol features ### What Doesn't Work - Final order submission (CAPTCHA required) - Real payment processing ## Development ### Testing ```bash # Run autonomous test suite (tests all tools except order placement) python test_mcp_with_ollama.py ``` ### Contributing This is an educational project demonstrating MCP protocol integration. Contributions that enhance the educational value are welcome! ## Technical Details - **MCP SDK**: Official Model Context Protocol SDK - **API Library**: pizzapi (unofficial Domino's API wrapper) - **Order Structure**: Mock order object with real API calls - **Validation**: Multi-step validation (structure → pricing → placement) ## Disclaimer ⚠️ **Educational Use Only** This project is for learning about: - Model Context Protocol implementation - Real-world API integration - Multi-tool orchestration - State management in AI assistants **Do not use for actual pizza ordering.** Use Domino's official website or mobile app instead. ## License MIT License Based on [GrahamMcBain/mcpizza](https://github.com/GrahamMcBain/mcpizza) (MIT License) ## Acknowledgments - **Graham McBain** - Original mcpizza project and MCP implementation - **pizzapi contributors** - Unofficial Domino's API wrapper - **Anthropic** - Model Context Protocol specification --- Built with Claude Code 🤖