🍕 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_toppingstool for proper coupon + topping configuration - ✅ Interaction Logging - Complete 2-way logging system for all MCP interactions
- ✅ Coupon Discovery -
get_couponsandget_ordering_guidancetools - ✅ Enhanced Error Handling - Detailed error reporting and validation
- ✅ Comprehensive Documentation - WORKFLOW.md with step-by-step instructions
What This Project Demonstrates
- MCP Protocol Integration - Full implementation of Model Context Protocol
- Real-world API Interaction - Integration with Domino's unofficial API
- Complex Tool Orchestration - 12 tools working together for multi-step workflows
- State Management - Order state management across tool calls
- 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.py # Autonomous testing
│
├── logs/ # Interaction logs (gitignored)
├── WORKFLOW.md # Complete workflow documentation
└── README.md # This file
Benefits of This Architecture
- Maintainability: Each module has a single responsibility
- Testability: Services and utilities are easily unit tested
- Readability: Clear separation between MCP layer, business logic, and API calls
- Scalability: Easy to add new tools or services
- 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
# 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 (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 🤖