serieslib

serieslib

serieslib 是 ElKassabgi 数据家族托管 MCP 服务的轻量本地桥接工具。该服务通过一个端点发布三个库：一个经济学目录，包含来自数百个官方来源的数十亿条时间序列；一个高频库，包含美国股票的 1 分钟 K 线和预先计算的学术变量；以及一个知识产权库，包含专利级创新指标。

该桥接工具不存储数据，也不执行计算。它在本地提供上游服务的工具列表——与从实时端点捕获的内容完全一致——并将每次工具调用转发到上游，原样返回结果。搜索、元数据、来源列表、数据新鲜度和状态工具在上游免费；上游的少数下载需要该家族自己的免费 API 密钥，这由上游负责：此客户端不会发送自己的凭据，而 get_auth_status 会报告上游连接的密钥状态。

工具

• search_econ_series — 按自由文本搜索经济学目录（必填：query）。可选：source，用于限定单个来源 ID；limit（1-50，默认值为 15）和 offset，用于分页；以及 lang（en、ar、es、fr、ru、zh），用于获取来源官方提供的译名（如有）。返回供其他工具使用的序列 ID。
• get_econ_series — 下载单个序列，返回日期/数值行及其引文和许可。必填：series_id。可选：date_from / date_to（YYYY-MM-DD），用于截取较长序列的日期范围；以及 max_rows（10-2000，默认值为 400）。
• get_econ_series_metadata — 获取单个序列的完整元数据（必填：series_id）：标题、频率、地理区域、单位、许可（含商业用途标记）、署名信息和覆盖日期。
• list_econ_sources — 列出目录中的来源（统计部门、货币当局、政府间组织、研究数据集）及其许可。可选：contains，按来源 ID 或名称进行不区分大小写的筛选。
• get_data_freshness — 显示上游更新器台账中的各来源更新情况：上次成功更新、数据最新时间点，以及过期或失败标记。可选：source，用于查看单个来源。
• get_econ_bundle_manifest — 构建可引用的 Frictionless 风格数据包清单：最多 50 个指定序列 ID（ids），或某个小型来源的全部序列（source，最多 1,000 个）。无法解析的 ID 会报告出来，不会被丢弃。
• get_hf_download_link — 获取高频库的身份验证下载说明。必填：ticker（例如 AAPL）。可选：dataset（bars、variables 或 quality，默认值为 bars）、version（clean 或 raw，默认值为 clean），以及 format（parquet 或 csv，默认值为 parquet；csv 仅适用于 bars）。文件包含某个股票代码的全部 K 线数据，由你自己的代码获取，不会以内联形式返回。
• get_hf_variables_dictionary — 获取 25 个预先计算的学术变量的准确发布定义和公式。不接受参数。
• list_ip_bundles — 列出知识产权库中固定到快照的专利和创新数据包，并显示大小、版本和下载路径。不接受参数。
• get_ip_download_link — 获取单个知识产权数据包的身份验证下载说明。必填：file（patent_measures.parquet 或 assignee_year.parquet）。可选：vintage，用于固定到特定快照，而非使用最新快照。
• get_family_status — 获取三个库的实时概要统计和数据时效情况。不接受参数。
• get_auth_status — 查询上游连接是否配置了该家族的 API 密钥（密钥已屏蔽，绝不会回显），以及如何添加密钥。不接受参数。

配置

• ELKASSABGI_MCP_URL（可选）— 覆盖上游端点。默认值为 https://elkassabgidata-mcp.elkassabgi.workers.dev/mcp。 （此覆盖钩子是本次重建自行标注的内容。）

转发机制

首次调用工具时，客户端会与上游建立一个可流式传输的 HTTP 会话：先发送 JSON-RPC initialize 请求（协议版本 2025-03-26，clientInfo 名称为 serieslib），然后发送 notifications/initialized 通知，接着发送携带调用方原样参数的 tools/call 请求。上游 在响应 initialize 时，如果返回 Mcp-Session-Id 标头， 该值会随会话的每个后续请求一并发送；该会话会在进程 运行期间持续复用。 响应可能以普通 JSON 或服务器发送事件的形式到达；两种格式都会读取。

成功的上游结果会原样传递，包括上游设置的任何 isError 标志。 失败情况——JSON-RPC 错误、非 2xx 状态、无法读取的响应，或 无法完成的请求——会作为 isError 结果返回，其 文本以 serieslib error: 开头（此呈现方式是 本次重建自行标注的还原）。

CLI

每个工具也可作为子命令使用，并接受一个 JSON 参数字符串（无需参数的工具可省略）：

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。