serieslib

serieslib

serieslib is a thin local bridge to the ElKassabgi data family's hosted MCP server, which publishes three libraries under one endpoint: an economics catalog with billions of time series drawn from hundreds of official sources, a high-frequency library of 1-minute US equity bars and pre-computed academic variables, and an intellectual-property library of patent-level innovation measures.

The bridge holds no data and computes nothing. It serves the upstream server's tool list locally — exactly as captured from the live endpoint — and forwards each tool call upstream, returning the result untouched. Search, metadata, source lists, freshness and status tools are free at the upstream; a few downloads there ask for the family's own free API key, which stays an upstream concern: this client sends no credential of its own, and get_auth_status reports the upstream connection's key state.

Tools

• search_econ_series — search the economics catalog by free text (query, required). Optional: source to restrict to one source id, limit (1-50, default 15) and offset for paging, and lang (en, ar, es, fr, ru, zh) for source-official translated titles where they exist. Returns series ids for the other tools.
• get_econ_series — download one series as date/value rows with its citation and licence. Required: series_id. Optional: date_from / date_to (YYYY-MM-DD) to window long series, and max_rows (10-2000, default 400).
• get_econ_series_metadata — full metadata for one series (series_id, required): title, frequency, geography, unit, licence including the commercial-use flag, attribution, and coverage dates.
• list_econ_sources — enumerate the catalog's sources (statistical offices, monetary authorities, IGOs, research datasets) with their licences. Optional: contains, a case-insensitive filter on source id or name.
• get_data_freshness — the per-source update board from the upstream updater's ledger: last successful update, data frontier, and stale or failure flags. Optional: source for a single source.
• get_econ_bundle_manifest — build a citable Frictionless-style bundle manifest: up to 50 explicit series ids (ids), or every series of one small source (source, up to 1,000). Unresolvable ids are reported, never dropped.
• get_hf_download_link — authenticated download instructions for the high-frequency library. Required: ticker (e.g. AAPL). Optional: dataset (bars, variables or quality, default bars), version (clean or raw, default clean), and format (parquet or csv, default parquet; csv applies to bars only). Files hold all of a ticker's bars and are fetched by your own code, not returned inline.
• get_hf_variables_dictionary — the exact published definitions and formulas of the 25 pre-computed academic variables. No arguments.
• list_ip_bundles — list the IP library's snapshot-pinned patent and innovation bundles, with sizes, vintages and download paths. No arguments.
• get_ip_download_link — authenticated download instructions for one IP bundle. Required: file (patent_measures.parquet or assignee_year.parquet). Optional: vintage to pin a snapshot instead of the newest.
• get_family_status — live headline stats and data currency for all three libraries. No arguments.
• get_auth_status — whether the upstream connection has a family API key configured (masked; the key is never echoed) and how to add one. No arguments.

Configuration

• ELKASSABGI_MCP_URL (optional) — override the upstream endpoint. Defaults to https://elkassabgidata-mcp.elkassabgi.workers.dev/mcp. (The override hook is this rebuild's own labelled reconstruction.)

Forwarding mechanics

On the first tool call the client opens a streamable HTTP session with the upstream: a JSON-RPC initialize request (protocolVersion 2025-03-26, clientInfo name serieslib), then a notifications/initialized notification, then the tools/call request carrying the caller's arguments unchanged. When the upstream answers initialize with an Mcp-Session-Id header, that value rides on every later request of the session, which is reused for the life of the process. Replies may arrive as plain JSON or as server-sent events; both are read.

Successful upstream results pass through verbatim, including any isError flag the upstream sets. Failures — a JSON-RPC error, a non-2xx status, an unreadable response, or a request that cannot be completed — come back as an isError result whose text starts with serieslib error: (this rendering is this rebuild's own labelled reconstruction).

CLI

Each tool is also a subcommand taking one JSON argument string (omit it for tools that take none):

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

Exit codes: 0 on success, 1 on an isError result, 2 on a usage error.

MCP server

npx -y @reneturcios/serieslib mcp

MCP client config:

{
  "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

The container's default command is mcp, so the first form is a stdio MCP server; any other arguments reach the CLI normally.

Development

npm install
npm run build
npm test
npm run dev

The test suite runs entirely against a stubbed JSON-RPC upstream — no live network calls.

License

MIT — see LICENSE.