io.github.ojhermann-org/ferric-fred-mcp

ferric-fred

A strongly-typed Rust client for FRED — the Federal Reserve Economic Data service from the Federal Reserve Bank of St. Louis — plus a CLI (with TUI charts) and an MCP server built on top of it.

ferric (iron oxide → rust) + FRED. Iron-clad, typed access to economic data.

Workspace

A Cargo workspace of three crates — each with its own README (the crates.io / docs.rs landing page) that carries the full usage detail:

Published versions (these badges are the source of truth — the crates version independently, so they can drift out of lockstep):

Consumers depend on the library by workspace path, so a breaking change in the library cannot compile-pass its consumers without updating them — that compile-time coupling is the primary "stay in sync" guarantee (versions are managed on top; see the ADRs).

What it covers

The library wraps all of FRED's read endpoints — series and observations (including ALFRED point-in-time / vintage data via a real-time window), search, categories, releases (including the nested release-table tree, with optional inline observation values), sources, and tags — plus the GeoFRED / Maps API (regional data and the geographic shape files to map it, ADR-0025) — behind ergonomic builders, with newtype identifiers, typed enums for FRED's closed value sets, a non-panicking error taxonomy, and auto-pagination (Paginate::send_all walks an endpoint to exhaustion, Paginate::stream yields lazily; --all on the CLI). See ADR-0020 and ADR-0021.

GeoFRED support spans the library, CLI (fred geofred), and MCP (get_regional_data, get_series_data, get_series_group) layers. The one exception is the geographic shapes/file endpoint, which is library/CLI-only — a large projected-GeoJSON blob is poor ergonomics for an MCP tool caller (ADR-0025).

Pick an entry point:

• Library — cargo add ferric-fred; typed async access from your own code. See the crate README and docs.rs.
• CLI (fred) — cargo install ferric-fred-cli; search, show metadata, print or chart observations in the terminal, browse categories, releases, sources, and tags, and pull GeoFRED regional data and map shapes (fred geofred). See the crate README or fred <command> --help.
• MCP server (fred-mcp) — cargo install ferric-fred-mcp; 34 tools over stdio covering the same read surface, for MCP-capable clients (ADR-0010). Each tool declares input and output schemas plus behavioural annotations (ADR-0023). See the crate README.

The MCP server is listed and scored on Glama:

Development

A Nix flake provides a reproducible toolchain (nix develop, or direnv allow once), but the project builds with a plain Rust toolchain too — Nix supplies the environment, not the build (ADR-0008).

Contributor setup, the fmt/clippy/test/prose gate, the tracked git hooks, and the workflow for adding an endpoint live in CONTRIBUTING.md. CI (ci.yml) runs that same offline gate on every push and PR; a dormant live.yml runs the live FRED tests once an Infisical machine identity is configured (ADR-0016).

Benchmarks

Performance tooling from the org Tech Radar pilot (ADR-0026, issue #42):

# Deserialization microbenches (divan) — the observations parse hot path.
cargo bench -p ferric-fred --bench deserialization
# Same workload under criterion (the divan-vs-criterion baseline).
cargo bench -p ferric-fred --bench deserialization_criterion

# Headless `fred chart` render cost (divan + ratatui TestBackend, no tty).
cargo bench -p ferric-fred-cli --bench render

# CLI wall-clock timing (hyperfine): startup + a live fetch-and-render.
# The fetch benchmark needs FRED_API_KEY; startup runs offline.
scripts/bench-cli.sh                    # add --json DIR to export hyperfine JSON

CI keeps the benches compiling on every PR (cargo bench --no-run), and a separate bench.yml uploads results to Bencher (hosted project ferric-fred) to track them over time and flag regressions on PRs. Bencher has no divan adapter, so it ingests the criterion mirror (rust_criterion) and hyperfine startup (shell_hyperfine); divan stays the fast local harness. BENCHER_API_TOKEN comes from Infisical, so the upload is a no-op until the machine identity is configured — see ADR-0026.

Secrets

The client reads a free FRED API key from the FRED_API_KEY environment variable (get one at https://fredaccount.stlouisfed.org/apikeys). Locally, secrets are injected via Infisical + direnv (ADR-0009):

cp .envrc.example .envrc     # local, git-ignored entry point
infisical login             # user auth (opens a browser)
infisical init              # link this dir → project
direnv allow                # load the shell + inject secrets on cd-in

Store the key with infisical secrets set FRED_API_KEY="…" --env=dev --path=/shared. No Infisical? Just set it directly in your git-ignored .envrc: export FRED_API_KEY="…" — the library only reads the env var and has no dependency on Infisical.

Architecture decisions

Design decisions are recorded as ADRs in docs/adr/. Start with the index.

License

Dual-licensed under MIT OR Apache-2.0, at your option — the Rust ecosystem default (ADR-0006). See LICENSE-MIT and LICENSE-APACHE. Unless you state otherwise, any contribution you submit is licensed under the same dual terms (see CONTRIBUTING.md).

This covers our code; FRED data itself is subject to the St. Louis Fed's terms of use, and you supply your own API key — the project ships no data and no key.