Metadata-Version: 2.4
Name: mealcp-mcp
Version: 0.1.0
Summary: Official Model Context Protocol (MCP) server for MealCP.
Author: MealCP
License: MIT
Project-URL: Homepage, https://mealcp.com
Project-URL: Documentation, https://mealcp.com/integrations/mcp/
Keywords: mcp,model-context-protocol,grocery,prices,mealcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=2.0.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7

# MealCP MCP

Official [Model Context Protocol](https://modelcontextprotocol.io) server for
[MealCP](https://mealcp.com) — the grocery & food data layer for AI agents.

Exposes two tools over the MealCP public API:

- **`search_products`** — search the grocery product catalog by keyword with
  faceted filtering (country, retailer, chain, brand, tag, category, city,
  price range, sort, pagination).
- **`get_price_history`** — aggregated price-history stats (min/max/avg/first/
  last, net change) for one product over a date range.

## Requirements

- Python 3.10+
- An API key from MealCP (each tool call consumes 1 credit)

## Usage

Run directly with [uv](https://docs.astral.sh/uv/):

```bash
uvx mealcp-mcp
```

Or install:

```bash
pip install mealcp-mcp
mealcp-mcp
```

The server speaks MCP over stdio; any MCP host (Claude Desktop, opencode,
Cursor, …) can spawn it.

### Claude Desktop

```json
{
  "mcpServers": {
    "mealcp": {
      "command": "uvx",
      "args": ["mealcp-mcp"],
      "env": {
        "MEALCP_API_URL": "https://api.mealcp.com",
        "MEALCP_API_KEY": "mcp_live_your_key_here"
      }
    }
  }
}
```

### opencode

```json
{
  "mcp": {
    "mealcp": {
      "type": "local",
      "command": ["uvx", "mealcp-mcp"],
      "enabled": true,
      "environment": {
        "MEALCP_API_URL": "https://api.mealcp.com",
        "MEALCP_API_KEY": "mcp_live_your_key_here"
      }
    }
  }
}
```

## Configuration

| Variable         | Default                | Description                          |
| ---------------- | ---------------------- | ------------------------------------ |
| `MEALCP_API_URL` | `http://localhost:8000`| Base URL of the MealCP API           |
| `MEALCP_API_KEY` | _(none)_               | `X-API-Key` sent with every request  |

## Errors

Tool errors surface the API's stable error tokens, formatted
`<code>: <message>` (e.g. `not_found: Product not found`). Branch on the code,
never the message.

## Contract

Response models are generated from the API's OpenAPI spec
(`contract/openapi.json`, currently version **0.1.0**). Refresh with:

```bash
uvx --from datamodel-code-generator datamodel-codegen \
  --input contract/openapi.json \
  --output src/mealcp_mcp/models.py \
  --output-model-type pydantic_v2.BaseModel \
  --target-python-version 3.10 --disable-timestamp
```

## Development

```bash
uv sync
uv run pytest
uv run ruff check .
```

## License

MIT
