Sdmx Structure

@pipeworx/sdmx-structure

适用于任何 SDMX 2.1 统计注册库的数据流维度和代码列表——“这个数据集中的代码是什么意思”——包括 Eurostat、OECD、European Central Bank、UN Statistics Division（通过 data.un.org SDMX hub）、IMF、Bank for International Settlements、ILOSTAT 和 Australian Bureau of Statistics。这是 SDMX 的 STRUCTURE 部分，与提取观测值不同——可用它解读某个维度的代码，或了解注册库自身的 get_data 工具所需的键顺序。

这是 Pipeworx 的一部分——一个将 AI Agent 连接到 1784+ 个实时数据源的 MCP 网关。这是一个独立的非官方集成，与上游提供方无关联、未获其认可，也不是由其发布。

工具

• sdmx_dataflow_structure(registry, dataflow, agency?, version?, max_codes_per_dimension?) — 返回单个数据流的有序维度，以及各维度代码表中的代码→标签对应项（每个维度均设有上限，并带有截断标记和实际总数）。解析数据流的实际 DSD（Data Structure Definition）引用，而不是假定数据流 ID 与 DSD ID 相同——很多数据流并非如此（Eurostat 的 UNE_RT_M 数据流 v1.0 指向 DSD UNE_RT_M v155.0；BIS 的 WS_CBPOL 数据流指向一个名称不同的 DSD：BIS_CBPOL）。
• sdmx_codelist(registry, id, agency?, version?, filter?, limit?) — 仅凭 ID 获取单个代码表中的代码→标签对应项，无需数据流。适用于你已知道代码表 ID（来自 sdmx_dataflow_structure 的 codelist 字段或文档），只想获取代码的情况；还可选择按子字符串筛选。
• sdmx_find_dataflow(registry, query, agency?, limit?) — 按 ID 或名称搜索注册库的数据流目录，以找到要传给 sdmx_dataflow_structure 的 ID。

注册表

registry	来源	结构格式	默认机构
eurostat	Eurostat	仅 XML（已确认在线可用 — 所有 JSON Accept/format 组合均返回 406）	ESTAT
oecd	OECD	JSON	all
ecb	European Central Bank	仅 XML	ECB
unsd	UN Statistics Division（data.un.org SDMX 中心）	JSON	all
imf	IMF	JSON	all
bis	Bank for International Settlements	JSON	BIS
ilo	ILOSTAT	JSON	ILO
abs	Australian Bureau of Statistics	JSON	ABS

OECD、IMF 和 UNSD 的默认机构是 all，而不是单一机构 — 这是关键设置，并非占位符。 这三个注册表都将目录分散在多个负责维护的子机构中，没有一个能覆盖全部内容的单一机构 ID：

• OECD：没有一个机构的名称恰好是 "OECD" — 每个数据流都由某个理事会发布（OECD.SDD.NAD、OECD.ELS.JAI、OECD.EDU.IMEP，……；在线观察到 52 个不同的机构 ID，其中一些也在 ESTAT 和 IAEG-SDGs 数据流中出现）。查询机构 "OECD" 时，目录列表和单个数据流查询都会返回 404 和 "No Results Found" — 这是 #2839 后续跟进时发现的线上缺陷（sdmx_find_dataflow({registry:"oecd", query:"unemployment"}) 返回 404）。
• IMF：有 10 个子机构（IMF.STA、IMF.MCD、IMF.SPR、IMF.AFR、IMF.MCM、IMF.FAD、IMF.WHD、IMF.APD、IMF.RES，以及外部机构 ISORA）。仅 IMF.STA 就能返回 200 — 所以最初看起来没问题 — 但它只覆盖 223 个数据流中的 190 个；其余 33 个都是各地区经济展望（APDREO、AFRREO、WHDREO，……）和财政事务数据流。
• UNSD：这个中心会将 ESTAT、IAEG-SDGs、UIS 和 World Bank 的数据流连同 UNSD 自身约 4 个数据流一起，按各自的机构 ID 镜像发布。查询机构 "UNSD" 会返回 200，但只返回 UNSD 自身的数据流（观察到 1.4KB）；而 "all" 会返回整个中心（4.4KB，约 15 个数据流）。

