ferric-fred-mcp

ferric-fred

一个类型安全性强的 Rust 客户端，用于访问 FRED——圣路易斯联邦储备银行提供的联邦储备经济数据服务——此外还包含一个带 TUI 图表的 CLI，以及基于它构建的 MCP 服务。

ferric（氧化铁 → rust）+ FRED。坚如铁石、类型安全的经济数据访问。

工作区

一个包含 3 个 Crate 的 Cargo 工作区——每个 Crate 都有自己的 README（即 crates.io / docs.rs 展示页），其中包含完整的用法说明：

Crate	二进制文件	说明	详情
ferric-fred	—	类型安全性强的异步 FRED 客户端	README · docs.rs
ferric-fred-cli	fred	带有 ratatui TUI 图表的命令行工具	README
ferric-fred-mcp	fred-mcp	向 MCP 客户端提供 FRED 访问能力的 MCP 服务	README

已发布的版本（这些徽章是权威信息来源——各个 Crate 独立发布版本，因此版本可能不同步）：

使用者通过工作区路径依赖此库，这样一来，库中的破坏性变更若未同步更新使用者，就无法通过编译——这种编译期耦合是确保“保持同步”的主要保障（版本管理在此基础上进行；详见 ADR）。

涵盖范围

该库封装了 FRED 的所有读取端点——序列和观测值 （包括通过实时窗口获取 ALFRED 的时间点 / 版本数据）、 搜索、类别、发布（包括嵌套的发布表树，可选择内嵌观测值）、来源 和标签——以及 GeoFRED / Maps API（区域数据和用于绘制地图的地理形状 文件，ADR-0025），并提供易用的构建器、新类型标识符、 针对 FRED 封闭值集的类型化枚举、不致引发恐慌的错误分类，以及 自动分页 （Paginate::send_all 遍历端点直至全部取完，Paginate::stream 惰性地产出结果；CLI 中的 --all）。参见 ADR-0020 和 ADR-0021。

GeoFRED 支持涵盖 库、CLI（fred geofred）和 MCP （get_regional_data、get_series_data、get_series_group）层。唯一的 例外是地理 shapes/file 端点，它仅支持库 / CLI——对于 MCP 工具调用者来说， 大型投影 GeoJSON 数据块并不易用 （ADR-0025）。

选择一个入口：

• 库 — cargo add ferric-fred；在你自己的代码中进行类型化异步访问。 参见 crate README 和 docs.rs。
• CLI（fred）— cargo install ferric-fred-cli；搜索、查看元数据、 在终端中打印或绘制图表展示观测值、浏览类别、 发布、来源和标签，并获取 GeoFRED 区域数据和地图形状 （fred geofred）。参见 crate README 或运行 fred <command> --help。
• MCP 服务（fred-mcp）— cargo install ferric-fred-mcp；通过 stdio 提供 34 个工具， 涵盖相同的读取范围，供支持 MCP 的客户端使用（ADR-0010）。 每个工具都声明输入和输出架构，以及行为注解 （ADR-0023）。参见 crate README。

该 MCP 服务已在 Glama 上列出并评分：

开发

Nix flake 提供可复现的工具链（运行 nix develop，或只需运行一次 direnv allow），但该项目也可通过普通 Rust 工具链构建——Nix 提供的是 环境，而非构建过程（ADR-0008）。

贡献者设置、fmt/clippy/test/文档门禁、已跟踪的 git 钩子，以及添加端点的 工作流，详见 CONTRIBUTING.md。 CI（ci.yml）会在每次推送和 PR 上运行相同的离线门禁；休眠的 live.yml 会在配置好 Infisical 机器身份后运行实时 FRED 测试 （ADR-0016）。

基准测试

来自组织 Tech Radar 试点的性能工具 （ADR-0026，问题 #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 会在每个 PR 上确保基准测试仍可编译（cargo bench --no-run），另有一个 单独的 bench.yml 会将结果上传到 Bencher（托管项目 ferric-fred），以便长期跟踪并标记 PR 中的性能回退。 Bencher 没有 divan 适配器，因此会导入 criterion 镜像 （rust_criterion）和 hyperfine 启动测试（shell_hyperfine）；divan 仍是 快速的本地测试框架。BENCHER_API_TOKEN 来自 Infisical，因此在配置 机器身份之前，上传操作不会执行任何操作——参见 ADR-0026。

密钥

客户端会从 FRED_API_KEY 环境变量读取免费的 FRED API 密钥（可在 https://fredaccount.stlouisfed.org/apikeys 获取）。本地密钥通过 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

使用 infisical secrets set FRED_API_KEY="…" --env=dev --path=/shared 存储密钥。 没有 Infisical？直接在已加入 Git 忽略列表的 .envrc 中设置即可： export FRED_API_KEY="…"——此库只读取环境变量，不依赖 Infisical。

架构决策

设计决策以 ADR 的形式记录在 docs/adr/ 中。请从 索引开始。

许可证

采用 MIT OR Apache-2.0 双重许可，你可以自行选择——这是 Rust 生态系统 的默认做法（ADR-0006）。请参阅 LICENSE-MIT 和 LICENSE-APACHE。除非你另有说明，否则你提交的任何 贡献均遵循相同的双重许可条款（参见 CONTRIBUTING.md）。

这适用于我们的代码；FRED 数据本身受 St. Louis Fed 使用条款约束，你需要提供自己的 API 密钥——本项目不附带数据或密钥。