Add price_trend / price_series MCP tools (USDA NASS grain)

Real $/bu price + MoM/YoY change + seasonal percentile context for corn/soy/
wheat, US + states, deep history. Wraps the new /api/data/price-trend and
/api/data/price-series endpoints. Changelog updated.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

ag_bids_mcp/client.py

@@ -70,6 +70,16 @@ def best(commodity: str) -> dict:
     return _get("/api/data/best", commodity=commodity)
 
 
+def price_trend(commodity: str, geo: str = "US", years: int = 10) -> dict:
+    return _get("/api/data/price-trend", commodity=commodity, geo=geo, years=years)
+
+
+def price_series(commodity: str, geo: str = "US",
+                 start_year: int | None = None, end_year: int | None = None) -> dict:
+    return _get("/api/data/price-series", commodity=commodity, geo=geo,
+                start_year=start_year, end_year=end_year)
+
+
 def futures(commodity: str, delivery: str | None = None) -> dict:
     return _get("/api/data/futures", commodity=commodity, delivery=delivery)
 

ag_bids_mcp/format.py

@@ -90,6 +90,85 @@ def fmt_best(commodity: str, payload: dict) -> str:
     )
 
 
+# ---------- reference price trends (USDA NASS / EIA) ----------
+
+
+def _unit_money(cents, unit: str) -> str:
+    if cents is None:
+        return "—"
+    dollars = cents / 100
+    if unit == "$/gal":
+        return f"${dollars:.3f}/gal"
+    if unit == "$/bu":
+        return f"${dollars:.2f}/bu"
+    if unit == "$/ton":
+        return f"${dollars:.2f}/ton"
+    return f"${dollars:.2f}"
+
+
+def _signed(cents) -> str:
+    if cents is None:
+        return "—"
+    return f"{'+' if cents >= 0 else '−'}${abs(cents)/100:.2f}"
+
+
+def _pct(p) -> str:
+    return "—" if p is None else f"{'+' if p >= 0 else '−'}{abs(p):.1f}%"
+
+
+def _ym(period: str) -> str:
+    # 2026-04-01 -> "Apr 2026"; weekly date -> as-is
+    try:
+        y, m, d = period.split("-")
+        return f"{_MONTH_NAMES_3[int(m)-1]} {y}" if d == "01" else period
+    except Exception:
+        return period
+
+
+_MONTH_NAMES_3 = ["Jan", "Feb", "Mar", "Apr", "May", "Jun",
+                  "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
+
+
+def fmt_price_trend(payload: dict, label: str = "price received") -> str:
+    commodity = payload.get("commodity")
+    geo = payload.get("geo")
+    unit = payload.get("unit") or "$/bu"
+    t = payload.get("trend")
+    if not t:
+        return f"### {commodity} — {geo} — {label}\n\nNo data on file.\n"
+    when = _ym(t["period"])
+    lines = [f"### {commodity} — {geo} — {label}, {when}: {_unit_money(t['value_cents'], unit)}", ""]
+    arrow = _delta_arrow(t.get("change_cents"))
+    lines.append(f"- **Change:** {arrow} {_signed(t.get('change_cents'))} ({_pct(t.get('change_pct'))}) vs prior period")
+    if t.get("yoy_cents") is not None:
+        lines.append(f"- **Year-over-year:** {_signed(t.get('yoy_change_cents'))} ({_pct(t.get('yoy_pct'))})")
+    s = t.get("seasonal")
+    if s:
+        lines.append(
+            f"- **Seasonal:** {s['percentile']}th pct vs last {s['sample_years']} same-months "
+            f"(normal {_unit_money(s['normal_cents'], unit)}, range "
+            f"{_unit_money(s['min_cents'], unit)}–{_unit_money(s['max_cents'], unit)}) "
+            f"· {_pct(s.get('vs_normal_pct'))} vs normal")
+    lines.append(f"- **Recent direction:** {_delta_arrow({'up':1,'down':-1,'flat':0}[t['recent_direction']])} {t['recent_direction']}")
+    lines.append(f"\n_Source: {payload.get('source') or 'USDA NASS'} · {t['points']} months on file_")
+    return "\n".join(lines) + "\n"
+
+
+def fmt_price_series(payload: dict, max_points: int = 60) -> str:
+    commodity = payload.get("commodity")
+    geo = payload.get("geo")
+    unit = payload.get("unit") or "$/bu"
+    series = payload.get("series") or []
+    if not series:
+        return f"### {commodity} — {geo} series\n\nNo data on file.\n"
+    shown = series[-max_points:]
+    head = [f"### {commodity} — {geo} — {payload.get('count', len(series))} periods "
+            f"(showing last {len(shown)})", "",
+            "| Period | Price |", "|---|---:|"]
+    body = [f"| {_ym(p['period'])} | {_unit_money(p['value_cents'], unit)} |" for p in shown]
+    return "\n".join(head + body) + "\n"
+
+
 # ---------- futures quote + change ----------
 
 

ag_bids_mcp/server.py

@@ -246,6 +246,63 @@ def basis_detail(
         return fmt.fmt_basis_detail(_filter_source(payload, source))
 
 
+@mcp.tool()
+def price_trend(
+    commodity: Annotated[
+        str, Field(description="Grain: 'corn', 'soy', or 'wheat'.")
+    ],
+    geo: Annotated[
+        str,
+        Field(description="'US' or a 2-letter state (e.g. 'OH', 'IA'). Default US."),
+    ] = "US",
+    years: Annotated[
+        int, Field(ge=1, le=120, description="Baseline window for the seasonal normal/percentile."),
+    ] = 10,
+) -> str:
+    """USDA NASS monthly price *received by farmers* ($/bu) with the change.
+
+    Returns the latest real price plus month-over-month and year-over-year moves
+    (dollars + percent) and where it sits seasonally (percentile vs the same
+    month over the last N years, normal, and range). This is the macro/seasonal
+    benchmark to compare local cash bids against — corn history goes back to 1908."""
+    cm = commodity.strip().lower()
+    g = geo.strip().upper()
+    with track("price_trend", commodity=cm, geo=g, years=years):
+        if cm not in VALID_GRAIN:
+            return f"`commodity` must be one of: {sorted(VALID_GRAIN)}"
+        return fmt.fmt_price_trend(client.price_trend(commodity=cm, geo=g, years=years))
+
+
+@mcp.tool()
+def price_series(
+    commodity: Annotated[
+        str, Field(description="Grain: 'corn', 'soy', or 'wheat'.")
+    ],
+    geo: Annotated[
+        str, Field(description="'US' or a 2-letter state. Default US."),
+    ] = "US",
+    start_year: Annotated[
+        int | None, Field(description="Optional first year (default: ~last 5 yrs of the full series).")
+    ] = None,
+    end_year: Annotated[int | None, Field(description="Optional last year.")] = None,
+) -> str:
+    """Raw monthly price-received series ($/bu) for charting / drill-down.
+
+    Use price_trend for the headline; use this when you need the actual monthly
+    numbers. Defaults to the recent window unless you pass a start_year."""
+    cm = commodity.strip().lower()
+    g = geo.strip().upper()
+    with track("price_series", commodity=cm, geo=g):
+        if cm not in VALID_GRAIN:
+            return f"`commodity` must be one of: {sorted(VALID_GRAIN)}"
+        # Default to a readable recent window if no range given.
+        if start_year is None and end_year is None:
+            from datetime import datetime
+            start_year = datetime.utcnow().year - 5
+        payload = client.price_series(commodity=cm, geo=g, start_year=start_year, end_year=end_year)
+        return fmt.fmt_price_series(payload)
+
+
 @mcp.tool()
 def list_sources() -> str:
     """All active scrapers + their last-success timestamps and any pending failures."""