对于这三个注册表，"all" 的单个数据流查询结果与该数据流实际所属的子机构完全一致（已并排验证 OECD.SDD.NAD、IMF.APD 和一个归属 ESTAT 的 UNSD 中心数据流，响应逐字节相同）— 因此默认使用它不会损失覆盖范围。只有在需要将搜索范围缩小到某个子机构，或与其他注册表的单一机构默认值保持一致时，才传入 agency（Eurostat/ECB/BIS/ILOSTAT/ABS 各自本来就只有一个机构）。

未纳入：Stats NZ。 它的 SDMX 端点需要平台 API 密钥（Ocp-Apim-Subscription-Key，由网关从 PLATFORM_STATSNZ_KEY 注入），并且 flowRef 路径段中必须包含字面量的、未进行 URL 编码的逗号 — 这两点都不符合此工具包无需密钥、路径经过 URL 编码的设计，而且 stats-nz 工具包已提供专用的结构工具。请参阅该工具包。

与现有工具包的功能重叠 — 使用此工具包查询 ILO 或 ABS 前请先阅读。 ilostat 工具包已为 ILO 数据流提供 dataflow_structure，abs-au 工具包也已为 ABS 数据流提供 dataflow_structure — 两者都直接内联代码，作用与此处的 sdmx_dataflow_structure 相同。此工具包支持 registry: "ilo" 和 registry: "abs"，仅用于独立的 sdmx_codelist 查询（按 ID 查询代码列表，无需数据流）；这两个工具包都未提供此功能。查询 ILO 或 ABS 数据流时，请优先使用 ilostat 或 abs-au 自带的 dataflow_structure — 此工具包针对这两个注册表的每个响应，都会在 overlap 字段中重复说明这一点。

身份验证

无需密钥。以上 8 个注册表均无需身份验证。

数据源

• Eurostat SDMX 2.1 REST API — https://ec.europa.eu/eurostat/api/dissemination/sdmx/2.1 — 结构端点（/dataflow、/datastructure、/codelist）只返回 SDMX-ML XML；本工具包尝试的所有 JSON Accept 标头和 format=SDMX-JSON 查询 参数要么返回 406，要么被静默忽略（已于 2026-10-08 在线确认）。eurostat 工具包自己的数据端点 (/dissemination/statistics/1.0/data) 是一个能提供 JSON-stat 的不同 API；两者不可互换。
• OECD SDMX 2.1 REST API — https://sdmx.oecd.org/public/rest。
• European Central Bank Data Portal — https://data-api.ecb.europa.eu/service — 结构端点仅支持 XML，与 ecb 工具包已针对其自身的 /dataflow 调用记录的情况相同 （fleet #1158）：DATA 端点支持 SDMX-JSON，STRUCTURE 端点（/dataflow、/datastructure、 /codelist）则不支持。
• UN Statistics Division SDMX hub — https://data.un.org/legacy/ws/rest — 文档中记录的 https://data.un.org/ws/rest/... 路径会重定向（302）到此处；本工具包直接调用 重定向目标。这是一个小型多机构 hub（观察到约 15 个数据流），包含 UNSD 自己的数据流（DF_UNDATA_ENERGY、 DF_UNDATA_COUNTRYDATA），以及以各自机构 ID 提供的 IAEG-SDGs、UIS 和 World Bank 镜像数据流——如果你需要的数据流 属于其中某个机构，而非 UNSD，请传入 agency。
• IMF SDMX 2.1 REST API — https://api.imf.org/external/sdmx/2.1。**IMF 概念级表示陷阱：**某些 IMF 维度完全没有 localRepresentation.enumeration——例如 EER 的 COUNTRY 和 INDICATOR 维度。它们的代码列表定义在共享的 CONCEPT 上：维度的 conceptIdentity URN 指向某个概念方案（例如 IMF:CS_MASTER_DATA），该概念自身的 coreRepresentation.enumeration 才是真正的代码列表（COUNTRY 对应 IMF:CL_COUNTRY）。本工具包会自动沿着这条链查找；只读取 dimension.localRepresentation 的简单实现会将这些维度报告为没有代码列表。
• Bank for International Settlements SDMX 2.1 REST API — https://stats.bis.org/api/v2/structure（注意 /structure 路径段 — 与此处其他所有注册表不同，BIS 将 dataflow、datastructure 和 codelist 资源嵌套在此路径下）。
• ILOSTAT SDMX 2.1 REST API — https://sdmx.ilo.org/rest。**Accept-Language 陷阱：**对于完全不带 Accept-Language 标头的任何请求，ILO 后端都会返回内容为 500 languageTag1 的空正文—— 使用 Node/Workers 的 fetch 可复现（默认不发送该标头），但使用 curl 则不会；已于 2026-10-08 在线确认。本工具包会在向每个注册表发出的每个请求中发送 Accept-Language: en（在其他地方无害），正是因为这个问题。
• Australian Bureau of Statistics Data API — https://data.api.abs.gov.au/rest — 文档中记录的主机 api.data.abs.gov.au 无法解析；这与 abs-au 工具包此前发现并记录的在线主机相同。

