# Food MCP Server + Agent

A two-stage AI project: an [MCP](https://modelcontextprotocol.io) server exposing cooking/recipe tools backed by the [Spoonacular](https://spoonacular.com/food-api) API, and a Gemini-powered agent built on top of it that answers natural-language cooking questions by calling those tools.

## Why MCP here

Rather than gluing an LLM directly to a food API with custom prompt-stuffed context, MCP exposes each capability as a typed, documented tool that any compliant client (Claude Desktop, a custom agent, etc.) can discover and call on its own.
The model decides *when* to call `search_recipes_by_ingredients` vs. `get_ingredient_substitutes` based on the tool descriptions — it isn't hardcoded into a single prompt.

## Tools

| Tool | Purpose |
|---|---|
| `search_recipes` | Natural-language recipe search with diet/cuisine/time filters |
| `search_recipes_by_ingredients` | "What can I cook with what I have" |
| `get_recipe_details` | Full recipe: ingredients, steps, image, source |
| `get_recipe_nutrition` | Calorie and macro/nutrient breakdown for a recipe |
| `get_ingredient_substitutes` | Suggested swaps for an ingredient you don't have |

These five were chosen deliberately (over exposing Spoonacular's full endpoint list) so they compose well for an agent: e.g. *"find a vegetarian recipe from these ingredients, show me the nutrition, and suggest a substitute for the one thing I'm missing"* chains three of these tools naturally.

## Setup

```bash
pip install -r requirements.txt
cp .env.example .env
# edit .env and add your free Spoonacular API key
```

## Run the server on its own

```bash
python server.py
```

This starts the server over stdio, the standard transport for local MCP clients.
You don't need to do this before running the agent below — it's only useful for testing the server in isolation.

## Test the server with the MCP Inspector

Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to call tools directly and see raw input/output before wiring this into an agent:

```bash
npx @modelcontextprotocol/inspector python server.py
```

## Use it with Claude Desktop

Add to your Claude Desktop MCP config:

```json
{
  "mcpServers": {
    "food": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": { "SPOONACULAR_API_KEY": "your_key_here" }
    }
  }
}
```

## The agent (stage 2)

`agent.py` is a command-line agent built on top of this server.
It uses Google Gemini's function-calling API to turn a plain-language question into one or more tool calls, chaining them together when needed — e.g. "find me a quick vegetarian dinner and check if it's healthy" triggers `search_recipes`, then `get_recipe_nutrition` on the result, with the agent deciding that sequence on its own from the tool descriptions.

It's written directly against the raw Gemini API and the raw MCP client (rather than an agent framework like LangChain), so the tool-calling loop is fully visible in the code.

### Agent setup

```bash
# add to your .env, alongside SPOONACULAR_API_KEY
GOOGLE_API_KEY=your_key_here   # free at https://aistudio.google.com/apikey
```

### Run the agent

```bash
python agent.py
```

You don't need to run `server.py` separately — the agent launches it automatically as a subprocess and talks to it over stdio.

### Example session

```
You: find me a quick vegetarian dinner and check if it's healthy

[calling tool: search_recipes({"query": "vegetarian dinner", "diet": "vegetarian", "max_ready_minutes": 30})]

[calling tool: get_recipe_nutrition({"recipe_id": 123456})]

Gemini: I found a vegetarian stir-fry ready in 25 minutes — it's about
480 calories with a good protein-to-carb balance, so a reasonably
healthy pick for a quick dinner.
```

## Roadmap

Stages 1 (MCP server) and 2 (agent) are both built.
Possible future additions: `search_recipes_by_diet`, `get_similar_recipes`, `convert_ingredient_amount`, and a web/chat UI in place of the command-line interface.

## Notes

- Free-tier Spoonacular quota is limited per day; the server surfaces a clear error if you hit it rather than failing silently.
- API keys are read from environment / `.env`, never hardcoded.
- The agent originally targeted Claude's API, then was moved to Gemini's free tier to keep this project cost-free.
  The MCP server needed zero changes for that swap — only the agent's model-calling logic and tool schema conversion did, since MCP standardizes the tool layer but not the underlying model API.