> ## Documentation Index
> Fetch the complete documentation index at: https://www.worldmonitor.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 工具：咽喉要道与供应链

> World Monitor MCP 工具参考：航运咽喉要道、供应脆弱性与供应链数据。逐一列出每个工具的输入参数与类型、数据新鲜度窗口、对应的后端 REST API 端点，以及可直接复制使用的示例调用负载，帮助开发者构建情报智能体、工作流自动化与自定义 MCP 客户端集成。

本页属于 [MCP 工具参考](https://www.worldmonitor.app/docs/zh/mcp-tools-reference.md)，该索引列出全部工具。连接、认证、套餐与错误见 [MCP Server 概览](https://www.worldmonitor.app/docs/zh/mcp-overview.md)。

`curl` 示例假设已执行 `export WM_KEY="wm_…"`；使用 OAuth 时，请将 `-H "X-WorldMonitor-Key: $WM_KEY"` 替换为 `-H "Authorization: Bearer $TOKEN"`。

### `get_chokepoint_status`

实时海上咽喉状态：每个咽喉的船只通行计数（10 分钟节奏）、滚动通行汇总、港口国家覆盖索引，以及静态参考数据（咽喉几何、规范 13 咽喉注册表）和流量汇总。覆盖苏伊士、霍尔木兹、马六甲、曼德海峡、巴拿马等。

**参数（工具特定）：**

| 名称 | 类型 | 描述 |
| - | - | - |
| `panel_request` | string | 来自付费面板的签名用户绑定咽喉读取凭据。仅授权此工具及其现有筛选；不能与刷新同时使用。 |
| `refresh` | boolean | 仅适用于付费额度：显式请求一次新面板分配。提供 request\_id UUID。 |
| `request_id` | string | 显式付费刷新的 UUID；重试同一 UUID 会复用该分配。 |
| `chokepoint` | string | 筛选为一个咽喉要道 — 在各数据集使用的不同标识符间按不区分大小写的子串匹配（例如 "hormuz" 匹配 "hormuz\_strait"、"Strait of Hormuz"）。 |
| `dataset` | `array<string: transit-summaries / chokepoint_transits / _countries / chokepoint-baselines / ref / chokepoint-flows>` | 将响应限制为一个或多个子数据集。省略则返回完整捆绑包。 |
| `limit` | number | 将 chokepoint-baselines 列表和 \_countries ISO2 索引限制为最多这么多项（默认 30，传 0 表示不限）。键控对象映射（transit-summaries、chokepoint\_transits、ref、chokepoint-flows）有意不做限制 — 请改用 `chokepoint` 筛选。 |

* **API 端点：** `GET /api/supply-chain/v1/get-chokepoint-status`
* **类型：** 缓存读取 — 来自 Redis 引导缓存的亚秒级响应。
* **新鲜度预算（按切片）：** 当任意贡献切片超过其单独预算时标记 `stale: true` — 实时通行汇总（中继）**30 分钟**、PortWatch 港口活动 **36 小时**、咽喉流量 **12 小时**、PortWatch 咽喉参考 **14 天**，静态咽喉注册表/地理基准线最多 **\~400 天**。捆绑包的 `cached_at` 反映最旧的贡献种子；`stale: true` 并不意味着所有数据都过时。
* **按国家的内容新鲜度（PortWatch 切片）：** 当决策关键国家（`CN`/`HK`）自身的观测超过 **72 小时**时，`stale: true` 同样会被标记 —— 即使该次运行的心跳是新鲜的、且全部 174 个国家均已发布。只要上游 `max(date)` 未推进，seeder 就会复用缓存的国家载荷，因此传输时效与记录数都显示健康，而某个国家的数据已过时数日。这与 `/api/health` 对同一 seed 键给出的 `STALE_CONTENT` 判定一致 —— 参见[健康检查端点](https://www.worldmonitor.app/docs/zh/health-endpoints.md)。`stale` 仍是单一布尔值，不会说明是哪个维度触发；指名过时国家的是 `/api/health`。

```bash curl theme={null}
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":1,
    "method":"tools/call",
    "params":{"name":"get_chokepoint_status","arguments":{}}
  }'
```

**咽喉要道面板额度。**

在 Pro 和 Pro Business 中，`get_chokepoint_status` 打开一次签名的 `chokepoints` 面板只消耗一个额度。重复筛选、`summary` 和 JMESPath 视图共享该额度。实际请求的来源子集完整时复用未截断的原始数据；规范化数据集子集或咽喉筛选变化时，可在同一额度内重新获取来源。仅含未知名称的数据集选择器使用完整数据包。键控筛选未匹配时保留原映射，不能制造完整空覆盖。稀疏 AIS、不可用的今日计数和部分建模流量保持可见且可重试。

返回的 `panelRequest.token` 作为 `panel_request` 仅授权此工具。显式 `refresh: true` 需要 UUID `request_id`，并省略读取凭据；同一 UUID 的重试复用该额度。已授权凭据读取会查询当前用量，不再分配额度；用量未知时不显示数字。API 和免费账户保持逐工具计费，并拒绝这些付费控制参数。

每次未缓存执行仍使用六个数据 GET、六个元数据 GET 和一个激活 EXISTS 命令。64 次读取限制按工具执行计数，不按这 13 个 Redis 命令计数。复用在缓存查询后和保存前验证所选来源形状、可用性、发布时间以及 CN/HK 关键内容时效。部分、格式错误、未经评估或过期的原始数据不会作为完整数据缓存。基准参考年份和建模流量发布时间不能证明当前实测油流或底层历史的新鲜度。私有封装缓存仍为 512 KiB，工具输出仍为 128 KiB。此额度修改不增加网站详情、历史、警告或提供商读取。

### `get_chokepoint_dependencies`

返回一个海运咽喉要道中评分最高的国家和商品依赖。反向索引与国家索引在同一次计算中生成，因此评分、状态、运输份额和方法版本可对账。

| 名称 | 类型 | 描述 |
| - | - | - |
| `chokepoint_id` | string | 必填规范 id，例如 `hormuz_strait` 或 `malacca_strait`。 |
| `page_size` | integer | 可选结果上限，1–100，默认 25。 |

* **API 端点：** `GET /api/supply-chain/v1/get-chokepoint-dependencies`
* **访问：** `subscription` —— 此 RPC 工具需要 Pro 订阅。
* **类型：** 从 `supply-chain:chokepoint-dependencies:v1` 读取 Redis 投影。
* **方法：** [大宗商品脆弱性方法论](https://www.worldmonitor.app/docs/zh/methodology/supply-vulnerability.md)。

```json theme={null}
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_chokepoint_dependencies","arguments":{"chokepoint_id":"hormuz_strait","page_size":25}}}
```

### `get_supply_vulnerabilities`

返回一个国家的已审核大宗商品脆弱性组合。每行包含绝对评分和等级（证据足够时）、组成、覆盖状态、过期原因、来源和 `methodologyVersion`。缺失评分表示未知，不是零。

| 名称 | 类型 | 描述 |
| - | - | - |
| `country_code` | string | 必填 ISO 3166-1 alpha-2 国家代码，例如 `AE`、`JP` 或 `DE`。不区分大小写。 |

* **API 端点：** `GET /api/supply-chain/v1/get-country-vulnerabilities`
* **访问：** `subscription` —— 此 RPC 工具需要 Pro 订阅。
* **类型：** 从 `supply-chain:vulnerability:v1` 读取 Redis 投影。
* **方法：** [大宗商品脆弱性方法论](https://www.worldmonitor.app/docs/zh/methodology/supply-vulnerability.md)。

```json theme={null}
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_supply_vulnerabilities","arguments":{"country_code":"AE"}}}
```

### `get_supply_chain_data`

返回运价指数、纽约联储 GSCPI、基于 BDRY 和航运公司股票的压力代理指标、海关收入及 COMTRADE 贸易流。仅限订阅用户，API 权重为 1。FRED 指数包含原始值和历史；SSE 仅含变化百分比、方向和 z 分数，不返回 Baltic 指数。GSCPI 单位为标准差，月度值可能修订。

**参数（工具特定）：**

| 名称 | 类型 | 描述 |
| - | - | - |
| `dataset` | `array<string: shipping_stress / customs-revenue / flows / freight-rates / gscpi>` | 将响应限制为一个或多个子数据集（股票航运压力代理指标 / 海关收入 / COMTRADE 流 / 运价 / GSCPI）。省略则返回全部。 |
| `commodity` | string | 将 COMTRADE 流筛选为一种大宗商品 — 精确匹配 HS 代码或按子串匹配大宗商品描述（例如 "2709" 或 "crude"）。 |
| `reporter` | string | 按数字报告方代码或报告方名称筛选 COMTRADE 流（例如 "156" 或 "China"）。 |
| `limit` | number | 将每个列表数据集（承运商、月份、贸易流、运价指数、GSCPI 观测值）限制为最多这么多项（默认 30，传 0 表示不限）。 |

* **API 端点：** `GET /api/supply-chain/v1/get-shipping-stress`, `GET /api/trade/v1/get-customs-revenue`, `GET /api/supply-chain/v1/get-shipping-rates`
* **类型：** 缓存读取 — 来自 Redis 引导缓存的亚秒级响应。
* **新鲜度预算：** 运价为 **19 小时**，GSCPI 与海关收入为 **2 天**。

`freight-rates.indices[]` 包含来源、频率、观测日期、期间变化和基线统计。z 分数使用除最新点外的历史均值和总体标准差；少于 12 个基线点或方差为零时为 null。SSE 每周历史上限为 56 点，仅从后续采集累积，不能回填。`gscpi.series.observations` 保留最新 `limit` 个月并按时间升序排列。数据来源为 Federal Reserve Bank of New York，值可能修订。

```bash curl theme={null}
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":1,
    "method":"tools/call",
    "params":{"name":"get_supply_chain_data","arguments":{"dataset":["freight-rates","gscpi"],"limit":12}}
  }'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.