Recipe Research MCP Server

# Recipe Research MCP Server A comprehensive Model Context Protocol (MCP) server that provides recipe search, storage, and meal planning functionality using TheMealDB API. Built with FastMCP and designed for both local development and remote deployment. ## 🚀 Features ### 🔍 Recipe Search & Discovery - Search recipes by dish name or cuisine - Find recipes starting with specific letters - Get random recipe suggestions - Detailed recipe information with ingredients, instructions, and metadata ### 📊 Recipe Management - Automatic recipe storage and indexing - Fast recipe lookup system - Recipe collection organization by cuisine/dish type - Cross-platform file handling with proper sanitization ### 🍽️ Meal Planning - Create custom meal plans from selected recipes - Save and manage multiple meal plans - Recipe collection statistics and insights ### 🎯 MCP Integration - **Tools**: Interactive recipe search and meal planning functions - **Resources**: Read-only access to recipe collections and statistics - **Prompts**: Pre-defined templates for cooking education and analysis ## 📋 Requirements - **Python**: 3.12 or higher - **Package Manager**: UV (recommended) - **Dependencies**: - `mcp[cli]>=1.15.0` - `httpx>=0.28.1` - `aiofiles>=24.1.0` ## 🛠️ Installation ### Using UV (Recommended) ```bash # Clone the repository git clone https://github.com/suraj-yadav-aiml/recipe-mcp.git cd recipe-mcp # Create and activate virtual environment uv venv # On Windows .venv\Scripts\activate # On macOS/Linux source .venv/bin/activate # Install dependencies uv sync # Test the MCP Server mcp dev recipe_server.py ``` ### Using pip ```bash # Create virtual environment python -m venv .venv # Activate virtual environment # On Windows .venv\Scripts\activate # On macOS/Linux source .venv/bin/activate # Install dependencies pip install -r requirements.txt # Test the MCP Server mcp dev recipe_server.py ``` ## 🚀 Usage ### Local Development (STDIO Transport) ```bash if __name__ == "__main__": mcp.run(transport="stdio") ``` ### Remote Deployment (HTTP Transport) ```bash if __name__ == "__main__": mcp.run(transport="streamable-http") ``` ### MCP Client Configuration #### Option 1: Remote MCP Server (Recommended) **Add to Claude Desktop as Custom Connector:** 1. Open Claude Desktop and go to **Settings** 2. Navigate to **Connectors** section 3. Click **Add Custom Connector** 4. Configure with the following details: - **Name**: `Recipe Research MCP` - **URL**: `https://recipe-mcp.onrender.com/mcp` This connects to our hosted Recipe MCP server without any local setup required. #### Option 2: Local MCP Server Add to your MCP client configuration file: ```json { "recipe_research": { "command": "uv", "args": [ "run", "--with", "mcp[cli]", "httpx", "aiofiles", "mcp", "run", "path/to/recipe_server.py" ], "cwd": "path/to/project", "env": { "PYTHONPATH": "path/to/project" } } } ``` Or for Windows: ```json { "recipe_research": { "command": "C:\\Users\\Admin\\.local\\bin\\uv.EXE", "args": [ "--directory", "path/to/project", "run", "path/to/project/recipe_server.py" ] } } ``` ## 🔧 API Reference ### Tools #### `search_recipes(dish_name: str, max_results: int = 5)` Search for recipes by dish name using TheMealDB API. **Example:** ```python # Search for pasta recipes results = await search_recipes("pasta", max_results=10) ``` #### `get_recipe_details(recipe_id: str)` Get detailed information about a specific recipe by ID. **Example:** ```python # Get details for recipe ID 52771 details = await get_recipe_details("52771") ``` #### `create_meal_plan(recipe_ids: List[str], plan_name: str = "My Meal Plan")` Create a meal plan from selected recipe IDs. **Example:** ```python # Create a meal plan plan = await create_meal_plan( ["52771", "52772", "52773"], "Italian Week" ) ``` #### `search_by_first_letter(letter: str, max_results: int = 5)` Search for recipes that start with a specific letter. **Example:** ```python # Find recipes starting with 'A' results = await search_by_first_letter("A") ``` #### `get_random_recipe()` Get a random recipe from TheMealDB. ### Resources #### `recipes://cuisines` List all available recipe collections in the database. #### `recipes://{cuisine}` Get detailed information about recipes in a specific cuisine collection. **Example:** `recipes://italian`, `recipes://pasta` #### `recipes://meal-plans` View all saved meal plans with their details. #### `recipes://stats` Get comprehensive statistics about the recipe collection. ### Prompts #### `generate_recipe_search_prompt(cuisine_type: str, num_recipes: int = 5)` Generate a comprehensive prompt for recipe search and culinary analysis. #### `generate_meal_planning_prompt(meal_type: str, people_count: int = 4, dietary_restrictions: str = "none")` Create a detailed meal planning prompt with shopping lists and preparation guides. #### `generate_cooking_lesson_prompt(skill_level: str, technique_focus: str, cuisine_style: str = "any")` Design structured cooking lessons focused on specific techniques. #### `generate_ingredient_exploration_prompt(main_ingredient: str, cooking_styles: str = "diverse", num_recipes: int = 6)` Explore recipes and techniques featuring a specific ingredient. #### `generate_cultural_cuisine_prompt(cuisine_name: str, cultural_context: str = "traditional", num_recipes: int = 5)` Explore the cultural heritage and traditions of specific cuisines. ## 📁 Data Structure ``` recipes/ ├── <dish_name>/ │ └── recipes_info.json # Recipe details by dish/cuisine ├── meal_plans/ │ └── <plan_name>.json # Saved meal plans ├── by_letter/ │ └── letter_<x>_search.json # Letter-based searches └── recipe_index.json # Master recipe index ``` ### Recipe Data Format ```json { "recipe_id": { "name": "Recipe Name", "cuisine": "Italian", "category": "Pasta", "instructions": "Step by step instructions...", "image_url": "https://...", "youtube_url": "https://...", "source_url": "https://...", "ingredients": [ { "ingredient": "Tomatoes", "measure": "400g" } ], "tags": ["Vegetarian", "Quick"] } } ``` ## 🌐 API Integration This server integrates with [TheMealDB](https://www.themealdb.com/) free API: - **Base URL**: `https://www.themealdb.com/api/json/v1/1` - **Search by name**: `/search.php?s={dish_name}` - **Search by letter**: `/search.php?f={letter}` - **Random recipe**: `/random.php` No API key required for the free tier. ## 🔧 Development ### Code Standards - **Async/Await**: All I/O operations use asyncio and aiofiles - **HTTP Requests**: Use httpx for all web requests - **Path Handling**: Use Pathlib for cross-platform compatibility - **Error Handling**: Comprehensive but not verbose - **Concurrency**: Use asyncio.gather() for parallel operations - **No Logging**: Code should not include logging statements ### File Operations - All JSON files use UTF-8 encoding with `ensure_ascii=False` - Directory creation uses `mode=0o755` for cross-platform compatibility - Filename sanitization removes invalid characters for Windows/Mac/Linux compatibility - Recipe index automatically rebuilds when stale entries are detected ## Deployment ### Local Development - Uses STDIO transport by default - Suitable for MCP client integration ### Remote Deployment - Set `PORT` environment variable - Server binds to `0.0.0.0` for external access - Uses streamable HTTP transport ## 📊 Performance Features - **Concurrent Operations**: Recipe processing uses asyncio.gather() - **Caching**: Recipe index provides fast lookups - **Lazy Loading**: Resources load data on-demand - **Cross-platform**: Handles Windows, Mac, and Linux file systems ## 📄 License This project is part of an Educational MCP server implementation. ## 🔗 Related Links - [Model Context Protocol Documentation](https://modelcontextprotocol.io/) - [FastMCP Framework](https://github.com/jlowin/fastmcp) - [TheMealDB API](https://www.themealdb.com/api.php) - [UV Package Manager](https://github.com/astral-sh/uv)