ajayindfw/mcp-recipe-server

Recipe MCP Server - .NET 8 Implementation

A comprehensive Model Context Protocol (MCP) server implementation in .NET 8 that provides access to recipe data from TheMealDB API. This server offers a complete set of cooking-focused tools, resources, and prompts for culinary exploration and meal planning.

Features

🔧 Tools

• search_recipes: Search for recipes by dish name with customizable result limits
• get_recipe_details: Retrieve detailed information about specific recipes by ID
• create_meal_plan: Generate organized meal plans from selected recipes
• search_by_first_letter: Find recipes starting with a specific letter
• get_random_recipe: Discover random recipes for inspiration
• test_filesystem: Verify filesystem operations and permissions
• get_system_info: Display system and environment information

📚 Resources

• recipes://cuisines: Browse all available recipe collections
• recipes://meal-plans: Access saved meal plans
• recipes://stats: View comprehensive recipe statistics
• recipes://{cuisine}: Explore specific cuisine collections

💡 Prompts

• generate_recipe_search_prompt: Create cuisine exploration prompts
• generate_meal_planning_prompt: Generate comprehensive meal planning guides
• generate_cooking_lesson_prompt: Design structured cooking lessons
• generate_ingredient_exploration_prompt: Create ingredient-focused analysis prompts
• generate_cultural_cuisine_prompt: Generate cultural cuisine exploration prompts

Prerequisites

• .NET 8.0 SDK or later
• Internet connection for TheMealDB API access

Installation & Setup

1. Clone or Download

# If cloning from a repository
git clone <repository-url>
cd mcp-recipe-final

# Or download and extract the source files

2. Restore Dependencies

dotnet restore

3. Build the Application

dotnet build

4. Configuration (Optional)

Edit appsettings.json to customize settings:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  },
  "Server": {
    "Host": "0.0.0.0",
    "Port": 8000
  },
  "RecipeService": {
    "ApiBaseUrl": "https://www.themealdb.com/api/json/v1/1",
    "RequestTimeoutSeconds": 10
  }
}

Usage

Command Line Options

dotnet run -- [options]

Options:
  --port <port>         Port to run the server on (default: 8000)
  --host <host>         Host to bind the server to (default: 0.0.0.0)
  --transport <method>  Transport method - stdio or http (default: stdio)
  --help               Show help information

Running the Server

📡 STDIO Mode (Local MCP Clients)

dotnet run -- --transport stdio

Default mode for VS Code and local MCP clients.

🌐 HTTP Mode (Web/Remote Clients)

dotnet run -- --transport http --port 8080 --host localhost

Enables HTTP API for remote access and web clients.

🚀 Render Cloud Deployment

1. Push code to GitHub
2. Connect repository to Render
3. Render auto-deploys using render.yaml and Dockerfile
4. Access at: https://your-app.onrender.com/mcp

🐳 Docker Deployment

docker build -t recipe-mcp-server .
docker run -p 8080:8080 recipe-mcp-server

HTTP Endpoints (when using --transport http)

• POST /mcp - Main MCP protocol endpoint
• GET /health - Health check
• GET / - Server information

Example Usage

Search for Recipes

# Search for Italian recipes
search_recipes("pasta", 5)

# Get specific recipe details
get_recipe_details("52771")

Create Meal Plans

create_meal_plan(["52771", "52772", "52773"], "Weekly Italian Menu")

Explore Resources

# View all available cuisines
recipes://cuisines

# Explore Italian recipes
recipes://italian

# Check meal plans
recipes://meal-plans

Project Structure

RecipeServer/
├── Models/
│   ├── Mcp/                    # MCP protocol models
│   │   └── McpModels.cs
│   └── Recipe/                 # Recipe data models
│       └── RecipeModels.cs
├── Services/
│   ├── Interfaces/
│   │   └── IServices.cs        # Service interface definitions
│   ├── McpServer.cs           # Core MCP message handling
│   ├── RecipeApiService.cs    # TheMealDB API integration
│   ├── ToolService.cs         # MCP tools implementation
│   ├── ResourceService.cs     # MCP resources implementation
│   └── PromptService.cs       # MCP prompts implementation
├── .vscode/                   # VS Code configuration
│   ├── launch.json           # Debug configurations
│   └── tasks.json            # Build tasks
├── Program.cs                 # Application entry point
├── appsettings.json          # Configuration file
├── RecipeServer.csproj       # Project file
├── build.sh                  # Build script
└── README.md                 # This documentation

Data Storage

The server automatically creates a recipes/ directory to store:

• Recipe Collections: Organized by cuisine/dish type
• Meal Plans: Saved meal planning data
• Search Results: Cached search results by letter

Directory structure example:

recipes/
├── italian/
│   └── recipes_info.json
├── pasta/
│   └── recipes_info.json
├── meal_plans/
│   ├── weekly_italian_menu.json
│   └── dinner_ideas.json
└── by_letter/
    └── letter_a_search.json

API Integration

This server integrates with TheMealDB API:

• Search by name: /search.php?s={dish_name}
• Search by first letter: /search.php?f={letter}
• Random recipe: /random.php
• Recipe by ID: /lookup.php?i={recipe_id}

Development

Adding New Tools

1. Define the tool schema in ToolService.GetToolsListAsync()
2. Implement the tool logic in ToolService.CallToolAsync()
3. Add any required helper methods

Adding New Resources

1. Add resource definition in ResourceService.GetResourcesListAsync()
2. Implement resource reading logic in ResourceService.ReadResourceAsync()

Adding New Prompts

1. Define prompt schema in PromptService.GetPromptsListAsync()
2. Implement prompt generation in PromptService.GetPromptAsync()

Error Handling

The server includes comprehensive error handling:

• Network failures: Graceful API timeout handling
• File system errors: Permission and access error management
• JSON parsing: Malformed data protection
• MCP protocol: Standards-compliant error responses

Logging

Structured logging is configured through appsettings.json:

• Information: General operation logs
• Warning: Non-critical issues
• Error: Exception and failure logs

Performance Considerations

• Async/await: All I/O operations are asynchronous
• HTTP client reuse: Shared HttpClient instance
• File caching: Search results cached locally
• Memory efficiency: Streaming JSON processing where possible

Compatibility

.NET Versions

• Primary: .NET 8.0
• Compatible: .NET 6.0+ (with minor modifications)

Operating Systems

• Windows: Full support
• macOS: Full support
• Linux: Full support

MCP Clients

• Compatible with any MCP 2024-11-05 protocol client
• Tested with Claude Desktop and other MCP-compatible applications

Troubleshooting

Common Issues

"Permission denied" errors

# Ensure write permissions for recipes directory
chmod 755 recipes/

"Network timeout" errors

• Check internet connectivity
• Verify TheMealDB API availability
• Adjust timeout in appsettings.json

"Port already in use"

# Use a different port
dotnet run -- --port 8001

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• TheMealDB Integration: Comprehensive recipe database with local caching
• TheMealDB: Free recipe database API
• Model Context Protocol: Anthropic's MCP specification
• .NET Community: Framework and ecosystem support