usage.md•6.06 kB
# Open Food Facts MCP Server Usage Examples
This document provides practical examples of how to use the Open Food Facts MCP server tools.
## Product Lookup Examples
### Basic Product Information
```json
{
"tool": "get_product",
"arguments": {
"barcode": "3017620422003"
}
}
```
**Response Example:**
```
**Nutella**
Brand: Ferrero
Quantity: 400g
Categories: Sweet spreads, Chocolate spreads
**Scores:**
Nutri-Score: E | NOVA Group: 4 | Eco-Score: D
**Ingredients:**
Sugar, palm oil, hazelnuts (13%), skimmed milk powder (8.7%), fat-reduced cocoa (7.4%), emulsifier: lecithins (soya), vanillin.
**Nutrition (per 100g):**
Energy: 539 kcal | Fat: 30.9g | Carbs: 57.5g | Sugars: 56.3g | Protein: 6.3g | Salt: 0.107g
```
## Search Examples
### Search by Category
```json
{
"tool": "search_products",
"arguments": {
"categories": "yogurts",
"nutrition_grades": "a,b",
"page_size": 5
}
}
```
### Search with Multiple Filters
```json
{
"tool": "search_products",
"arguments": {
"search": "organic",
"categories": "breakfast-cereals",
"brands": "nature valley",
"nutrition_grades": "a,b,c",
"sort_by": "popularity"
}
}
```
### Search by Brand
```json
{
"tool": "search_products",
"arguments": {
"brands": "ben jerry",
"categories": "ice-creams",
"page": 1,
"page_size": 10
}
}
```
## Nutritional Analysis Examples
### Detailed Analysis
```json
{
"tool": "analyze_product",
"arguments": {
"barcode": "3017620422003"
}
}
```
**Response Example:**
```
**Nutritional Analysis: Nutella**
**Scores:**
• Nutri-Score E: Very poor nutritional quality
• NOVA Group 4: Ultra-processed foods
• Eco-Score D: High environmental impact
**Nutritional Breakdown:**
• Energy: 539 kcal (high)
• Fat: 30.9g (high)
• Sugars: 56.3g (high)
• Salt: 0.107g (low)
```
## Product Comparison Examples
### Nutrition Comparison
```json
{
"tool": "compare_products",
"arguments": {
"barcodes": ["3017620422003", "8712566453627", "4056489314592"],
"focus": "nutrition"
}
}
```
### Environmental Comparison
```json
{
"tool": "compare_products",
"arguments": {
"barcodes": ["3017620422003", "8712566453627"],
"focus": "environmental"
}
}
```
### Processing Level Comparison
```json
{
"tool": "compare_products",
"arguments": {
"barcodes": ["3017620422003", "8712566453627"],
"focus": "processing"
}
}
```
## Product Suggestions Examples
### Healthy Snack Suggestions
```json
{
"tool": "get_product_suggestions",
"arguments": {
"category": "snacks",
"dietary_preferences": ["organic", "low-sugar"],
"min_nutriscore": "b",
"max_results": 5
}
}
```
### Vegan Breakfast Options
```json
{
"tool": "get_product_suggestions",
"arguments": {
"category": "breakfast-cereals",
"dietary_preferences": ["vegan", "high-protein"],
"max_results": 10
}
}
```
### Gluten-Free Products
```json
{
"tool": "get_product_suggestions",
"arguments": {
"category": "breads",
"dietary_preferences": ["gluten-free"],
"min_nutriscore": "c",
"max_results": 8
}
}
```
## Advanced Use Cases
### Health-Conscious Shopping Assistant
```json
// Find healthy alternatives in a category
{
"tool": "search_products",
"arguments": {
"categories": "chocolates",
"nutrition_grades": "a,b",
"nova_groups": "1,2",
"sort_by": "popularity"
}
}
```
### Dietary Restriction Helper
```json
// Find products suitable for specific dietary needs
{
"tool": "get_product_suggestions",
"arguments": {
"category": "plant-based-foods",
"dietary_preferences": ["vegan", "organic", "gluten-free"],
"max_results": 15
}
}
```
### Environmental Impact Analysis
```json
// Compare environmental impact of similar products
{
"tool": "compare_products",
"arguments": {
"barcodes": ["123456789", "987654321"],
"focus": "environmental"
}
}
```
### Nutritional Education
```json
// Analyze a product to understand its nutritional profile
{
"tool": "analyze_product",
"arguments": {
"barcode": "3017620422003"
}
}
```
## Common Search Parameters
### Categories
- `beverages` - All drinks
- `dairy` - Milk products, yogurts, cheese
- `snacks` - Chips, crackers, nuts
- `breakfast-cereals` - Cereals and granola
- `chocolates` - Chocolate products
- `breads` - Bread and bakery items
- `plant-based-foods` - Vegan alternatives
- `ice-creams` - Frozen desserts
### Nutrition Grades
- `a` - Best nutritional quality (green)
- `b` - Good nutritional quality (light green)
- `c` - Average nutritional quality (yellow)
- `d` - Poor nutritional quality (orange)
- `e` - Very poor nutritional quality (red)
### NOVA Groups
- `1` - Unprocessed or minimally processed
- `2` - Processed culinary ingredients
- `3` - Processed foods
- `4` - Ultra-processed foods
### Dietary Preferences
- `vegan` - No animal products
- `vegetarian` - No meat
- `gluten-free` - No gluten
- `organic` - Organic certified
- `low-fat` - Reduced fat content
- `low-sugar` - Reduced sugar content
- `high-protein` - High protein content
## Error Handling
The server handles various error conditions gracefully:
```json
// Product not found
{
"content": [
{
"type": "text",
"text": "Product not found for barcode: 1234567890123"
}
]
}
// Rate limit exceeded
{
"content": [
{
"type": "text",
"text": "Error: Rate limit exceeded for search. Wait 45 seconds."
}
],
"isError": true
}
// Invalid search parameters
{
"content": [
{
"type": "text",
"text": "No products found matching your search criteria."
}
]
}
```
## Performance Tips
1. **Use specific searches**: More specific search criteria return faster results
2. **Limit page size**: Use appropriate page_size (default: 20, max: 100)
3. **Cache results**: The server includes basic rate limiting and caching
4. **Batch requests**: Use compare_products for multiple product analysis
5. **Use staging API**: For development, use the staging server (default configuration)