justin
2e67a0fce2
Add futures_quote, basis_movement, basis_detail to the tools table, mark price_history/latest_prices filters optional, list the /futures endpoint, and point to CHANGELOG.md for per-release detail. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
93 lines
3.7 KiB
Markdown
93 lines
3.7 KiB
Markdown
# ag-bids-mcp
|
|
|
|
Model Context Protocol server exposing live + historical commodity price data
|
|
collected by [ag-monitor](https://git.jpaul.io/justin/ag-bids). Sits behind
|
|
the user's MetaMCP gateway at `https://mcp.jpaul.io/metamcp/ag-bids/mcp`.
|
|
|
|
## What it does
|
|
|
|
Lets an LLM client (Claude Desktop, OpenWebUI, anything that speaks MCP) ask
|
|
plain-English questions like:
|
|
|
|
- "What's the best place to sell corn today?"
|
|
- "What's the current price of lime?"
|
|
- "Show me the corn basis trend at Andersons Greenville over the last 30 days."
|
|
- "How is basis moving overall this week?"
|
|
- "What's the July corn futures price and how far has it moved since the open?"
|
|
- "Which sources are stale or failing?"
|
|
|
|
## How it talks to data
|
|
|
|
All data is read from ag-monitor over HTTPS:
|
|
|
|
```
|
|
ag-bids-mcp ── X-API-Key ─► https://agbids.paul.farm/api/data/*
|
|
```
|
|
|
|
Endpoints used: `/api/data/latest`, `/history`, `/futures`, `/best`, `/inputs`,
|
|
`/sources`, `/deliveries`. See the [ag-monitor source](https://git.jpaul.io/justin/ag-bids)
|
|
for the contract.
|
|
|
|
## Authentication
|
|
|
|
**No in-container auth.** The MCP's port 8000 is never exposed outside the
|
|
private `mcp-servers_mcp` Docker network on `.0.2`. The only client that
|
|
can reach it is MetaMCP, and MetaMCP enforces auth at the gateway → client
|
|
edge (bearer token / OAuth in its UI).
|
|
|
|
This matches the zerto-docs-mcp pattern.
|
|
|
|
## Local dev (stdio)
|
|
|
|
```bash
|
|
python3 -m venv venv && source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
cp .env.example .env # fill in AG_BIDS_API_KEY + AG_BIDS_MCP_USER/PASS
|
|
MCP_TRANSPORT=stdio python -m ag_bids_mcp.server
|
|
```
|
|
|
|
Wire into Claude Desktop's `claude_desktop_config.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"ag-bids": {
|
|
"command": "/path/to/venv/bin/python",
|
|
"args": ["-m", "ag_bids_mcp.server"],
|
|
"env": {
|
|
"MCP_TRANSPORT": "stdio",
|
|
"AG_BIDS_API_URL": "https://agbids.paul.farm",
|
|
"AG_BIDS_API_KEY": "..."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Deploy (MetaMCP host)
|
|
|
|
See [deploy/README.md](deploy/README.md). Container image is pulled from
|
|
`git.jpaul.io/justin/ag-bids-mcp:latest`; Watchtower on the MetaMCP host
|
|
auto-updates it every 5 minutes.
|
|
|
|
## Tools exposed
|
|
|
|
| Tool | Returns |
|
|
|---|---|
|
|
| `best_local_bid(commodity)` | Where to sell `corn`, `soy`, or `wheat` for this month's delivery — markdown one-liner + table |
|
|
| `futures_quote(commodity, delivery?)` | CBOT futures price + change since open + change on the day. With a delivery month it resolves the listed contract; without it, the continuous nearby |
|
|
| `current_lime_price()` | Latest lime quotes across all manual-entry sources |
|
|
| `current_input_price(product?)` | MAP / Potash / Lime — all three or one |
|
|
| `latest_prices(commodity?, source?, delivery?, kind?)` | Live snapshot table; every filter optional (`kind` = `grain`/`fertilizer`) |
|
|
| `price_history(commodity?, source?, delivery?, days?)` | Time series per (elevator, crop, delivery); **every filter optional** — omit `commodity` to span all crops. Shows bid + basis trend + futures |
|
|
| `basis_movement(commodity?, source?, delivery?, days?)` | Aggregated basis trend, one headline line per crop (the cheap overview) |
|
|
| `basis_detail(commodity?, source?, delivery?, days?)` | Per-(elevator, crop, delivery) basis first→last drill-down |
|
|
| `list_sources()` | Active scrapers + last-success timestamps |
|
|
| `list_commodities()` | corn, soy, wheat, map, potash, lime |
|
|
| `list_deliveries(commodity)` | Posted delivery labels, chronological |
|
|
| `source_health()` | Stale / failing / healthy summary |
|
|
| `todays_summary()` | Same shape as the morning brief snapshot |
|
|
|
|
For the full per-release detail (signatures, conventions, example question → call
|
|
mappings), see [CHANGELOG.md](CHANGELOG.md).
|