# Mandi Price Advisor — MCP Server

An MCP server that gives farmers and traders **daily mandi (wholesale market) commodity prices** across India, lets them compare markets, and — critically — **sets price alerts that message them on Telegram** when a threshold is crossed.

This goes beyond fetch-only MCP wrappers: the scheduler acts on the user's behalf over time, making the system genuinely agentic.

## Architecture

```
Claude / any MCP client
        │  tools · resources · prompts
        ▼
MCP Server (Streamable HTTP)
        ├── Tools: get_mandi_price, compare_markets, get_price_trend,
        │           set_price_alert, list_my_alerts, cancel_alert
        ├── Resources: mandi://commodity/{name}/state/{state}/latest
        │              mandi://commodity/{name}/market/{market}/history
        └── Prompts: daily_selling_advisory
        │
        ├── SQLite (cache, alerts, price history)
        ├── api.data.gov.in (verified mandi dataset)
        └── APScheduler → Telegram Bot API
```

**Key design decision:** Price facts are always fetched from [data.gov.in](https://data.gov.in) or read from a validated SQLite cache — never generated or interpolated by an LLM. The LLM's only job is understanding the user's request and phrasing the response.

## Data Source (Verified)

| Field | Value |
|---|---|
| Dataset | Current Daily Price of Various Commodities from Various Markets (Mandi) |
| Publisher | Ministry of Agriculture and Farmers Welfare |
| Resource ID | `9ef84268-d588-465a-a308-a864a43d0070` |
| Endpoint | `https://api.data.gov.in/resource/9ef84268-d588-465a-a308-a864a43d0070?api-key={KEY}&format=json` |
| Fields | `state`, `district`, `market`, `commodity`, `variety`, `grade`, `arrival_date`, `min_price`, `max_price`, `modal_price` |
| Update cadence | **Once per day** (not real-time) |

Get a free API key instantly at [data.gov.in](https://data.gov.in) — no approval wait.

## Quick Start

### 1. Install dependencies

```bash
cd mandi-advisor-mcp
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # macOS/Linux
pip install -r requirements.txt
```

### 2. Configure environment

```bash
copy .env.example .env        # Windows
# cp .env.example .env        # macOS/Linux
```

Edit `.env`:

```
DATA_GOV_IN_API_KEY=your_key_from_datagovin
TELEGRAM_BOT_TOKEN=your_token_from_BotFather
```

### 3. Set up Telegram

1. Message [@BotFather](https://t.me/BotFather) on Telegram → `/newbot`
2. Copy the bot token into `.env`
3. Message your bot `/start` — the bot replies with your `chat_id` (background polling starts automatically when the server runs)
4. Use that `chat_id` when calling `set_price_alert`

### 4. Run the MCP server

```bash
python -m mcp_server.server
```

Server starts on `http://0.0.0.0:8000` with **Streamable HTTP** transport. The alert scheduler and Telegram `/start` bot polling run in the background.

### 5. Connect from Cursor / Claude Desktop

Add to your MCP client config:

```json
{
  "mcpServers": {
    "mandi-advisor": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

## MCP Surface

### Tools

| Tool | Description |
|---|---|
| `get_mandi_price` | Latest min/max/modal price for a commodity, optionally by state/market |
| `compare_markets` | Compare modal prices across states to find the best market |
| `get_price_trend` | Modal price trend over N days from cached history |
| `set_price_alert` | **Action tool** — Telegram alert when threshold is crossed |
| `list_my_alerts` | List active alerts for a chat ID |
| `cancel_alert` | Cancel an alert by ID |

### Resources

- `mandi://commodity/{commodity}/state/{state}/latest`
- `mandi://commodity/{commodity}/market/{market}/history`

### Prompts

- `daily_selling_advisory(commodity, location?, state?, market?)` — "Should I sell today?" briefing grounded in fetched data

## Alert Behavior

1. User calls `set_price_alert(commodity="Onion", market="Pune", threshold_price=2000, direction="above", telegram_chat_id="123456")`
2. Alert stored in SQLite
3. Scheduler (every 6h) batch-fetches prices for all watched commodity/market pairs
4. On threshold cross → Telegram message sent, alert marked **fired** (one-shot)

Example notification:
> 🔔 Price Alert: Onion at Pune market is now ₹2,100/quintal (as of 2026-07-27), above your ₹2,000 alert.

## Running Tests

```bash
pytest eval/ -v
```

Tests cover:
- API response parsing and httpx-mocked fetch/caching
- Alert threshold edge cases (`above`/`below`, exact threshold, missing data)
- Cache hit/expiry behavior
- End-to-end scheduler with mocked Telegram
- MCP tool registration and prompt location resolution
- Telegram `/start` bot handler

## Deployment

Deploy to Railway, Render, or similar **always-on** host (alerts require a persistent scheduler).

**Docker:**

```bash
docker build -t mandi-advisor-mcp .
docker run -p 8000:8000 --env-file .env mandi-advisor-mcp
```

**Railway / Render:** use the included `railway.toml` or `render.yaml` with the Dockerfile.

```bash
python -m mcp_server.server
```

Set environment variables on the host. Recommended: `ALERT_CHECK_INTERVAL_HOURS=6`, `CACHE_TTL_SECONDS=21600`, `TELEGRAM_POLLING_ENABLED=true`.

## Disclaimers

> **Prices are sourced from the Government of India's daily mandi price dataset and update once per day, not in real time.** Always confirm final prices at the actual market before making a selling decision.

> **This tool does not execute trades or transactions** — it only informs and alerts.

## Project Structure

```
mandi-advisor-mcp/
├── mcp_server/          # MCP tools, resources, prompts, server entrypoint
├── data_layer/          # data.gov.in client, SQLite, alert logic
├── scheduler/           # APScheduler alert checker
├── notifications/       # Telegram Bot API wrapper
├── eval/                # Tests and API response fixtures
└── requirements.txt
```

## License

MIT