serieslib

serieslib

serieslib は、ElKassabgi データファミリーのホスト型 MCP サーバーへの、薄いローカルブリッジです。このサーバーは 1 つのエンドポイントで 3 つのライブラリを提供します。数百の公式ソースから集めた数十億件の時系列を収録した経済データカタログ、米国株の 1 分足データと事前計算済みの学術変数を収録した高頻度ライブラリ、そして特許レベルのイノベーション指標を収録した知的財産ライブラリです。

このブリッジはデータを保持せず、計算も行いません。ライブエンドポイントから取得したツールリストをそのままローカルで提供し、各ツール呼び出しを上流へ転送して、結果を変更せずに返します。検索、メタデータ、ソース一覧、更新状況、ステータスの各ツールは上流で無料です。ダウンロードの一部では、データファミリー独自の無料 API キーが必要ですが、これは上流側で管理されます。このクライアントは独自の認証情報を送信せず、get_auth_status は上流接続のキーの状態を報告します。

ツール

• search_econ_series — 自由記述（query、必須）で経済データカタログを検索します。省略可能な項目：1 つのソース ID に絞り込む source、limit（1～50、既定値 15）、ページネーション用の offset、およびソース公式の翻訳タイトルがある場合に使用する lang（en、ar、es、fr、ru、zh）。ほかのツールで使う時系列 ID を返します。
• get_econ_series — 1 つの時系列を、日付／値の行と引用情報およびライセンスとともにダウンロードします。必須項目：series_id。省略可能な項目：長い時系列の期間を指定する date_from／date_to（YYYY-MM-DD）、および max_rows（10～2000、既定値 400）。
• get_econ_series_metadata — 1 つの時系列の完全なメタデータを取得します（series_id、必須）。タイトル、頻度、地域、単位、商用利用の可否を含むライセンス、帰属表示、および収録期間が含まれます。
• list_econ_sources — ライセンスとともに、カタログのソース（統計局、金融当局、政府間組織、研究データセット）を列挙します。省略可能な項目：ソース ID または名前を大文字小文字を区別せずに絞り込む contains。
• get_data_freshness — 上流アップデーターの台帳に基づく、ソースごとの更新状況を取得します。最終成功更新日時、データの最新時点、古いデータや失敗を示すフラグが含まれます。省略可能な項目：単一のソースを指定する source。
• get_econ_bundle_manifest — 引用可能な Frictionless 形式のバンドルマニフェストを作成します。明示的な時系列 ID を最大 50 件指定する ids、または小規模な 1 つのソースに含まれる全時系列（最大 1,000 件）を指定する source を使用できます。解決できない ID は報告され、削除されません。
• get_hf_download_link — 高頻度ライブラリの認証済みダウンロード手順を取得します。必須項目：ticker（例：AAPL）。省略可能な項目：dataset（bars、variables、quality のいずれか、既定値は bars）、version（clean または raw、既定値は clean）、および format（parquet または csv、既定値は parquet。csv は bars のみ適用されます）。ファイルには銘柄の全バーが含まれます。データはインラインで返されず、ユーザー自身のコードで取得します。
• get_hf_variables_dictionary — 事前計算済みの 25 個の学術変数について、公開されている正確な定義と数式を取得します。引数はありません。
• list_ip_bundles — IP ライブラリの、スナップショットに固定された特許およびイノベーションのバンドルを、サイズ、ビンテージ、ダウンロードパスとともに一覧表示します。引数はありません。
• get_ip_download_link — 1 つの IP バンドルの認証済みダウンロード手順を取得します。必須項目：file（patent_measures.parquet または assignee_year.parquet）。省略可能な項目：最新ではなく特定のスナップショットに固定する vintage。
• get_family_status — 3 つすべてのライブラリの最新統計とデータの更新状況を取得します。引数はありません。
• get_auth_status — 上流接続にデータファミリーの API キーが設定されているか（マスク表示。キー自体は決して表示されません）、およびキーの追加方法を確認します。引数はありません。

設定

• ELKASSABGI_MCP_URL（省略可能）— 上流エンドポイントを上書きします。既定値は https://elkassabgidata-mcp.elkassabgi.workers.dev/mcp です。 （この上書き用フックは、今回の再構築で独自に実装したものとして明記しています。）

転送の仕組み

最初のツール呼び出し時に、クライアントは上流とのストリーミング可能な HTTP セッションを開きます。JSON-RPC の initialize リクエスト（protocolVersion 2025-03-26、clientInfo name serieslib）、続いて notifications/initialized 通知を送り、その後、呼び出し元の引数を変更せずに含めた tools/call リクエストを送信します。上流が Mcp-Session-Id ヘッダーを付けて initialize に応答すると、その値はセッションの以降のすべての リクエストに付与され、プロセスの存続期間中、同じセッションが再利用されます。 応答は通常の JSON または サーバー送信イベントとして届く場合があり、どちらも読み取られます。

上流からの成功結果は、上流が設定した isError フラグも含め、 そのまま返されます。 JSON-RPC エラー、2xx 以外のステータス、読み取り不能な応答、 完了できないリクエストなどの失敗は、テキストが serieslib error: で始まる isError 結果として返されます（この表現は この再構築で独自に付与したラベルです）。

CLI

各ツールは、JSON 引数文字列を 1 つ受け取るサブコマンドとしても実行できます （引数を取らないツールでは省略します）。

npx @reneturcios/serieslib search_econ_series '{"query":"germany inflation"}'
npx @reneturcios/serieslib get_econ_series_metadata '{"series_id":"worldbank:NY.GDP.MKTP.CD:DEU"}'
npx @reneturcios/serieslib list_econ_sources
npx @reneturcios/serieslib --version

終了コード：成功時は 0、isError 結果の場合は 1、使用方法が誤っている場合は 2 です。

MCP サーバー

npx -y @reneturcios/serieslib mcp

MCP クライアントの設定：

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

Docker

docker run -i ghcr.io/cloudcorprecords/serieslib
docker run --rm ghcr.io/cloudcorprecords/serieslib --version

コンテナのデフォルトコマンドは mcp であるため、最初の形式は stdio MCP サーバーとして動作します。それ以外の引数は通常どおり CLI に渡されます。

開発

npm install
npm run build
npm test
npm run dev

テストスイートはすべて、スタブ化された JSON-RPC 上流を対象に実行されます。実ネットワークへの呼び出しはありません。

ライセンス

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