**所有注册表都存在的体积陷阱：**使用 references=children 获取 DSD，会在同一个响应中拉取它所使用的所有代码列表——仅 Eurostat 的 UNE_RT_M 就有 3.7MB，因为其 GEO（国家/地区）代码列表有 2.6MB。本工具包 从不这样做：它使用 references=none 获取 DSD（仅几 KB——包含维度列表以及每个维度的代码列表 REFERENCE）， 然后逐个获取实际需要的代码列表，每个列表的条目数均限制为 max_codes_per_dimension（默认值为 50，最大值为 500），并附带截断标记和 实际代码总数。 结构端点返回 404 始终表示“没有这个 ID”——与数据端点不同，结构查询不存在“数据流存在，但没有匹配的观测值”这种模糊情况，因此此工具包无需采用 shared/src/sdmx-miss.ts 为其他工具包的 get_data 工具提供的 data-endpoint no_records/no_dataflow 区分。这里的每个 404 都会以结构化的 {error: "not_found", ...} 返回，并将 sdmx_find_dataflow 指定为下一步操作。若 200 响应解析出的维度数或数据流数为零，则会报告醒目的 upstream_parse: 错误，绝不会静默返回空结果。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "sdmx-structure": {
      "url": "https://gateway.pipeworx.io/sdmx-structure/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/sdmx-structure/mcp 上的 tools/list 会返回上表中的工具，以及 Pipeworx 共享的元工具——ask_pipeworx、discover_tools、search_within、remember/recall 和网关级工具集中的其他工具。因此，你看到的工具数量会多于此表中的数量：目前，单个工具包端点除了列出该工具包自身的工具，还会列出大约 30 个共享工具。连接的 initialize 响应会说明其确切范围，并且是当天实际范围的权威依据。

这是有意为之，并非意外的多路复用。元工具让受限连接也能回答此工具包未覆盖的问题——通过 ask_pipeworx 在整个目录中进行路由——无需添加第二个 MCP 服务。目前无法在不包含这些工具的情况下挂载工具包端点；如果额外的架构定义带来的上下文开销超过了路由的价值，请连接一次完整网关，而不是连接多个工具包端点。

也可以连接完整的 Pipeworx 网关，直接列出每个工具包的工具，而不只是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都连接到同一个网关和相同的 1784+ 个数据源。唯一的区别是直接列出哪个工具包的工具；无论连接哪一个，ask_pipeworx 都可以访问所有工具包。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/sdmx_dataflow_structure \
  -H 'Content-Type: application/json' \
  -d '{"registry":"eurostat","dataflow":"une_rt_m"}'

首次调用无需账号。查看任意工具：GET https://gateway.pipeworx.io/v1/tools/sdmx_dataflow_structure。查找工具：使用 {"query":"..."} 向 https://gateway.pipeworx.io/v1/tools/search_packs 发送 POST 请求。

独立运行（无需网关账号）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账号，也无需往返网关：

{
  "mcpServers": {
    "sdmx-structure": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-sdmx-structure"]
    }
  }
}

或者直接运行，确认它能正常启动：

npx -y @pipeworx/mcp-sdmx-structure

它通过 stdin/stdout 使用 MCP 通信，并仅针对此工具包的工具响应 initialize/tools/list/tools/call——不包含上文网关连接额外提供的共享元工具。来源相同，工具相同，但没有 ask_pipeworx 路由。

使用 ask_pipeworx

你无需直接调用工具，也可以用通俗的英语提问——无论是使用上文的工具包端点还是完整网关，都能这样操作：

ask_pipeworx({ question: "your question about Sdmx Structure data" })

网关会自动选择合适的工具并填入参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT