ferric-fred-mcp

ferric-fred

FRED 用の、強い型付けを備えた Rust クライアントです。FRED はセントルイス連邦準備銀行が提供する連邦準備制度の経済データサービスです。さらに、CLI（TUI チャート付き）と、その上に構築された MCP サーバーも提供します。

ferric（酸化鉄 → rust）＋ FRED。経済データに鉄壁の型安全なアクセスを提供します。

ワークスペース

3 つのクレートで構成される Cargo ワークスペースです。各クレートには、利用方法の詳細をすべて記載した独自の README（crates.io ／ docs.rs のランディングページ）があります。

クレート	バイナリ	概要	詳細
ferric-fred	—	強い型付けを備えた非同期 FRED クライアント	README · docs.rs
ferric-fred-cli	fred	ratatui の TUI チャートを備えたコマンドラインツール	README
ferric-fred-mcp	fred-mcp	MCP クライアントに FRED を公開する MCP サーバー	README

公開済みのバージョン（これらのバッジが正しい情報源です。各クレートは独立してバージョン管理されるため、足並みがそろわなくなる場合があります）：

利用側は、ライブラリをワークスペースのパス指定で依存関係に加えます。そのため、利用側を更新しない限り、ライブラリの破壊的変更があっても利用側はコンパイルを通過できません。このコンパイル時の結び付きが、「同期を保つ」ための主要な保証です（バージョンはその上で管理します。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 のみで利用できます。 大きな投影済み GeoJSON のデータは、MCP ツールの呼び出し元にとって扱いにくいためです （ADR-0025）。

利用する入口を選んでください。

• ライブラリ — cargo add ferric-fred。自分のコードから型付きの非同期アクセスができます。 クレートの README と docs.rs を参照してください。
• CLI（fred）— cargo install ferric-fred-cli。検索、メタデータの表示、 ターミナルでの観測値の出力やグラフ表示、カテゴリ、リリース、 ソース、タグの閲覧、GeoFRED の地域データと地図用シェープの取得ができます （fred geofred）。クレートの README または fred <command> --help を参照してください。
• MCP サーバー（fred-mcp）— cargo install ferric-fred-mcp。MCP 対応クライアント向けに、 同じ読み取り範囲をカバーする 34 個のツールを stdio 経由で提供します (ADR-0010)。 各ツールは入力と出力のスキーマ、および動作に関する注釈を宣言します (ADR-0023)。クレートの README を参照してください。

MCP サーバーは Glama に掲載され、 評価されています。

開発

Nix flake により再現可能なツールチェーンを利用できます（nix develop、または一度だけ direnv allow を実行します）。ただし、このプロジェクトは通常の Rust ツールチェーンでもビルドできます。 Nix が提供するのは環境であり、ビルドそのものではありません （ADR-0008）。

コントリビューター向けのセットアップ、fmt/clippy/test/文章のゲート、追跡対象の git フック、 エンドポイント追加のワークフローについては、CONTRIBUTING.md を参照してください。 CI（ci.yml）は、すべての push と PR で同じオフラインゲートを実行します。休止中の live.yml は、Infisical のマシン ID が設定されると、ライブ FRED テストを実行します （ADR-0016）。

ベンチマーク

組織の Tech Radar パイロットによるパフォーマンス計測ツール （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 はすべての PR でベンチマークのコンパイルを確認します（cargo bench --no-run）。別の bench.yml は結果を Bencher（ホストされた プロジェクト ferric-fred）にアップロードし、経時的に追跡して PR での性能低下を検出します。 Bencher には divan アダプターがないため、criterion のミラー （rust_criterion）と hyperfine による起動時間（shell_hyperfine）を取り込みます。 divan は高速なローカルハーネスとして引き続き使用します。BENCHER_API_TOKEN は Infisical から取得するため、 マシン ID が設定されるまではアップロードは何も行いません。詳しくは ADR-0026 を参照してください。

シークレット

クライアントは、環境変数 FRED_API_KEY から無料の FRED API key を読み取ります （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 には依存しません。

アーキテクチャ上の決定

設計上の決定は、docs/adr/ に ADR として記録されています。 まずはインデックスをご覧ください。

ライセンス

お好みに応じて MIT OR Apache-2.0 のデュアルライセンスを適用します。これは Rust エコシステムの標準です（ADR-0006）。LICENSE-MIT および LICENSE-APACHE をご覧ください。特に明記がない限り、 提出された貢献は同じデュアルライセンス条件でライセンスされます（ CONTRIBUTING.md をご覧ください）。

これは 当プロジェクトのコード に適用されます。FRED のデータ自体には St. Louis Fed の利用規約が適用され、 API キーはご自身で用意してください。このプロジェクトにはデータもキーも含まれていません。