fxrates

fxrates

fxrates は Frankfurter API から外国為替データを取得します。対応通貨、最新レート、過去の特定の日または期間のレート、取得したレートを使ってローカルで計算する通貨換算を確認できます。1 つのバイナリで、コマンドラインインターフェースと stdio MCP サーバーの両方を提供します。

API キーは不要です。キーなしで利用できるため、何も設定せずに fxrates を使えます。API のベース URL は FRANKFURTER_API_URL で上書きできます。設定されていない場合、呼び出し先は https://api.frankfurter.dev/v1 です。

インストール

npx @reneturcios/fxrates currencies

または、コンテナイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/fxrates

コンテナはデフォルトで MCP サーバーとして起動します（下記を参照）。CLI として使うには、CLI 引数を渡してください。

CLI

fxrates currencies
fxrates latest --base USD --symbols EUR,GBP
fxrates convert 25 EUR USD
fxrates historical 2024-05-01 --base EUR --symbols USD
fxrates range 2024-05-01 2024-05-03 --base EUR
fxrates convert-on 2020-01-02 100 USD EUR
fxrates greet Ada

fxrates --version

レート関連のコマンドは、上流 API の JSON ペイロードを出力します。通貨換算コマンドは、API が日付を返す場合、amount、from、to、rate、converted、date を含む JSON オブジェクトを出力します。終了コードは、成功時が 0、呼び出しに失敗した場合（上流 API エラーを含む）が 1、使用方法に誤りがある場合が 2 です。

通貨換算はローカルで計算します。必要な単一のレートを取得して乗算します。結果は小数第 6 位で丸め、最大 6 桁の小数に整えます。手数料、スプレッド、追加の丸めはありません。

MCP サーバー

1 つのバイナリで、両方のインターフェースを提供します。mcp サブコマンドで stdio MCP サーバーを起動します。

npx -y @reneturcios/fxrates mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "fxrates": {
      "command": "npx",
      "args": ["-y", "@reneturcios/fxrates", "mcp"]
    }
  }
}

サーバーの接続先を別の Frankfurter 互換ホストにするには、このサーバーのクライアント設定の env に FRANKFURTER_API_URL を追加します。

ツール

ツール	入力	戻り値
get_supported_currencies	（なし）	対応する通貨コードと名称のマップ。
get_latest_exchange_rates	base、symbols（どちらも省略可）	最新レートのペイロード。
convert_currency_latest	amount、from、to（すべて必須）	最新レートによる換算結果：金額、通貨ペア、レート、換算後の値、日付。
get_historical_exchange_rates	date または start_date／end_date、および省略可能な base、symbols	特定の日または期間のレート。
convert_currency_specific_date	date、amount、from、to（すべて必須）	指定日のレートによる換算結果。
greet	name（省略可）	あいさつ文字列。内部テスト用です。

日付には YYYY-MM-DD を使用します。symbols は USD,GBP のようなカンマ区切りのリストです。通貨の引数には EUR や USD などのコードを指定します。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

ライセンス

MIT — LICENSE を参照してください。