ag-bids-mcp/CHANGELOG.md

Changelog

Notes for clients/agents that consume the ag-bids MCP tools and the underlying ag-monitor /api/data/* HTTP API. Newest first.

2026-05-31 — Location-aware bid lookup (zip / GPS + radius)

best_local_bid and latest_prices can now be scoped to a farmer's location, so "where should I haul today" means near me, not "across every elevator we scrape." Filtering is offline (vendored US Census ZIP centroids — no geocoding API).

Changed MCP tools

• best_local_bid(commodity, zip?, lat?, lng?, radius_miles?) — pass a zip OR lat+lng (not both) with optional radius_miles (default 50) to restrict to nearby elevators; the result shows the distance to the winner. With no location it behaves as before (all sources). If nothing is in range it returns no winner and reports the nearest elevator + its distance, so a coverage gap reads as a gap, not an error.
• latest_prices(..., zip?, lat?, lng?, radius_miles?) — same location filter; rows are limited to the radius, annotated with distance_miles, and sorted nearest-first (adds a Distance column).

GPS input is reverse-labeled to its nearest ZIP for display; only zip → coord is used for the actual distance math.

Coverage note: scraped cash-bid sources are currently concentrated in Ohio. A zip/GPS far from Ohio (e.g. Iowa) will correctly return "nothing in range" with the nearest-source hint until more regions are added. (Reference data — price_trend, input_cost_trend — is already national.)

API

• GET /api/data/best?commodity=&zip=&lat=&lng=&radius_miles= — new location params. Response adds center ({lat,lng,zip,source}), radius_miles, and (when out of range) nearest. best now carries distance_miles, city, state.
• GET /api/data/latest?...&zip=&lat=&lng=&radius_miles= — same params; rows carry distance_miles and source city/state/latitude/longitude; response adds center + radius_miles when a location is given.
• Errors (HTTP 400): zip and GPS together, partial GPS, radius_miles with no location, or an unknown zip.

Example questions → tool calls

Ask	Call
Best corn bid within 40 mi of my zip	best_local_bid(commodity="corn", zip="45810", radius_miles=40)
Best soybean bid near my coordinates	best_local_bid(commodity="soy", lat=40.79, lng=-83.81)
Elevators near me, nearest first	latest_prices(commodity="corn", zip="45810", radius_miles=60)

2026-05-30 — Regional fertilizer input costs (real $/ton + change)

Real U.S. regional retail fertilizer prices now feed the input-cost tools, so the advisor can reason about fertilizer the same way it does diesel and grain — actual dollars and the move, not an index. Source: USDA AgTransport (monthly, $/ton, history back to 2023).

Changed MCP tools (fertilizer added to the existing input-cost tools)

• input_cost_trend(item, geo?, years=10) — item now accepts six fertilizers in addition to diesel: urea, uan, anhydrous (anhydrous ammonia), dap, map, potash. Returns the latest real $/ton, month-over-month and year-over-year change ($ and %), and seasonal context.
  • New optional geo = AgTransport region; defaults to Cornbelt. Other regions: U.S. Gulf NOLA, Northern Plains, Southern Plains, Southeast, Northeast, California, Pacific Northwest, South Central, Central Florida, Tampa (not every product is published for every region).
  • diesel is unchanged — national U.S. $/gal, weekly; geo is ignored for it.
• input_cost_series(item, geo?) — raw monthly $/ton series for any fertilizer (or the diesel $/gal weekly series), region-selectable.

Seasonal percentile for fertilizer is computed over a short history (2023+), so it deepens over time; the price and YoY/MoM change are solid now.

API

• GET /api/data/input-cost-trend?item=&geo=&years= — geo added.
• GET /api/data/input-cost-series?item=&geo= — geo added.
• GET /api/data/input-cost-geographies?item= — new: lists the regions a given input has data for (plus its default_geo).

Example questions → tool calls

Ask	Call
Cornbelt urea price and how it's moved	input_cost_trend(item="urea")
Anhydrous ammonia in the Southern Plains	input_cost_trend(item="anhydrous", geo="Southern Plains")
Potash $/ton history	input_cost_series(item="potash")
Which regions have DAP prices	(API) GET /api/data/input-cost-geographies?item=dap

2026-05-30 — Grain price-received trends (real $ + change + seasonal)

New national/seasonal reference layer (USDA NASS, corn back to 1908) — the macro benchmark to compare local cash bids against. Real prices and the change, not an index.

New MCP tools

• price_trend(commodity, geo="US", years=10) — monthly price received by farmers ($/bu) with the move: latest real price, month-over-month and year-over-year change ($ and %), and seasonal context (percentile vs the same month over the last N years, normal, and range). geo is US or any 2-letter state. Conclusions, not rows.
• price_series(commodity, geo="US", start_year?, end_year?) — raw monthly series ($/bu) for charting/drill-down (defaults to the recent window).

API

• GET /api/data/price-trend?commodity=&geo=&years= — computed trend (cents + change_cents/change_pct/yoy_* + seasonal).
• GET /api/data/price-series?commodity=&geo=&start_year=&end_year= — raw series.
• GET /api/data/price-geographies?commodity= — which geos (US + states) exist.

All grain: corn/soy/wheat, all 50 states + US.

Input-cost tools (real $ + change)

• input_cost_trend(item, years=10) — real input price with the move. Currently item="diesel" (EIA U.S. retail $/gal, weekly, back to 1994): latest price + week-over-week and year-over-year change + seasonal percentile/range. (For current fertilizer $/ton, current_input_price (DTN) still applies; more inputs extend this same tool.)
• input_cost_series(item) — raw historical series for an input.
• API: GET /api/data/input-cost-trend?item=&years=, GET /api/data/input-cost-series?item=.

USDA stopped publishing dollar input prices in 2014, so these use real-dollar sources (EIA) rather than an index.

2026-05-30 — Source geo + many more locations

Per-source geo (API + MCP)

• GET /api/data/sources now returns location geo on every source: city, state, zip, county, latitude, longitude (any may be null). The AgriCharts-fed elevators carry exact coordinates; smaller sites carry city/state/zip.
• MCP list_sources gained a Location column (City, ST ZIP). source_health is unchanged in shape.
• Sources that are national or non-physical (CBOT futures, USDA AMS, DTN fertilizer, hedge-to-arrive / "Direct" bid buckets) legitimately have null geo. ~43 of ~51 sources are geo-tagged.

Many more elevator locations

These flow through every data tool/endpoint automatically (latest, history, best, basis_movement/basis_detail, sources, deliveries). No tool signatures changed — just far more sources, all named "<Co-op> — <Location>":

• Heritage Cooperative — new co-op, 23 central/eastern-Ohio locations (corn/soy/wheat).
• Mercer Landmark — expanded from 2 to all ~16 locations. Note: the two old source names were renamed for continuity — "Mercer Landmark — St Henry" → "Mercer Landmark — MPS St Henry", "Mercer Landmark — Minster" → "Mercer Landmark — Heartland Minster".
• Bambauer — now both locations incl. Pemberton ("Bambauer — Jackson Center / New Knoxville", "Bambauer — Pemberton"); the old "Bambauer Jackson Center / New Knoxville, OH" source was renamed to the first of those.

If you cache source names, refresh them — several changed and many were added.

2026-05-29 — Futures price + change tool

New MCP tool

• futures_quote(commodity, delivery?) — CBOT futures price and change for a grain. Reports the latest price, today's session open, the prior day's close, and both moves: change since open and change on the day (vs the previous settle). With delivery (e.g. "Jul 2026") it resolves the listed contract that month prices against (e.g. ZCN26); without it, the continuous nearby.

API changes (ag-monitor)

• GET /api/data/futures?commodity=<grain>&delivery=<label?> — new endpoint. Returns { commodity, delivery, contract, symbol, quote } where quote is { settle_date, open_cents, last_cents, prev_close_cents, change_since_open_cents, change_on_day_cents, fetched_at } (or null if no data yet for that contract). commodity must be corn/soy/wheat.
• futures_quotes table gained an open_cents column; the futures scraper now stores the session Open alongside the close. Rows captured before this change have open_cents = NULL, so change_since_open_cents is null for those until the next session is scraped.
• Futures now also pull at :30 during the CBOT day session (on top of the hourly :00), so last and the changes track the session every ~30 min.

Example questions → tool calls

Ask	Call
Corn Jul futures and how far it's moved today	futures_quote(commodity="corn", delivery="Jul 2026")
Soy nearby futures, change on the day	futures_quote(commodity="soy")

2026-05-29 — Flexible history + basis movement

New MCP tools

• basis_movement(commodity?, source?, delivery?, days=30) — aggregated basis trend, one headline line per crop. Averages every matching (elevator × delivery) series to avg basis first → last over the window and reports how far it moved. This is the cheap "how is basis moving overall" view. All filters optional; commodity (if given) must be corn/soy/wheat.

  • Positive move = cash strengthened vs futures (basis up); negative = weaker.
  • Aggregation is intentional: divergent elevators can net to "flat". When the aggregate looks flat or surprising, call basis_detail to see per-elevator splits.

• basis_detail(commodity?, source?, delivery?, days=30) — the drill-down for basis_movement. One row per (elevator, crop, delivery) series with basis first → last and the move. Same optional filters.

Both tools do the aggregation server-side (in the MCP) and return compact markdown — they do not dump every raw sample — to keep token usage low. Pattern: call basis_movement first, then basis_detail (optionally filtered) only when you need the breakdown.

Changed MCP tools

• price_history — commodity is now optional (was required). Omit it to span every crop. Output now groups by (elevator, crop, delivery), surfaces basis first → last in each series summary, and adds a Futures column to the raw points table. Every filter (commodity, source, delivery, days) is optional and AND'd — pivot per elevator, per crop, per delivery, or any combination.

  • Raw per-row points are still only included when the window has ≤ ~60 samples; wider queries return the per-series summaries only.

• latest_prices — added the kind filter (grain | fertilizer) for parity with the API. commodity, source, delivery, kind all optional.

API changes (ag-monitor)

• GET /api/data/history — commodity query param is now optional. When omitted, returns history across all crops. source_id, delivery, and days (1–730, default 30) remain optional. Response shape is unchanged: { "commodity": <str|null>, "days": <int>, "rows": [...] }. Each row carries fetched_at, source_id, source_name, commodity, delivery, bid_cents, basis_cents, futures_cents so callers can pivot client-side.
  • GET /api/data/latest already supported optional commodity, source, delivery, kind — unchanged.

Conventions / gotchas

• All money fields are integer cents. bid_cents/futures_cents render as $/bu (4 dp) for grain and $/ton (2 dp) for fertilizer; basis_cents renders as a signed dollar value (2 dp), e.g. -0.14.
• Basis is only meaningful for grain — the basis tools skip non-grain rows and any series with no basis on file.
• source filtering is by exact elevator display name (e.g. "Mercer Landmark — Minster"). Use list_sources to get exact names.

Example questions → tool calls

Ask	Call
Basis movement overall, last 7 days	basis_movement(days=7)
Corn basis movement across all elevators	basis_movement(commodity="corn")
Basis movement at one elevator	basis_movement(source="Mercer Landmark — Minster")
Per-elevator basis breakdown for corn	basis_detail(commodity="corn")
Last 7 days of history from elevator X for corn	price_history(commodity="corn", source="…", days=7)
All-crop price history at one elevator	price_history(source="…")
Latest grain bids only	latest_prices(kind="grain")