MCPizza - Enhanced MCP Server

🍕 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 for details.

Credits

This project is based on 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 package manager

Setup

# 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:

{
  "mcpServers": {
    "pizza": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-pizza",
        "run",
        "mcpizza"
      ]
    }
  }
}

Usage

See 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.p