bellwether-mcp 1.3.1__tar.gz

bellwether_mcp-1.3.1/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012-2023 Project Maintainers
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

bellwether_mcp-1.3.1/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: bellwether-mcp
+Version: 1.3.1
+Summary: Crypto discovery/caps (CoinMarketCap), Fed macro series with point-in-time vintages (FRED/ALFRED), and the FOMC decision calendar as an MCP server and agent-connector-sdk source adapters
+Author-email: Project Maintainers <maintainers@users.noreply.github.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: agent-connector-sdk[mcp]<1.0.0,>=0.3.13
+Requires-Dist: httpx>=0.28.1
+Provides-Extra: test
+Requires-Dist: pytest-xdist>=3.8.0; extra == "test"
+Requires-Dist: pytest>=9.1.1; extra == "test"
+Requires-Dist: pytest-asyncio>=1.4.0; extra == "test"
+Requires-Dist: pytest-cov>=7.1.0; extra == "test"
+Dynamic: license-file
+
+# bellwether-mcp
+
+*Version: 1.3.1*
+
+> **Documentation** — Installation, deployment, and tool usage are maintained in the
+> [official documentation](https://knuckles-team.github.io/bellwether-mcp/).
+
+Crypto discovery/rankings/market caps (CoinMarketCap), Fed macro and liquidity
+series with point-in-time vintages (FRED/ALFRED), and the FOMC decision
+calendar (hike/cut/hold, sourced) — as an MCP tool surface and, through
+`agent-connector-sdk`'s declarative `mcp_tool` source adapter, as bounded,
+checkpointed ingestion streams intended for EG's `finance-v1` world-model
+ontology (`feat/finance-core`, not yet published — see AGENTS.md).
+
+**Not a venue-specific OHLCV feed.** CoinMarketCap's general historical OHLCV
+endpoint documents hourly/daily coverage only, not minute-level exchange
+candles — pair this package with an `emerald-exchange` backend for tradable
+bars and charts.
+
+## Sources
+
+| Ledger row | Sources | Target class (provisional) |
+|---|---|---|
+| EH-412 (crypto discovery/caps) | CoinMarketCap listings/quotes/global-metrics | `Instrument`, `MacroEvent` |
+| EH-412 (Fed macro series) | FRED/ALFRED `series/observations`, `series/vintagedates` | `EconomicIndicator` |
+| EH-412 (FOMC calendar) | Curated dataset, sourced to federalreserve.gov press releases | `MacroEvent` |
+| EH-422 (macro/liquidity) | FRED named aliases: `WALCL`, `WDTGAL`, `M2SL`, `RRPONTSYD`, `WRESBAL`, `DGS10`, `DTWEXBGS` | `EconomicIndicator` |
+
+`Instrument`, `EconomicIndicator` and `MacroEvent` are the design doc's own
+proposed finance-v1 class names
+(`plans/refactor/proposals/FINANCE-INTEGRATION-20260924.md` section 4/7).
+EG's `feat/finance-core` branch, which owns finance-v1, has not published
+anything yet as of this package's build — see AGENTS.md "Ontology mapping"
+before trusting these as final.
+
+## Tools
+
+Eight MCP tools, one FastMCP server (`bellwether-mcp` console script):
+`cmc_listings`, `cmc_quotes`, `cmc_global_metrics`, `fred_macro_series_aliases`,
+`fred_series_observations`, `fred_series_observations_asof`,
+`fred_series_vintage_dates`, `fomc_calendar_list`.
+
+Every tool is keyless except `cmc_*` and `fred_*`, whose credentials are
+resolved server-side through `agent_connector_sdk.credentials`
+(`BELLWETHER_CMC_API_KEY`, `BELLWETHER_FRED_API_KEY`) — never accepted as a
+tool argument. `fomc_calendar_list` reads a packaged, curated, sourced dataset
+and needs no credential and no network.
+
+See [`AGENTS.md`](AGENTS.md) for architecture, the ontology-mapping
+authority, the FOMC dataset's provenance, rate limits, and commands.

bellwether_mcp-1.3.1/README.md

@@ -0,0 +1,50 @@
+# bellwether-mcp
+
+*Version: 1.3.1*
+
+> **Documentation** — Installation, deployment, and tool usage are maintained in the
+> [official documentation](https://knuckles-team.github.io/bellwether-mcp/).
+
+Crypto discovery/rankings/market caps (CoinMarketCap), Fed macro and liquidity
+series with point-in-time vintages (FRED/ALFRED), and the FOMC decision
+calendar (hike/cut/hold, sourced) — as an MCP tool surface and, through
+`agent-connector-sdk`'s declarative `mcp_tool` source adapter, as bounded,
+checkpointed ingestion streams intended for EG's `finance-v1` world-model
+ontology (`feat/finance-core`, not yet published — see AGENTS.md).
+
+**Not a venue-specific OHLCV feed.** CoinMarketCap's general historical OHLCV
+endpoint documents hourly/daily coverage only, not minute-level exchange
+candles — pair this package with an `emerald-exchange` backend for tradable
+bars and charts.
+
+## Sources
+
+| Ledger row | Sources | Target class (provisional) |
+|---|---|---|
+| EH-412 (crypto discovery/caps) | CoinMarketCap listings/quotes/global-metrics | `Instrument`, `MacroEvent` |
+| EH-412 (Fed macro series) | FRED/ALFRED `series/observations`, `series/vintagedates` | `EconomicIndicator` |
+| EH-412 (FOMC calendar) | Curated dataset, sourced to federalreserve.gov press releases | `MacroEvent` |
+| EH-422 (macro/liquidity) | FRED named aliases: `WALCL`, `WDTGAL`, `M2SL`, `RRPONTSYD`, `WRESBAL`, `DGS10`, `DTWEXBGS` | `EconomicIndicator` |
+
+`Instrument`, `EconomicIndicator` and `MacroEvent` are the design doc's own
+proposed finance-v1 class names
+(`plans/refactor/proposals/FINANCE-INTEGRATION-20260924.md` section 4/7).
+EG's `feat/finance-core` branch, which owns finance-v1, has not published
+anything yet as of this package's build — see AGENTS.md "Ontology mapping"
+before trusting these as final.
+
+## Tools
+
+Eight MCP tools, one FastMCP server (`bellwether-mcp` console script):
+`cmc_listings`, `cmc_quotes`, `cmc_global_metrics`, `fred_macro_series_aliases`,
+`fred_series_observations`, `fred_series_observations_asof`,
+`fred_series_vintage_dates`, `fomc_calendar_list`.
+
+Every tool is keyless except `cmc_*` and `fred_*`, whose credentials are
+resolved server-side through `agent_connector_sdk.credentials`
+(`BELLWETHER_CMC_API_KEY`, `BELLWETHER_FRED_API_KEY`) — never accepted as a
+tool argument. `fomc_calendar_list` reads a packaged, curated, sourced dataset
+and needs no credential and no network.
+
+See [`AGENTS.md`](AGENTS.md) for architecture, the ontology-mapping
+authority, the FOMC dataset's provenance, rate limits, and commands.

bellwether_mcp-1.3.1/bellwether_mcp/__init__.py

@@ -0,0 +1,22 @@
+"""bellwether-mcp: crypto discovery, Fed macro series and the FOMC calendar.
+
+Wraps CoinMarketCap (crypto discovery/rankings/market caps — not a
+venue-specific OHLCV feed; see ``api/coinmarketcap.py``), FRED/ALFRED (Fed
+macro and liquidity series with point-in-time vintages), and a curated,
+sourced FOMC decision calendar as an MCP tool surface and, through
+``agent-connector-sdk``'s declarative ``mcp_tool`` source adapter, as
+bounded, checkpointed ingestion streams intended for the ``finance-v1``
+world-model ontology once EG's parallel ``feat/finance-core`` publishes its
+class/property names (see ``bellwether_mcp/ontology/mappings/source.yaml``
+for the current, provisional mapping and how to update it).
+
+This package never calls epistemic-graph directly: extraction rides an
+in-process MCP session over its own tool surface, and delivery to a live
+graph is owned by ``agent_connector_sdk.runner``/``sinks``.
+"""
+
+from __future__ import annotations
+
+from bellwether_mcp._version import __version__
+
+__all__ = ["__version__"]

bellwether_mcp-1.3.1/bellwether_mcp/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m bellwether_mcp`` runs the MCP server."""
+
+from __future__ import annotations
+
+from bellwether_mcp.mcp_server import mcp_server
+
+if __name__ == "__main__":
+    mcp_server()

bellwether_mcp-1.3.1/bellwether_mcp/_version.py

@@ -0,0 +1,5 @@
+"""Single-source package version."""
+
+from __future__ import annotations
+
+__version__ = "1.3.1"

bellwether_mcp-1.3.1/bellwether_mcp/api/__init__.py

@@ -0,0 +1,3 @@
+"""Thin async vendor API clients — pure functions, no MCP/adapter concerns."""
+
+from __future__ import annotations

bellwether_mcp-1.3.1/bellwether_mcp/api/coinmarketcap.py

@@ -0,0 +1,125 @@
+"""CoinMarketCap Pro API: crypto discovery, rankings, market caps (EH-412).
+
+https://coinmarketcap.com/api/documentation/pro-api-reference/cryptocurrency.
+CMC is a discovery/caps source, not a venue-specific OHLCV feed — its general
+historical OHLCV endpoint documents hourly/daily coverage only and must not
+be assumed to supply minute-level exchange candles (that role stays with
+emerald-exchange's venue backends). This client therefore exposes listings,
+per-symbol quotes and global market metrics only.
+
+Every endpoint requires ``X-CMC_PRO_API_KEY`` — there is no keyless CMC
+endpoint, including the free "Basic" plan.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+__all__ = ["get_global_metrics", "get_quotes", "list_listings"]
+
+
+def _quote_usd(item: dict[str, Any]) -> dict[str, Any]:
+    usd = item.get("quote", {}).get("USD", {})
+    return {
+        "price_usd": usd.get("price"),
+        "market_cap_usd": usd.get("market_cap"),
+        "volume_24h_usd": usd.get("volume_24h"),
+        "percent_change_24h": usd.get("percent_change_24h"),
+        "percent_change_7d": usd.get("percent_change_7d"),
+        "last_updated": usd.get("last_updated"),
+    }
+
+
+def _listing_record(item: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "cmc_id": str(item["id"]),
+        "name": item.get("name", ""),
+        "symbol": item.get("symbol", ""),
+        "cmc_rank": item.get("cmc_rank"),
+        "circulating_supply": item.get("circulating_supply"),
+        "total_supply": item.get("total_supply"),
+        "max_supply": item.get("max_supply"),
+        **_quote_usd(item),
+    }
+
+
+async def list_listings(
+    client: httpx.AsyncClient, *, api_key: str, start: int, limit: int
+) -> dict[str, Any]:
+    """One page of the latest cryptocurrency listings, ranked by market cap.
+
+    ``start`` is a 0-based offset (this package's own convention, matching
+    ``ToolPreset(pagination="offset")``'s zero-based semantics) — translated
+    to CMC's native 1-based ``start`` query parameter internally, so a caller
+    never has to know CMC's API is 1-indexed.
+
+    CMC's listings endpoint reports no reliable total count, so callers page
+    until a page shorter than ``limit`` comes back (``total`` is always
+    ``None`` here).
+    """
+    response = await client.get(
+        "/v1/cryptocurrency/listings/latest",
+        headers={"X-CMC_PRO_API_KEY": api_key},
+        params={"start": start + 1, "limit": limit, "convert": "USD"},
+    )
+    response.raise_for_status()
+    payload = response.json()
+    items = [_listing_record(item) for item in payload.get("data", [])]
+    return {"items": items, "offset": start, "limit": limit, "total": None}
+
+
+async def get_quotes(
+    client: httpx.AsyncClient, *, api_key: str, symbols: str
+) -> dict[str, Any]:
+    """Latest quote(s) for one or more comma-separated symbols (e.g. ``"BTC,ETH"``)."""
+    response = await client.get(
+        "/v1/cryptocurrency/quotes/latest",
+        headers={"X-CMC_PRO_API_KEY": api_key},
+        params={"symbol": symbols, "convert": "USD"},
+    )
+    response.raise_for_status()
+    payload = response.json()
+    data = payload.get("data", {})
+    items = []
+    for symbol, entries in data.items():
+        # CMC returns either one object or a list when a symbol maps to
+        # several listed assets (rare ticker collisions).
+        for item in entries if isinstance(entries, list) else [entries]:
+            items.append({"symbol": symbol, **_listing_record(item)})
+    return {"items": items, "offset": 0, "limit": len(items), "total": len(items)}
+
+
+async def get_global_metrics(
+    client: httpx.AsyncClient, *, api_key: str
+) -> dict[str, Any]:
+    """Aggregate market metrics: total market cap, BTC/ETH dominance, volume.
+
+    A macro/liquidity gauge for the crypto market as a whole (EH-422) —
+    distinct from any single asset's quote.
+    """
+    response = await client.get(
+        "/v1/global-metrics/quotes/latest",
+        headers={"X-CMC_PRO_API_KEY": api_key},
+        params={"convert": "USD"},
+    )
+    response.raise_for_status()
+    payload = response.json().get("data", {})
+    usd = payload.get("quote", {}).get("USD", {})
+    return {
+        "items": [
+            {
+                "id": "global",
+                "active_cryptocurrencies": payload.get("active_cryptocurrencies"),
+                "btc_dominance": payload.get("btc_dominance"),
+                "eth_dominance": payload.get("eth_dominance"),
+                "total_market_cap_usd": usd.get("total_market_cap"),
+                "total_volume_24h_usd": usd.get("total_volume_24h"),
+                "last_updated": usd.get("last_updated"),
+            }
+        ],
+        "offset": 0,
+        "limit": 1,
+        "total": 1,
+    }

bellwether_mcp-1.3.1/bellwether_mcp/api/fomc_calendar.py

@@ -0,0 +1,97 @@
+"""The FOMC decision calendar as sourced records (EH-412).
+
+The Federal Reserve does not publish its meeting calendar or decisions as a
+JSON API — only as HTML
+(https://www.federalreserve.gov/monetarypolicy/fomccalendars.htm) and one
+press-release page per meeting. This module therefore reads a curated,
+versioned dataset (``bellwether_mcp/connectors/fomc_meetings.json``) instead
+of scraping HTML at call time. Every record carries the Federal Reserve's own
+press-release URL as ``source_url`` — never asserted as one of this package's
+own findings. See ``AGENTS.md``'s "FOMC dataset provenance" section for how
+and when this dataset was verified, and how to extend it.
+
+No network I/O happens here; loading is a pure, cached read of packaged data.
+"""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from importlib import resources
+from typing import Any
+
+from bellwether_mcp.errors import UnknownFomcOutcomeFilterError
+
+__all__ = ["VALID_OUTCOMES", "list_meetings", "load_meetings"]
+
+VALID_OUTCOMES = frozenset({"hike", "cut", "hold"})
+
+
+@lru_cache(maxsize=1)
+def load_meetings() -> tuple[dict[str, Any], ...]:
+    """The full curated FOMC meeting dataset, oldest first, each record sourced."""
+    raw = json.loads(
+        resources.files("bellwether_mcp.connectors")
+        .joinpath("fomc_meetings.json")
+        .read_text()
+    )
+    meetings = tuple(raw["meetings"])
+    for meeting in meetings:
+        if meeting["outcome"] not in VALID_OUTCOMES:
+            raise ValueError(
+                f"fomc_meetings.json has an invalid outcome {meeting['outcome']!r} "
+                f"for {meeting['decision_date']!r} (expected one of {sorted(VALID_OUTCOMES)})"
+            )
+    return meetings
+
+
+def _record(meeting: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "id": meeting["decision_date"],
+        "meeting_start_date": meeting["meeting_start_date"],
+        "decision_date": meeting["decision_date"],
+        "outcome": meeting["outcome"],
+        "bps_change": meeting["bps_change"],
+        "target_range_low_pct": meeting["target_range_low_pct"],
+        "target_range_high_pct": meeting["target_range_high_pct"],
+        "source_url": meeting["source_url"],
+    }
+
+
+def list_meetings(
+    *,
+    since: str = "",
+    until: str = "",
+    outcome: str = "",
+    offset: int = 0,
+    limit: int = 100,
+) -> dict[str, Any]:
+    """Sourced FOMC decision records, optionally filtered by date range/outcome.
+
+    Args:
+        since: inclusive ISO ``decision_date`` lower bound (``""`` = no bound).
+        until: inclusive ISO ``decision_date`` upper bound (``""`` = no bound).
+        outcome: one of ``"hike"``, ``"cut"``, ``"hold"``, or ``""`` for all.
+
+    Raises:
+        UnknownFomcOutcomeFilterError: ``outcome`` is not empty and not one of
+            :data:`VALID_OUTCOMES`.
+    """
+    if outcome and outcome not in VALID_OUTCOMES:
+        raise UnknownFomcOutcomeFilterError(
+            f"outcome {outcome!r} is not one of {sorted(VALID_OUTCOMES)}"
+        )
+    matches = [
+        m
+        for m in load_meetings()
+        if (not since or m["decision_date"] >= since)
+        and (not until or m["decision_date"] <= until)
+        and (not outcome or m["outcome"] == outcome)
+    ]
+    page = matches[offset : offset + limit]
+    return {
+        "items": [_record(m) for m in page],
+        "offset": offset,
+        "limit": limit,
+        "total": len(matches),
+    }

bellwether_mcp-1.3.1/bellwether_mcp/api/fred.py

@@ -0,0 +1,149 @@
+"""FRED + ALFRED (point-in-time vintages): Fed macro and liquidity series (EH-412/EH-422).
+
+https://fred.stlouisfed.org/docs/api/fred/series_observations.html
+https://fred.stlouisfed.org/docs/api/fred/series_vintagedates.html
+
+ALFRED is not a separate host or API — it is the *same* FRED REST API's
+``realtime_start``/``realtime_end`` parameters on ``series/observations``,
+which select "the data as it was known/published as of this date" instead of
+today's latest revision. This client exposes that explicitly
+(:func:`get_observations_asof`) rather than only ever returning today's
+revised values, so a caller can reconstruct what a point-in-time backtest
+would actually have seen (no look-ahead into later data revisions).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+__all__ = ["get_observations", "get_observations_asof", "get_vintage_dates"]
+
+
+def _parse_observation_value(raw: Any) -> float | None:
+    """FRED encodes a missing observation as the literal string ``"."``."""
+    if raw is None or raw == ".":
+        return None
+    return float(raw)
+
+
+def _observation_record(series_id: str, obs: dict[str, Any]) -> dict[str, Any]:
+    realtime_start = obs.get("realtime_start", "")
+    date = obs.get("date", "")
+    return {
+        # Unique within one call's vintage window; a single series_id+date can
+        # recur across different realtime_start vintages, so the record
+        # identity folds in the vintage too.
+        "observation_id": f"{series_id}:{date}:{realtime_start}",
+        "series_id": series_id,
+        "date": date,
+        "value": _parse_observation_value(obs.get("value")),
+        "realtime_start": realtime_start,
+        "realtime_end": obs.get("realtime_end", ""),
+    }
+
+
+async def get_observations(
+    client: httpx.AsyncClient,
+    *,
+    api_key: str,
+    series_id: str,
+    offset: int = 0,
+    limit: int = 1000,
+    realtime_start: str | None = None,
+    realtime_end: str | None = None,
+) -> dict[str, Any]:
+    """One page of a FRED series' observations, latest-revision by default.
+
+    Pass ``realtime_start``/``realtime_end`` (``YYYY-MM-DD``) to pin the
+    vintage instead of today's latest revision — see
+    :func:`get_observations_asof` for the common "as of one date" case.
+    """
+    params: dict[str, Any] = {
+        "series_id": series_id,
+        "api_key": api_key,
+        "file_type": "json",
+        "offset": offset,
+        "limit": limit,
+        "sort_order": "asc",
+    }
+    if realtime_start:
+        params["realtime_start"] = realtime_start
+    if realtime_end:
+        params["realtime_end"] = realtime_end
+    response = await client.get("/series/observations", params=params)
+    response.raise_for_status()
+    payload = response.json()
+    items = [
+        _observation_record(series_id, obs) for obs in payload.get("observations", [])
+    ]
+    return {
+        "items": items,
+        "offset": offset,
+        "limit": limit,
+        "total": payload.get("count"),
+    }
+
+
+async def get_observations_asof(
+    client: httpx.AsyncClient,
+    *,
+    api_key: str,
+    series_id: str,
+    vintage_date: str,
+    offset: int = 0,
+    limit: int = 1000,
+) -> dict[str, Any]:
+    """Point-in-time (ALFRED) observations: the series exactly as known on ``vintage_date``.
+
+    A pure convenience over :func:`get_observations` pinning both
+    ``realtime_start`` and ``realtime_end`` to the same date.
+    """
+    return await get_observations(
+        client,
+        api_key=api_key,
+        series_id=series_id,
+        offset=offset,
+        limit=limit,
+        realtime_start=vintage_date,
+        realtime_end=vintage_date,
+    )
+
+
+async def get_vintage_dates(
+    client: httpx.AsyncClient,
+    *,
+    api_key: str,
+    series_id: str,
+    offset: int = 0,
+    limit: int = 1000,
+) -> dict[str, Any]:
+    """Every date this series' data was revised/published — the ALFRED vintage list.
+
+    Feed any entry back into :func:`get_observations_asof` as ``vintage_date``
+    to reconstruct that exact point-in-time view.
+    """
+    response = await client.get(
+        "/series/vintagedates",
+        params={
+            "series_id": series_id,
+            "api_key": api_key,
+            "file_type": "json",
+            "offset": offset,
+            "limit": limit,
+        },
+    )
+    response.raise_for_status()
+    payload = response.json()
+    dates = payload.get("vintage_dates", [])
+    items = [
+        {"vintage_id": f"{series_id}:{d}", "series_id": series_id, "vintage_date": d}
+        for d in dates
+    ]
+    return {
+        "items": items,
+        "offset": offset,
+        "limit": limit,
+        "total": payload.get("count"),
+    }