> ## Documentation Index
> Fetch the complete documentation index at: https://worldmonitor-spike-bun-package-manager.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# WorldMonitor MCP 服务器：接入 Claude 与 Cursor

> 通过 Model Context Protocol 将 Claude、Cursor 及其他兼容 MCP 的 AI 客户端与 IDE 无缝接入 WorldMonitor 的实时全球情报数据，涵盖新闻、市场、军事、海事、能源与地缘政治信号，构建可直接调用真实世界数据的智能 Agent 与工作流。

WorldMonitor 将其情报栈作为 [Model Context Protocol](https://modelcontextprotocol.io) 服务器对外开放，因此任何兼容 MCP 的客户端（Claude Desktop、Claude web、Cursor、MCP Inspector、自定义 agent）都可以将实时冲突、市场、航空、海事、经济和预测数据直接拉取到模型上下文中。

<Tip>
  **初次使用？** [MCP 快速入门](/zh/mcp-quickstart) 是一条从零到在 Claude Desktop 中完成真实工具调用的五分钟路径。如需认证模式、套餐、OAuth 配置和完整工具目录，请回到本页查看。
</Tip>

<Note>
  如果需要操作 Chrome 标签页中已经打开的仪表板，请参见 [WebMCP](/zh/webmcp)。WebMCP 是页面本地、实验性且有人参与的接口；它**不会**取代这套持久托管 MCP 服务器及其数据工具。
</Note>

<Info>
  **Pro 和 API 套餐均可通过 OAuth 接入 —— 无需 API key。** Pro 订阅者只需在授权页点击 *"Sign in with WorldMonitor Pro"*；API Starter / Business / Enterprise 用户可以同样的方式登录，或者粘贴 `wm_…` key。已确认的**免费账户**以及服务方确认已结束付费覆盖期的账户同样可以完成 OAuth 流程：其令牌仅限 `free-account` 工具，并按免费额度计量。只有经确认但不具备免费账户资格的权益不足或已停用套餐，才会在 OAuth 步骤被拒绝并看到 Pro-required 页面。

  `get_sources` 不需要 OAuth：它是唯一无需凭据且不消耗每日配额的数据工具。匿名调用使用独立的失败关闭限额：每个 IP 每分钟 10 次。其他数据工具需要绑定用户的凭据；标记为 `free-account` 的缓存工具可使用已确认免费账户的小额额度，标记为 `subscription` 的实时获取工具需要 Pro。
</Info>

所有付费套餐共享同一个 MCP 服务器和同样的实时工具目录。当前的硬性 MCP 每日预留仅针对 OAuth 上下文在 Pro 计数器上强制执行：**每个 UTC 日 50 次消耗配额的 `tools/call` / `resources/read` 调用**。使用 API key（`wm_…`）的 MCP 客户端受本 handler 中 **60 次请求/分钟/key** 限流器的保护；更宽松的 API Starter / Business REST 额度在 MCP 每日预留路径之外强制执行。（`describe_tool`，即 v1.5.0 的元数据查询辅助工具，不计入 Pro 每日配额。）

Pro 订阅者无需粘贴任何 API key 即可接入 Claude Desktop / Cursor / claude.ai —— 参见下方的 [Pro 登录流程](#pro-sign-in-flow)。API Starter+ 用户可继续在授权页粘贴 `wm_…` key（原始流程），也可使用与 Pro 相同的 OAuth 路径。

## 端点

| 端点                                                                    | 用途                                                                                                                                       |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `https://worldmonitor.app/mcp`                                        | JSON-RPC 服务器（Streamable HTTP 传输；默认返回 JSON 响应，当客户端声明 `text/event-stream` 时返回 SSE 响应；`initialize` 默认协商协议 `2025-06-18`，对旧客户端为 `2025-03-26`） |
| `https://api.worldmonitor.app/api/oauth/register`                     | 动态客户端注册（RFC 7591）                                                                                                                        |
| `https://api.worldmonitor.app/api/oauth/authorize`                    | OAuth 2.1 授权端点（要求 PKCE）                                                                                                                  |
| `https://api.worldmonitor.app/api/oauth/token`                        | Token 端点（authorization\_code + refresh\_token）                                                                                           |
| `https://api.worldmonitor.app/.well-known/oauth-authorization-server` | AS 元数据（RFC 8414）                                                                                                                         |
| `https://worldmonitor.app/docs/mcp`                                   | 独立的匿名**文档** MCP 服务器（文档搜索 + 只读文档文件系统）——卡片位于 `/.well-known/mcp/docs-server-card.json`；参见[智能体发现](/zh/agent-discovery)                       |
| `https://worldmonitor.app/.well-known/oauth-protected-resource`       | 资源服务器元数据（RFC 9728）                                                                                                                       |

服务器标识：`worldmonitor` v1.17.0。

注册表登记：该服务器以 `app.worldmonitor/mcp` 之名发布于[官方 MCP 注册表](https://registry.modelcontextprotocol.io/v0/servers?search=worldmonitor) —— 这是一个经过域名验证的命名空间，因此通过注册表解析服务器的客户端获得的端点和元数据与上方的服务器卡片一致 —— 并在 [Smithery](https://smithery.ai/servers/worldmonitor/wm-mcp) 和 [mcp.so](https://mcp.so/server/world-monitor) 上列出。

### 协议协商

WorldMonitor 位于 `/.well-known/mcp/server-card.json` 的静态服务器卡片声明协议版本 `2025-06-18`，而实时的 `initialize` 握手默认会协商该版本 —— 因此所声明的底线版本与实际协商出的版本保持一致：

* 默认情况下，`initialize` 同时支持 `2025-03-26` 和 `2025-06-18`。
* 请求 `2025-06-18` 的客户端会得到 `2025-06-18`；固定使用 `2025-03-26` 的客户端继续得到 `2025-03-26`。
* 设置 `MCP_PROTOCOL_FLOOR_2025_06_18=off` 会将服务器固定回仅支持 `2025-03-26` 的旧版底线；此后请求 `2025-06-18` 的客户端会收到安全默认值 `2025-03-26`。

无论协商出的协议版本如何，工具的 `outputSchema` 元数据都会在 `tools/list` 中发出。较旧的 `2025-03-26` 客户端应忽略未知字段，而较新的客户端可以立即使用该 schema。

### Streamable HTTP 响应

WorldMonitor 支持 Streamable HTTP POST 流程，可返回 JSON 或 SSE 响应：

* 在 `Accept` 中省略 `text/event-stream` 的客户端会收到标准的 JSON-RPC JSON 响应体。
* 发送 `Accept: application/json, text/event-stream` 的客户端在 JSON-RPC POST 成功时可收到 `text/event-stream` 响应。
* `initialize` 的 SSE 响应包含 `Mcp-Session-Id`；后续的 POST 应发送相同的 `Mcp-Session-Id` 头。
* 每个 SSE 响应以带有事件 `id` 的单个 `message` 事件承载 JSON-RPC 结果。不存在开头的空预热事件 —— 根据 WHATWG SSE 规范，空的 `data:` 字段仍会派发一个 `message`（其 `data === ""`），这会导致严格的握手扫描器在 `JSON.parse("")` 上失败。
* 如果客户端在唯一的那个事件之后断开连接，可以通过发送带有 `Accept: text/event-stream`、相同 `Mcp-Session-Id` 和 `Last-Event-ID` 的 `GET /mcp` 来重新连接；在已投递的事件之后恢复会返回一个空流。在收到该事件之前就断开的客户端没有已确认的 `Last-Event-ID`，因此会改为重新发起该 POST。
* \*\*带有 `Accept: text/event-stream` 但不带 `Last-Event-ID` 的 `GET /mcp`\*\*表示客户端尝试打开可选的服务器→客户端独立 SSE 流。这条无状态 edge 路由不提供服务器发起的流，因此返回 `405 Method Not Allowed`（并声明 `Allow`）；MCP SDK 会将其作为“无独立流”的正常信号处理。
* **浏览器式的普通 `GET /mcp`** —— 既无 SSE `Accept`，也无 `Last-Event-ID` —— 返回 `200` 和人类/agent 可读的 markdown 服务器指南（与 `/mcp-server.md` 相同）。普通 `HEAD /mcp` 采用同一路由，只省略响应体。

重放缓冲区在内存中，且按每个 edge 实例设有上限。请将 `Last-Event-ID` 恢复视为容忍丢失的传输层恢复，而非持久化的消息存储。

## 认证

**发现是公开的。** `initialize`、`tools/list`、`prompts/list`、`prompts/get`、`resources/list`、`resources/templates/list`、`ping`、`logging/setLevel` 以及 `notifications/initialized` 握手都可**无需凭据**提供服务，因此任何 agent（或 agent 就绪性扫描器）都可以连接到 `https://worldmonitor.app/mcp`、读取服务器身份，并在认证之前枚举完整的工具、prompt 和资源目录 —— 这与静态[服务器卡片](https://worldmonitor.app/.well-known/mcp/server-card.json)中已发布的元数据相同。这些方法只返回公开的目录元数据（名称、描述、URI / URI 模板、静态工作流模板文案 —— 不含数据，不计配额）；匿名 `initialize` 所声明的每一项能力都可匿名调用，因此严格的 MCP 客户端（Claude Desktop、`mcp-remote`、参考 SDK）能够完成其连接后的完整枚举，而不会卡在认证墙上。对**公开**资源的 `resources/read`（由 `resources/list` 暴露的具体的、仅含元数据的新鲜度/健康探针，例如 `worldmonitor://seed-meta/freshness`）**同样是公开且不计配额的** —— 匿名 agent 可以顺畅读取它。匿名发现按每个客户端 IP 限流为 60 次请求/分钟。`get_sources` 是唯一无需凭据且不消耗每日配额的数据工具；其匿名路径使用独立的失败关闭上限：每个 IP 每分钟 10 次。其他承载数据的调用需要凭据。每个 `tools/list` 和 `describe_tool` 条目都携带 `_meta["worldmonitor/access"]`：`free` 表示匿名且不计额度，`free-account` 表示已认证免费账户可用（缓存数据调用消耗免费额度，`describe_tool` 不消耗），`subscription` 表示仅 Pro 可用。资源模板携带与其支撑工具相同的标记。在发现方法上出示的凭据仍会被校验（错误的 key 会返回 `401`，绝不会静默降级为匿名）。

MCP handler 按优先级顺序接受两种认证模式：

1. **OAuth 2.1 bearer** —— `Authorization: Bearer <token>`，其中 `<token>` 由 `/api/oauth/token` 颁发。这是 Claude Desktop、claude.ai、Cursor 和 MCP Inspector 自动使用的方式。任何从浏览器源访问 MCP 的客户端都必须使用此方式。
2. **直接 API key** —— 对于用户颁发的 key 使用 `X-WorldMonitor-Key: wm_0123456789abcdef0123456789abcdef01234567`，或使用由运营方颁发的不透明企业 key。适用于服务端脚本、`curl` 和自定义集成。**不要**把 API key 当作 `Bearer` token 发送 —— 它会通过 OAuth 解析失败并返回 `401 invalid_token`。

OAuth bearer 请求在分发之前会重新检查解析出的 MCP token、用户绑定和当前权益，因此套餐降级会在下一次请求时移除不再具备的付费能力，但不会无条件撤销 OAuth 身份。服务方确认付费覆盖期已经结束时，该身份会转入受限、按额度计量的免费账户路径，仅能调用 `free-account` 工具；不具备免费账户资格的非免费权益不足或已停用权益仍会被拒绝。控制面板签发的 `X-WorldMonitor-Key: wm_…` 请求会校验密钥所有者和有效权益，然后使用与 OAuth 路径相同的按用户分钟桶和每日 50 次默认值。部署许可名单中的旧版运营方密钥使用按密钥分钟桶，并跳过每日预留。

### Redirect URI 允许列表

动态客户端注册**不**对任意 HTTPS 重定向开放。仅接受以下前缀：

* `https://claude.ai/api/mcp/auth_callback`
* `https://claude.com/api/mcp/auth_callback`
* `http://localhost:<port>` / `http://127.0.0.1:<port>`（任意端口） —— 适用于 Claude Code、MCP Inspector、本地开发

其他客户端必须通过这些重定向之一代理，或在本地运行。

### Token 生命周期

| 项目            | TTL      |
| ------------- | -------- |
| 授权码           | 10 分钟    |
| Access token  | 1 小时     |
| Refresh token | 7 天      |
| 已注册客户端记录      | 90 天（滑动） |

## Pro 登录流程

Pro 订阅者（以及不愿粘贴 key 的 API Starter+ 用户）可通过其已有的 WorldMonitor 账户授权 MCP 客户端 —— 无需 API key。

1. **在 MCP 客户端中添加服务器 URL**。规范入口为：

   ```
   https://api.worldmonitor.app/mcp
   ```

   （`https://worldmonitor.app/mcp` 也可用 —— 它代理同一个 handler。）

2. **在授权页点击 "Sign in with WorldMonitor Pro"**。这是默认 CTA。你会跳转到 `worldmonitor.app/mcp-grant`（受 Clerk 保护 —— 如需登录请先登录），然后回到 `api.worldmonitor.app/oauth/authorize-pro`，最后跳转到你客户端的 redirect。

3. **完成。** 你的机器上不会创建或存储任何 `wm_…` key。客户端会收到一个标准 OAuth 2.1 access token（1 小时 TTL，7 天 refresh）。

<Note>
  如果登录步骤提示无法校验你的订阅 —— 例如返回 `503` 页面或 `503 TIER_VERIFICATION_UNAVAILABLE` —— 这是可重试的校验状态，并不代表你的订阅已失效。请等待响应中的 `Retry-After`，然后从客户端重新发起连接；授权会话是一次性的，不要只刷新页面。服务方确认已失效且付费覆盖期已结束的订阅会转为免费账户，以受限的 `free-account` 令牌完成 OAuth，并按免费额度计量；它不会因该失效标记收到 `403`。真正的权益不足或已停用套餐仍会收到 `403 INSUFFICIENT_TIER`。参见[错误处理](/zh/usage-errors)。
</Note>

如果你更愿意粘贴 API key（Starter+ / 脚本化客户端），可在授权页展开 "Use API key instead" 并提交你的 `wm_` 用户 key 或由运营方颁发的企业 key —— 该路径保持不变。

### 每日额度（Pro 套餐）

* **每个 UTC 日 50 次消耗配额的调用**，在 UTC 00:00 重置。
* 承载数据的 `tools/call` 以及对承载数据的 **URI 模板实例化**的 `resources/read` 会消耗 Pro 每日配额，`get_sources` 和元数据辅助工具 `describe_tool` 除外。
* `initialize`、`tools/list`、`prompts/list`、`prompts/get`、`resources/list`、`resources/templates/list`、`logging/setLevel`、`notifications/initialized`、`ping`、`describe_tool` 和 `get_sources` **不**计入每日上限。对**公开**资源的 `resources/read`（仅含元数据的新鲜度/健康探针，例如 `worldmonitor://seed-meta/freshness`）同样豁免 —— 它不承载任何可计费的数据。
* 达到上限会返回 JSON-RPC 错误 `-32029` 以及 HTTP `429`，并附带指向下一个 UTC 午夜的 `Retry-After` 头。
* 该上限是硬性限制：接近边界时的并发 `tools/call` 或 `resources/read` 请求使用原子 Redis 预留，因此恰好跨越 50 的那次调用会被拒绝。

需要更高吞吐量的脚本化访问？**API Starter** 和 **API Business** 增加了 `wm_…` key 选项以及更高的 REST/API 套餐额度。它们的 MCP 调用仍使用每日 50 次默认值和共享的每用户每分钟 60 次限流。对于批量或高吞吐量工作流，请优先使用 REST/API 端点或联系 Enterprise —— 参见[套餐与限制](#plans--limits)。

### 已连接的 MCP 客户端

每次授权都会生成一条独立记录，因此撤销 Claude Desktop 不会影响 Cursor。

* 在 **[Settings → Connected MCP clients](https://worldmonitor.app/settings)** 管理已连接的客户端。
* 可查看每个 token 的实时 `clientName`（例如 "Claude"、"Cursor"）、`lastUsedAt` 和 `createdAt`。
* 撤销会在下一次 MCP 请求时生效（无正向缓存）。
* 每个用户最多 **5 个活跃 token**。超出上限的授权会静默撤销**创建时间最早**的现有 token（按创建顺序，而非最近使用时间；并发授权下的执行是最终一致的）。

## 套餐与限制

| 套餐               | MCP 访问                                              | 认证模式                          | MCP 每日预留                                 | 备注                                                                                     |
| ---------------- | --------------------------------------------------- | ----------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------- |
| **Free**         | 匿名 `get_sources`；持有绑定用户凭据时可用 `free-account`（缓存读取）工具 | OAuth（已确认的免费账户可完成流程）或现有绑定用户凭据 | **每 UTC 日 5 次调用和 3 个空闲间隔请求窗口**           | 令牌仅限 `free-account` 工具；`subscription` 工具返回升级拒绝。匿名 `get_sources` 超过每个 IP 每分钟 10 次时失败关闭。 |
| **Pro**          | ✅ 是                                                 | 仅 OAuth                       | **50 次消耗配额的调用 / UTC 日**                  | 经由 apex Clerk 登录跳转。无需或存储 `wm_…` key。                                                   |
| **API Starter**  | ✅ 是                                                 | OAuth **或** `wm_…` key        | **每个 UTC 日 50 次消耗配额的调用**                 | 标准开发者层 REST/API 访问。                                                                    |
| **API Business** | ✅ 是                                                 | OAuth **或** `wm_…` key        | **每个 UTC 日 50 次消耗配额的调用**                 | 更高的 REST/API 吞吐量。                                                                      |
| **Enterprise**   | ✅ 是                                                 | OAuth **或** `wm_…` key        | OAuth 可以不设上限；`wm_…` key 使用**每日 50 次默认值** | 可提供自定义 SLA。                                                                            |

所有付费套餐都通过每分钟 60 次调用的限流来防御突发流量风暴；OAuth 和控制面板签发的 `wm_…` key 按用户计数，旧版运营方密钥按密钥计数。**每分钟限流器在方法分发之前运行，因此每个已认证方法（包括 `initialize`、`tools/list`、`prompts/list`、`resources/list`、`describe_tool` 等）都计入 60/分钟。** 匿名 `get_sources` 调用改用独立的失败关闭上限：每个 IP 每分钟 10 次。每日配额上限仅由需要订阅且承载数据的 `tools/call` 和 `resources/read` 预留消耗，适用于 OAuth 和控制面板签发的 `wm_…` key（参见上方的[每日额度（Pro 套餐）](#daily-limit-pro-tier)，以及[错误目录](/zh/mcp-error-catalog#-32029--rate-limited-per-minute-or-daily)中关于两种限制的完整方法豁免表）。

OAuth 和控制面板签发的 key 的 60/分钟均按用户计算（一个拥有 3 个 Claude 安装或多个 `wm_…` key 的用户共享一个 60/分钟池）；旧版运营方密钥按 key 计算。

达到 MCP 每日配额会返回 JSON-RPC 错误 `-32029` 以及 HTTP `429`，并附带指向下一个 UTC 午夜的 `Retry-After` 头。达到每分钟限制会返回相同的错误码，但 `Retry-After` 较短。

WorldMonitor 还会在 Settings 中显示当前的 MCP 套餐限额通知，并在付费用户接近或超出其套餐额度时以受限频率发送邮件。这些通知以信息告知和行动引导为目的：它们提供重试/重置指引、在下一套餐可自助购买时提供结账入口，或在不可自助时提供支持联系方式。它们不会自动升级账户，也不会产生超额费用。

### 其他速率限制

* **OAuth authorize**：10 次请求 / 分钟 / IP
* **OAuth token**：10 次请求 / 分钟 / IP
* **动态注册**：5 次注册 / 分钟 / IP

超过任何限制都会返回 HTTP `429`，并附带 `Retry-After` 头。

## 客户端配置

### Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json`（macOS） —— 使用远程 MCP 条目：

```json theme={null}
{
  "mcpServers": {
    "worldmonitor": {
      "url": "https://worldmonitor.app/mcp"
    }
  }
}
```

Claude Desktop 会在首次连接时自动处理 OAuth 流程。

### Claude web (claude.ai)

通过 **Settings → Connectors → Add custom connector** 添加：

* 名称：`WorldMonitor`
* URL：`https://worldmonitor.app/mcp`

### Cursor

`~/.cursor/mcp.json`：

```json theme={null}
{
  "mcpServers": {
    "worldmonitor": {
      "url": "https://worldmonitor.app/mcp"
    }
  }
}
```

### MCP Inspector（调试）

```bash theme={null}
npx @modelcontextprotocol/inspector https://worldmonitor.app/mcp
```

## 工具目录

服务器暴露实时工具目录。大多数是对预填充 Redis key 的缓存读取（亚秒级）。较慢的非缓存路径包括六个实时 LLM/外部 API 工具（`get_country_brief`、`analyze_situation`、`generate_forecasts`、`search_flights`、`search_flight_prices_by_date`、`classify_event`）、实时地理 RPC 工具（`get_airspace`、`get_maritime_activity`）、受预算约束的规范采购代理（`get_procurement_opportunities`）、企业情报代理（`get_company_intelligence`）、规范化中国决策信号 RPC（`get_china_decision_signals`），以及三个持久化历史 RPC（`search_intel_history`、`get_intel_timeline`、`get_similar_events`）。`get_world_brief` 读取仪表板使用的预计算、有引用依据的 `news:insights:v1` 快照，不会在请求时调用 LLM。按需 NLP 实用工具（`classify_event`、`extract_entities`、`get_news_clusters`、`get_keyword_spikes`）接受有严格上限的调用方文本或基于实时种子数据计算；除 `classify_event` 外全部为确定性计算。有一个工具（`describe_tool`，v1.5.0 新增）返回任何其他工具的完整未压缩定义 —— 在压缩后的 `tools/list` 描述含糊不清时很有用；不计入 Pro 每日配额。

<Tip>
  如需各工具的参数、新鲜度预算、超时以及具体的 `curl` 示例，请参阅 [MCP 工具参考](/zh/mcp-tools-reference)。关于 payload 投影 —— 每个工具都接受一个可选的 `jmespath` 参数，通常可将响应大小缩减 80-95% —— 请参阅 [JMESPath 指南](/zh/mcp-jmespath)。
</Tip>

### 市场与经济

| 工具                              | 描述                                                                                                                 |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `get_market_data`               | 股票报价、商品价格、实物金银溢价与背离状态、加密货币、外汇、板块表现及估值覆盖、ETF 资金流、海湾市场。板块覆盖将写入年龄与完整度分开，并提供有界的 unavailable/last-good/direct-proxy 诊断。 |
| `get_economic_data`             | Fed Funds、经济日历、燃料价格、ECB 外汇、欧盟收益率曲线、财报、COT、能源库存、BIS DSR + 房价。                                                       |
| `get_country_macro`             | 每个国家一份的 IMF WEO 数据包：通胀、经常账户、人均 GDP、失业率、储蓄-投资缺口（约 210 个国家）。                                                         |
| `get_eu_housing_cycle`          | Eurostat 年度房价指数（prc\_hpi\_a），每个欧盟成员国 + EA20/EU27 的 10 年迷你图。                                                        |
| `get_eu_quarterly_gov_debt`     | Eurostat 季度政府总债务（占 GDP 比例），8 个季度迷你图。                                                                               |
| `get_eu_industrial_production`  | Eurostat 月度工业生产指数，12 个月迷你图。                                                                                        |
| `get_prediction_markets`        | 含当前概率的预测市场：`geopolitical`（地缘政治/选举）、`tech`（有标签的科技：人工智能/加密货币/科学）以及 `finance`（金融/经济或未分类回退）。                           |
| `get_supply_chain_data`         | 干散货航运压力指数、海关流量、COMTRADE 双边贸易。                                                                                      |
| `get_tariff_trends`             | 全球贸易和定价指标：美国关税趋势（HTS 编码）、巨无霸指数、FAO 食品价格指数以及各国国债水平。                                                                 |
| `get_wto_trade_flows`           | 一个报告国与世界之间的 WTO 商品贸易流量（报告国使用 3 位 UN M49 代码，时间窗口为 1–30 年）。区分 `not_covered` 与故障。                                     |
| `get_chokepoint_status`         | 实时海上咽喉要道状态：每个咽喉要道的船舶过境计数（10 分钟节奏）、滚动过境摘要、每个港口的活动，以及静态参考数据和流量汇总。覆盖苏伊士、霍尔木兹、马六甲、曼德海峡、巴拿马等。                           |
| `get_consumer_prices`           | 各国消费者价格情报：30 天概览、品类级通胀、零售商价差（必需品篮子）、热门变动以及来源新鲜度。需要 `country_code`（目前仅填充了 `ae`）。                                    |
| `get_procurement_opportunities` | 仅限 Pro 的规范全球采购搜索；紧凑输出默认 10 条、最多 25 条。关键词相关性绝不表示投标资格。                                                               |
| `get_company_intelligence`      | 经 SEC 身份验证的逐公司情报：丰富化、带时间戳的信号、申报搜索与全市场重大 8-K 事件。                                                                    |
| `get_commodity_geo`             | 全球 71 个主要矿场（金、银、铜、锂、铀、煤）。                                                                                          |
| `get_mineral_production`        | 各国矿产开采/冶炼份额与 HHI（USGS MCS，BGS 补缺）。                                                                                 |
| `get_five_factor_scorecard`     | 冻结版 v1 五因素韧性评分卡：食品、能源、人口结构、科技与国防。可查询一个国家、官方集团或已验证的自定义集团，并保留输入可用性与来源信息。                                             |
| `list_five_factor_scorecards`   | 紧凑列出各国五因素支柱评分、档位、覆盖率和数据不足原因。读取数值前必须检查 `hasScore`；若为 false，零值只是数据不足占位符。完整证据账本请使用单项评分卡工具。                            |

### 能源

| 工具                        | 描述                                                                              |
| ------------------------- | ------------------------------------------------------------------------------- |
| `get_energy_intelligence` | 能源供应、价格、库存、中断和政策：EIA 石油库存、电力价格（Ember）、天然气库存（GIE）、燃料短缺、化石与可再生能源占比、活跃能源中断、政府危机政策。 |

### 地缘与安全

| 工具                           | 描述                                                    |
| ---------------------------- | ----------------------------------------------------- |
| `get_conflict_events`        | 活跃的 UCDP/伊朗冲突、带地理坐标的动荡、各国风险评分。                        |
| `get_country_risk`           | CII 评分 0-100、组成部分分解、旅行警示、各国 OFAC 敞口。快速，无需 LLM。        |
| `get_military_posture`       | 战区姿态 + 军事风险评分。                                        |
| `get_cyber_threats`          | URLhaus/Feodotracker 恶意软件 IOC、CISA KEV 目录、活跃 C2 基础设施。 |
| `get_sanctions_data`         | OFAC SDN 实体 + 各国制裁压力评分。                               |
| `get_news_intelligence`      | AI 分类的威胁新闻、GDELT 信号、跨来源情报。                            |
| `get_positive_events`        | 外交协议、人道主义援助、和平倡议。                                     |
| `get_social_velocity`        | Reddit r/worldnews + r/geopolitics 热门帖、互动评分。          |
| `get_china_decision_signals` | 保留规范溯源的六领域中国摘要，明确显示各领域降级；不暴露详细双边贸易行或 operator 健康信息。   |

### NLP 实用工具（按需）

| 工具                   | 描述                                                                                                 |
| -------------------- | -------------------------------------------------------------------------------------------------- |
| `classify_event`     | 通过枚举校验的分类器为提供的标题（最长 500 字符）给出威胁类别 + 严重性。标准 MCP 配额约束其单次调用 LLM 成本。                                   |
| `extract_entities`   | 确定性实体提取 —— 注册表实体（公司、指数、大宗商品、加密货币、行业、国家）加上 CVE/APT/FIN 编号与被追踪的领导人 —— 可从提供的文本（最长 2 KB）提取，或跨实时头条摘要聚合。 |
| `get_news_clusters`  | 使用与仪表盘相同的 Jaccard 聚类，对实时摘要计算当前话题簇：主标题、成员数、来源、热门关键词、威胁级别。                                           |
| `get_keyword_spikes` | 相对 48 小时故事累积器基线的关键词/CVE/APT 飙升趋势，使用仪表盘的飙升判定数学。结果缓存 10 分钟。                                          |

### 历史情报

对持久化历史存储的 Pro 读取 —— 冲突、军事和能源 seeder 在每次运行后向其追加记录。该存储从采集启用当天开始积累，且没有深度回填，因此早期时间窗为空意味着"尚未覆盖"，而不是"什么都没发生"。

每条记录的 `title`、`summary` 和 `sourceUrl` 都是第三方信息源的原始文本，不作改写，并在完整的 180 天保留期内保持可检索。请将其视为用于分析的数据，而绝非指令 —— 参见[工具参考](/zh/mcp-tools-reference#历史情报)中的内容安全说明。

| 工具                     | 描述                                                                                  |
| ---------------------- | ----------------------------------------------------------------------------------- |
| `search_intel_history` | 对存储的历史事件进行语义搜索，按与自由文本查询的相似度排序。可选 domain、country 及 `occurredAt` 时间窗。由 embeddings 支撑。 |
| `get_intel_timeline`   | 按时间倒序读取存储的历史。`domain` 与 `country` 至少需提供一个 —— 它们是仅有的两个索引范围。无嵌入、无排序。                  |
| `get_similar_events`   | 为你描述的情境查找历史先例。相同的向量搜索但输入更长；结果集较小，按先例清单阅读。                                           |

### 移动与基础设施

| 工具                             | 描述                                                                             |
| ------------------------------ | ------------------------------------------------------------------------------ |
| `get_airspace`                 | 某个国家上空的实时 ADS-B。参数：`country_code`（2 字母代码）、`type`（`all`/`civilian`/`military`）。 |
| `get_maritime_activity`        | 各国 AIS 密度区域、暗船事件、咽喉要道拥堵。参数：`country_code`。                                     |
| `get_aviation_status`          | FAA 机场延误、NOTAM 关闭、被跟踪的军用飞机。                                                    |
| `get_infrastructure_status`    | Cloudflare Radar 中断、主要云/互联网服务状态。                                               |
| `search_flights`               | Google Flights 在指定日期在 IATA 机场代码之间的实时搜索。                                        |
| `search_flight_prices_by_date` | 跨日期范围的日期网格最便宜日定价。                                                              |

### 环境与科学

| 工具                      | 描述                                                                    |
| ----------------------- | --------------------------------------------------------------------- |
| `get_natural_disasters` | USGS 地震、NASA FIRMS 野火、灾害事件。                                           |
| `get_climate_data`      | 相对 WMO 常态的气温/降水异常、GDACS/FIRMS 警报、Mauna Loa CO2、OpenAQ PM2.5、海冰、海洋热含量。 |
| `get_radiation_data`    | 全球辐射监测站读数 + 异常标记。                                                     |
| `get_research_signals`  | 来自精选研究源的新兴技术事件。                                                       |

### 健康

| 工具                   | 描述                                                         |
| -------------------- | ---------------------------------------------------------- |
| `get_health_signals` | 活跃疾病暴发（WHO/ECDC 等）和全球空气质量站点读数（OpenAQ/WAQI PM2.5）。用于健康风险筛查。 |

### 人道主义与流离失所

| 工具                      | 描述                            |
| ----------------------- | ----------------------------- |
| `get_displacement_data` | 按国家统计的难民和 IDP 数量（UNHCR 年度数据）。 |

### AI 情报

| 工具                         | 描述                                                                               | 成本  |
| -------------------------- | -------------------------------------------------------------------------------- | --- |
| `get_world_brief`          | 来自仪表板使用的 `news:insights:v1` 快照的预计算、有引用依据的世界情报简报。`geo_context` 为兼容性保留，不会重新聚焦种子快照。 | 缓存  |
| `get_country_brief`        | 带结构化来源链接的各国地缘 + 经济评估。支持分析框架。                                                     | LLM |
| `analyze_situation`        | 基于查询 + 上下文的临时地缘推断推理。返回置信度 + 支撑信号。                                                | LLM |
| `generate_forecasts`       | 新鲜概率估计（绕过缓存）。                                                                    | LLM |
| `get_forecast_predictions` | 预计算的缓存预测。快速。                                                                     | 缓存  |
| `get_forecast_scorecard`   | 缓存的预测结算校准与记分卡。                                                                   | 缓存  |

## API 覆盖

只有当确切的 `METHOD /api/...` 路径声明在某个工具的注册表 `_apiPaths` 条目中时，该 API 端点才算**由 MCP 暴露**。下表是这些声明来自 `api/mcp/registry/cache-tools.ts` 和 `api/mcp/registry/rpc-tools.ts` 的面向人类的呈现；它比公共 OpenAPI 目录更窄。

一个 REST 路由可以存在于 OpenAPI 中，但仍然是仅限 REST 的。parity 测试将这一区别保持明确：每个公共 OpenAPI 操作要么出现在 `_apiPaths` 中，要么在 `tests/mcp-api-parity.test.mjs` 中列出并附带一个已分类的排除原因。

当前的规范划分即以下命令所打印的内容：

```bash theme={null}
./node_modules/.bin/tsx --test tests/mcp-api-parity.test.mjs
```

该输出包含已覆盖、已排除和操作总数的计数。请将这些计数视为动态清单，而非产品文案；测试和注册表才是事实来源。

反向查询工作流：

1. 从 OpenAPI 页面复制确切的方法和路径，例如 `GET /api/research/v1/list-tech-events`。
2. 搜索此表。如果该路由出现，则调用所列的 MCP 工具。
3. 如果它未出现，则该 REST 路由未作为 API 等价路径通过 MCP 暴露。仅缓存的 MCP 工具可能仍返回相关领域数据，但它并不声称覆盖该 REST 路由。
4. 如需代码级验证，请在 `api/mcp/registry/cache-tools.ts` 和 `api/mcp/registry/rpc-tools.ts` 中搜索 `_apiPaths`；parity 测试会解释有意的仅限 REST 排除项。

| MCP 工具                         | 服务的 API 端点                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_market_data`              | `GET /api/market/v1/get-fear-greed-index`<br />`GET /api/market/v1/get-physical-divergence-index`<br />`GET /api/market/v1/get-physical-premiums`<br />`GET /api/market/v1/get-sector-summary`<br />`GET /api/market/v1/list-commodity-quotes`<br />`GET /api/market/v1/list-crypto-quotes`<br />`GET /api/market/v1/list-etf-flows`<br />`GET /api/market/v1/list-gulf-quotes`<br />`GET /api/market/v1/list-market-quotes` |
| `get_economic_data`            | `GET /api/economic/v1/get-ecb-fx-rates`<br />`GET /api/economic/v1/get-economic-calendar`<br />`GET /api/economic/v1/get-eu-yield-curve`<br />`GET /api/economic/v1/list-fuel-prices`<br />`GET /api/market/v1/get-cot-positioning`<br />`GET /api/market/v1/list-earnings-calendar`                                                                                                                                         |
| `get_tariff_trends`            | `GET /api/economic/v1/get-fao-food-price-index`<br />`GET /api/economic/v1/get-national-debt`<br />`GET /api/economic/v1/list-bigmac-prices`                                                                                                                                                                                                                                                                                 |
| `get_wto_trade_flows`          | `GET /api/trade/v1/get-trade-flows`                                                                                                                                                                                                                                                                                                                                                                                          |
| `get_energy_intelligence`      | `GET /api/economic/v1/get-energy-crisis-policies`<br />`GET /api/supply-chain/v1/get-fuel-shortage-detail`<br />`GET /api/supply-chain/v1/list-energy-disruptions`<br />`GET /api/supply-chain/v1/list-fuel-shortages`                                                                                                                                                                                                       |
| `get_consumer_prices`          | `GET /api/consumer-prices/v1/get-consumer-price-freshness`<br />`GET /api/consumer-prices/v1/get-consumer-price-overview`<br />`GET /api/consumer-prices/v1/list-consumer-price-categories`<br />`GET /api/consumer-prices/v1/list-consumer-price-movers`<br />`GET /api/consumer-prices/v1/list-retailer-price-spreads`                                                                                                     |
| `get_supply_chain_data`        | `GET /api/supply-chain/v1/get-shipping-stress`<br />`GET /api/trade/v1/get-customs-revenue`                                                                                                                                                                                                                                                                                                                                  |
| `get_chokepoint_status`        | `GET /api/intelligence/v1/get-country-port-activity`<br />`GET /api/supply-chain/v1/get-chokepoint-status`                                                                                                                                                                                                                                                                                                                   |
| `get_five_factor_scorecard`    | `GET /api/scorecard/v1/get-five-factor-scorecard`<br />`GET /api/scorecard/v1/get-bloc-scorecard`                                                                                                                                                                                                                                                                                                                            |
| `list_five_factor_scorecards`  | `GET /api/scorecard/v1/list-five-factor-scorecards`                                                                                                                                                                                                                                                                                                                                                                          |
| `get_climate_data`             | `GET /api/climate/v1/get-co2-monitoring`<br />`GET /api/climate/v1/get-ocean-ice-data`<br />`GET /api/climate/v1/list-air-quality-data`<br />`GET /api/climate/v1/list-climate-anomalies`<br />`GET /api/climate/v1/list-climate-disasters`<br />`GET /api/climate/v1/list-climate-news`                                                                                                                                     |
| `get_health_signals`           | `GET /api/health/v1/list-air-quality-alerts`<br />`GET /api/health/v1/list-disease-outbreaks`                                                                                                                                                                                                                                                                                                                                |
| `get_conflict_events`          | `GET /api/conflict/v1/list-iran-events`<br />`GET /api/conflict/v1/list-ucdp-events`<br />`GET /api/unrest/v1/list-unrest-events`                                                                                                                                                                                                                                                                                            |
| `get_news_intelligence`        | `GET /api/intelligence/v1/list-cross-source-signals`<br />`GET /api/intelligence/v1/search-gdelt-documents`                                                                                                                                                                                                                                                                                                                  |
| `get_country_risk`             | `GET /api/intelligence/v1/get-country-risk`                                                                                                                                                                                                                                                                                                                                                                                  |
| `get_country_brief`            | `GET /api/intelligence/v1/get-country-intel-brief`                                                                                                                                                                                                                                                                                                                                                                           |
| `get_social_velocity`          | `GET /api/intelligence/v1/get-social-velocity`                                                                                                                                                                                                                                                                                                                                                                               |
| `get_china_decision_signals`   | `GET /api/intelligence/v1/get-china-decision-signals`                                                                                                                                                                                                                                                                                                                                                                        |
| `get_company_intelligence`     | `GET /api/intelligence/v1/get-company-enrichment`<br />`GET /api/intelligence/v1/list-company-signals`<br />`GET /api/intelligence/v1/search-sec-filings`<br />`GET /api/intelligence/v1/list-material-events`                                                                                                                                                                                                               |
| `search_intel_history`         | `POST /api/intelligence/v1/search-intel-history`                                                                                                                                                                                                                                                                                                                                                                             |
| `get_intel_timeline`           | `GET /api/intelligence/v1/get-intel-timeline`                                                                                                                                                                                                                                                                                                                                                                                |
| `get_similar_events`           | `POST /api/intelligence/v1/get-similar-events`                                                                                                                                                                                                                                                                                                                                                                               |
| `get_natural_disasters`        | `GET /api/natural/v1/list-natural-events`<br />`GET /api/seismology/v1/list-earthquakes`<br />`GET /api/wildfire/v1/list-fire-detections`                                                                                                                                                                                                                                                                                    |
| `get_radiation_data`           | `GET /api/radiation/v1/list-radiation-observations`                                                                                                                                                                                                                                                                                                                                                                          |
| `get_infrastructure_status`    | `GET /api/infrastructure/v1/list-internet-outages`                                                                                                                                                                                                                                                                                                                                                                           |
| `get_airspace`                 | `GET /api/aviation/v1/track-aircraft`<br />`GET /api/military/v1/list-military-flights`                                                                                                                                                                                                                                                                                                                                      |
| `get_maritime_activity`        | `GET /api/maritime/v1/get-vessel-snapshot`                                                                                                                                                                                                                                                                                                                                                                                   |
| `get_military_posture`         | `GET /api/military/v1/get-theater-posture`                                                                                                                                                                                                                                                                                                                                                                                   |
| `get_displacement_data`        | `GET /api/displacement/v1/get-displacement-summary`                                                                                                                                                                                                                                                                                                                                                                          |
| `get_positive_events`          | `GET /api/positive-events/v1/list-positive-geo-events`                                                                                                                                                                                                                                                                                                                                                                       |
| `get_sanctions_data`           | `GET /api/sanctions/v1/list-sanctions-pressure`<br />`GET /api/sanctions/v1/lookup-sanction-entity`                                                                                                                                                                                                                                                                                                                          |
| `get_research_signals`         | `GET /api/research/v1/list-tech-events`                                                                                                                                                                                                                                                                                                                                                                                      |
| `get_prediction_markets`       | `GET /api/prediction/v1/list-prediction-markets`                                                                                                                                                                                                                                                                                                                                                                             |
| `get_forecast_predictions`     | `GET /api/forecast/v1/get-forecasts`                                                                                                                                                                                                                                                                                                                                                                                         |
| `get_forecast_scorecard`       | `GET /api/forecast/v1/get-forecast-scorecard`                                                                                                                                                                                                                                                                                                                                                                                |
| `classify_event`               | `GET /api/intelligence/v1/classify-event`                                                                                                                                                                                                                                                                                                                                                                                    |
| `extract_entities`             | `GET /api/news/v1/list-feed-digest`                                                                                                                                                                                                                                                                                                                                                                                          |
| `get_news_clusters`            | `GET /api/news/v1/list-feed-digest`                                                                                                                                                                                                                                                                                                                                                                                          |
| `analyze_situation`            | `POST /api/intelligence/v1/deduct-situation`                                                                                                                                                                                                                                                                                                                                                                                 |
| `search_flights`               | `GET /api/aviation/v1/search-google-flights`                                                                                                                                                                                                                                                                                                                                                                                 |
| `search_flight_prices_by_date` | `GET /api/aviation/v1/search-google-dates`                                                                                                                                                                                                                                                                                                                                                                                   |

没有声明 API 路径的工具仍通过 `tools/call` 返回数据，但不应将它们视为 REST 等价物：

* **缓存支撑的 bootstrap 聚合** —— 读取由 Railway cron 直接填充的 Redis key（例如 `get_aviation_status`、`get_cyber_threats`、`get_country_macro`，以及三个 EU Eurostat 工具）。
* **种子合成快照** —— `get_world_brief` 通过仪表板 bootstrap 路径读取已接受的 `news:insights:v1` payload；没有直接 REST 等价操作，也不会在请求时调用 LLM。
* **静态内存注册表** —— 过滤随 MCP 服务器 edge 二进制文件一起打包的一个常量，完全无需上游调用（例如 `get_commodity_geo`）。
* **没有公共 OpenAPI 行的实时工具** —— 运行时代理一次 HTTP 调用，其方法偏离公共规范，由一个同类工具覆盖规范声明的方法（例如 `generate_forecasts` 以 POST 方式请求 `/api/forecast/v1/get-forecasts`，而 `get_forecast_predictions` 拥有该 GET）。

在此表中，`covered` 意味着某个工具在 `_apiPaths` 中声明了确切的操作。`tests/mcp-api-parity.test.mjs` 中常见的仅限 REST 排除项：

* **`mutating`** —— 写入、队列、webhook、缓存刷新或持久化副作用。示例：`GET /api/aviation/v1/list-airport-delays` 有意仅限 REST，因为其 GET handler 会刷新/持久化机场延误缓存状态；`get_aviation_status` 转而暴露已填充的缓存支撑快照。
* **`llm-passthrough`** —— 每次调用直接进行的 LLM 工作，在通过 MCP 暴露之前需要专门设计的成本/威胁模型。
* **`fetch-on-miss`** —— 在缓存为冷时可能调用付费或受限流的上游，或接受不适合缓存打包的高基数标识符。排除原因必须包含一个强制的次要信号：`high-cardinality-input`、`paid-upstream` 或 `llm-cost`。示例：`GET /api/conflict/v1/list-acled-events`、`GET /api/infrastructure/v1/list-service-statuses`、`GET /api/supply-chain/v1/get-critical-minerals` 以及 `GET /api/aviation/v1/get-flight-status`。
* **`admin`** —— 位于明确管理员边界之后的仅限内部操作，例如管理员 key、仅限内部的中间件或仅限 cron 的路径。
* **`manual-mapping`** —— 参数化的缓存 key 或内联的 Redis/Convex handler 需要人工分诊。示例：`GET /api/research/v1/list-arxiv-papers`、`GET /api/research/v1/list-trending-repos` 以及 `GET /api/research/v1/list-hackernews-items`；`get_research_signals` 仅声明 `GET /api/research/v1/list-tech-events`。
* **`deferred-to-future-tool`** —— 其缓存 key 尚未被某个 MCP bundle 暴露的纯读取。示例：`GET /api/cyber/v1/list-cyber-threats` 计划用于未来的扩展领域工具，而非由如今缓存支撑的 `get_cyber_threats` 认领。

当前的后续跟踪项：

* [#4525](https://github.com/koala73/worldmonitor/issues/4525) —— 延后的纯读取 MCP 覆盖候选项。
* [#4526](https://github.com/koala73/worldmonitor/issues/4526) —— 手动映射和 fetch-on-miss 分诊。

有关完整的实时工具目录，请参见上方的[工具目录](#tool-catalog)；有关各工具详情，请参阅 [MCP 工具参考](/zh/mcp-tools-reference)。

## Prompt 与资源

除实时工具目录外，WorldMonitor 还暴露 MCP prompt 和资源，使客户端无需从零编排工具计划即可发现常见工作流并寻址稳定的数据切片。

### Prompt

`prompts/list` 返回六个工作流模板。`prompts/get` 会将所选模板渲染为一条用户消息，其中包含正确的 `tools/call` 序列和预置的 JMESPath 投影。

| Prompt               | 用途                                            |
| -------------------- | --------------------------------------------- |
| `country-briefing`   | 针对一个 ISO 3166-1 alpha-2 国家的国家风险、AI 情报简报和宏观指标。 |
| `energy-shock-watch` | 活跃能源中断、燃料短缺和政府危机政策；可选按国家聚焦。                   |
| `market-open-prep`   | 用于开盘扫描的轻量级股票、大宗商品和加密货币异动简报。                   |
| `conflict-pulse`     | 活跃的 UCDP 冲突事件以及带警报标记的热门新闻，可全球或针对一个国家。         |
| `route-risk-check`   | 针对一个咽喉要道的海上过境摘要与风险态势。                         |
| `freshness-audit`    | 跨市场、能源和咽喉要道 bootstrap 信封的缓存新鲜度检查。             |

`prompts/list` 和 `prompts/get` 是元数据/工作流发现方法：它们不计入 Pro 每日配额，但仍计入 60/分钟的每分钟限流器。

### 资源

资源分为三个访问类别。**公开具体资源**可匿名且不计配额地读取；**账户资源**只向已认证、绑定用户的凭据公开，但读取时不消耗配额；**URI 模板**是参数化且承载数据的资源，其访问要求由 `_meta["worldmonitor/access"]` 声明为 `free-account` 或 `subscription`，并按调用者适用的免费额度或订阅配额计量。

`resources/list` —— 具体、可匿名读取、不计配额：

| 资源 URI                                 | 支撑数据                                                                                                                                                                                                                  |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `worldmonitor://seed-meta/freshness`   | 仅股票市场数据 bootstrap 的写入年龄：`seed-meta:market:stocks` 的 `cached_at` 与 `stale`。**不**证明板块估值完整度 —— 请用 `get_market_data` 的 `valuationCoverage`（`sourceStatus`、unavailable/last-good/diagnostics）。廉价 seeder 健康探针 —— 无需认证，不计配额。 |
| `worldmonitor://account/mcp-allowance` | 当前已认证账户的每日调用使用量、剩余额度、UTC 重置时间，以及适用时的免费账户请求窗口状态。仅向绑定用户的 OAuth token 或 `wm_…` key 公开；读取不预留或消耗额度。                                                                                                                        |

`resources/templates/list` —— 参数化的 URI 模板。替换占位符，然后 `resources/read` 具体的 URI。客户端必须读取模板的 `_meta["worldmonitor/access"]`：`free-account` 模板允许已认证免费账户使用免费额度，`subscription` 模板需要有效订阅。计量方式与等价的 `tools/call` 对称：

| 资源 URI 模板                                  | 支撑数据                                                                                                 |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| `worldmonitor://countries/{iso2}/risk`     | 国家风险评分、组成部分分解、旅行警示和制裁敞口。`{iso2}` 是小写的 alpha-2，例如 `de` 或 `us`。                                        |
| `worldmonitor://chokepoints/{slug}/status` | 咽喉要道过境摘要和风险叙述。`{slug}` 是已发布的 kebab-case 咽喉要道 slug 之一，例如 `suez`、`strait-of-hormuz` 或 `bab-el-mandeb`。 |
| `worldmonitor://markets/{symbol}/quote`    | 单一符号的市场报价切片。`{symbol}` 是大写，例如 `AAPL`、`GC=F` 或 `BTC-USD`。                                             |

`resources/list` 和 `resources/templates/list` 是元数据，不消耗每日额度。对模板实例化的 `resources/read` 有意消耗与等价 `tools/call` 相同的调用者适用额度；它通过同一个分发器路由，因此承载数据的资源无法绕过免费账户上限或订阅配额。对公开具体资源和 `worldmonitor://account/mcp-allowance` 的 `resources/read` 不计额度。与每个 MCP 方法一样，所有这些仍计入 60/分钟限流器。有关每分钟限流与每日额度耗尽之间确切的 `-32029` 状态/头差异，请参阅 [MCP 错误目录](/zh/mcp-error-catalog#-32029--rate-limited-per-minute-or-daily)。

### MCP Apps（交互式 UI）

该服务器支持 [MCP Apps](https://modelcontextprotocol.io/extensions/apps/build)（扩展 `io.modelcontextprotocol/ui`，规范 `2026-01-26`）—— 即当调用某个关联工具时由宿主在沙箱化 iframe 中渲染的交互式视图。三个线路信号驱动它：

* **`initialize`** 在握手中声明支持。响应的 `capabilities.extensions` 会命名该扩展：`{"io.modelcontextprotocol/ui": {}}`。这是宿主（或 agent 就绪性扫描器）读取以将该端点归类为 MCP App 界面的协商信号 —— 下方的 `tools/list` 和 `resources/list` 条目就是它随后渲染的内容。
* **`tools/list`** 在工具上声明这种关联。每个关联了 UI 的工具都携带指向其 UI 资源的 `_meta.ui.resourceUri`（以及已弃用的扁平别名 `ui/resourceUri`）。
* **`resources/list`** 暴露 UI 资源本身，以及具体的数据资源（参数化的数据模板位于 `resources/templates/list`）：

| UI 资源 URI                                   | 关联工具                       | 渲染内容                                                             |
| ------------------------------------------- | -------------------------- | ---------------------------------------------------------------- |
| `ui://worldmonitor/country-risk.html`       | `get_country_risk`         | CII 评分、动荡/冲突/安全/新闻组成部分分解、旅行警示级别，以及 OFAC 制裁敞口。                    |
| `ui://worldmonitor/world-brief.html`        | `get_world_brief`          | 以可读段落呈现的预计算、有引用依据的全球情报简报，外加支撑性头条和来源文章。                           |
| `ui://worldmonitor/country-brief.html`      | `get_country_brief`        | 以段落呈现的 AI 合成各国简报，附带分析框架视角和支撑来源。                                  |
| `ui://worldmonitor/market-radar.html`       | `get_market_data`          | Fear & Greed 综合指标，外加各资产类别的报价表（股票、大宗商品、加密货币、海湾、板块），带有带符号、色彩编码的涨跌。 |
| `ui://worldmonitor/chokepoint-monitor.html` | `get_chokepoint_status`    | 各咽喉要道的滚动过境摘要（今日计数、周环比变化、油轮占比），并带有风险级别标记。                         |
| `ui://worldmonitor/news-intelligence.html`  | `get_news_intelligence`    | AI 分类的热门报道，带有类别、警报标记、国家和来源。                                      |
| `ui://worldmonitor/conflict-events.html`    | `get_conflict_events`      | 来自 UCDP 源的活跃武装冲突事件（交战方、暴力类型、国家、伤亡、日期）。                           |
| `ui://worldmonitor/natural-disasters.html`  | `get_natural_disasters`    | 近期地震（USGS 震级、地点、时间）和活跃野火（NASA FIRMS），分组显示。                       |
| `ui://worldmonitor/prediction-markets.html` | `get_prediction_markets`   | 按类别（地缘政治、科技、金融）分组的活跃事件合约赔率，每个市场带有一个概率条。                          |
| `ui://worldmonitor/forecasts.html`          | `get_forecast_predictions` | 以概率卡片（标题、领域、区域）呈现的 AI 生成地缘政治和经济预测。                               |

所有 UI 资源共享 `mimeType: text/html;profile=mcp-app`。

对 `ui://` URI 的 `resources/read` 返回自包含的 HTML 视图。与数据资源不同，`ui://` 读取是**公开且豁免配额的** —— 该模板不承载数据，也不产生上游调用，因此宿主可以在无凭据、不触及 Pro 每日上限的情况下预加载它（agent 就绪性扫描器也可以获取它）。该视图完全自包含（无外部资源），并通过标准的 MCP Apps `postMessage` 桥（`ui/initialize` → `ui/notifications/tool-result` → `ui/notifications/size-changed`）与宿主通信。

有关完整的 MCP Apps 契约 —— 宿主流程、安全态势、各小部件清单、源文件以及 docs-stat 漂移检查 —— 请参阅 [MCP Apps](/zh/mcp-apps)。

## JSON-RPC 示例

服务端使用直接 API key —— 将其作为 `X-WorldMonitor-Key` 发送，**不要**作为 bearer token。

```bash theme={null}
WM_KEY="wm_0123456789abcdef0123456789abcdef01234567"

# 1. List tools
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/list"}'

# 2. Call a cache tool
curl -s https://worldmonitor.app/mcp \
  -H "X-WorldMonitor-Key: $WM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":2,
    "method":"tools/call",
    "params":{"name":"get_country_risk","arguments":{"country_code":"IR"}}
  }'
```

如果你已完成 OAuth 流程并持有来自 `/api/oauth/token` 的 access token，则将其作为 `Authorization: Bearer $TOKEN` 传入。

## 响应结构

工具响应使用标准 MCP content block 格式：

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "{...json payload...}" }
    ],
    "isError": false
  }
}
```

对于缓存工具，JSON payload 包含 `cached_at`（最旧贡献数据点的 ISO 时间戳）和 `stale`（布尔值 —— 当任意贡献 seed 超出其 per-key 新鲜度预算时为 `true`），以便模型可对新鲜度进行推理。

## 数据新鲜度

所有缓存工具都从由 Railway cron seeder 写入的 Redis key 读取。典型新鲜度：

| 领域                  | 典型新鲜度    |
| ------------------- | -------- |
| 市场（盘中）              | 1–5 分钟   |
| 航班（ADS-B）           | 1–3 分钟   |
| 海事（AIS）             | 5–15 分钟  |
| 冲突 / 动荡             | 15–60 分钟 |
| 宏观 / BIS / Eurostat | 每日–每周    |
| IMF WEO             | 每月       |

每个 key 的 seed 级健康状态：[status.worldmonitor.app](https://status.worldmonitor.app/)。

## 错误

MCP handler 在三个独立层次上发出失败信号 —— **HTTP 状态**、**JSON-RPC `error.code`**，以及 **`result.content[0].text` 内部的 soft-behavior envelope** —— 一次失败可能触及任意组合。

| 层次            | 常见形态                                                                                                                           | 查看位置                                                            |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| HTTP 状态       | `200`（JSON-RPC 默认）、`400`、`401`、`403`、`404`、`405`、`406`、`429`、`503`                                                             | `WWW-Authenticate` / `Retry-After` / `X-Billing-Verification` 头 |
| JSON-RPC      | `-32001` 认证 · `-32002` 权益拒绝 · `-32003` 数据不可用 · `-32004` 重放光标缺失 · `-32029` 速率受限 · `-32600` 请求无效 · `-32602` 参数错误 · `-32603` 内部错误 | `error.code` + `error.message`                                  |
| Soft envelope | `_budget_exceeded`（响应过大）、`_jmespath_error`（投影失败）                                                                               | 将 `result.content[0].text` 解析为 JSON                             |

由外向内分诊：HTTP 状态 → JSON-RPC 错误码 → soft envelope。完整的每种形态参考（触发条件、配对状态、恢复方式、示例 payload）位于 [MCP 错误目录](/zh/mcp-error-catalog)。几个高频要点：

* **401 + `-32001`** 携带一个 `WWW-Authenticate` 头，其 `resource_metadata` 指向 `/.well-known/oauth-protected-resource`。支持 RFC 9728 的客户端会在此头上自动重新运行 OAuth 流程。
* **403 + `-32002`** 是已经发出的终止性权益拒绝。`lapsed-subscription` 只会在罕见竞态中出现：服务方确认的失效在 Pro 调用预检查通过后、执行中途才落地；若预检查时已经确认覆盖期结束，OAuth 身份会改走受限、按额度计量的 `free_account` 路径。`upgrade-required` 表示免费账户调用了订阅工具，或不具备免费账户资格的非免费权益不足。该错误不携带 `WWW-Authenticate`，重新运行 OAuth 无法修复这一次已经发出的拒绝。
* **429 + `-32029`** 是 Pro 每日上限（`Retry-After: <距离 UTC 午夜的秒数>`）。每分钟速率限制在 HTTP 200 内返回 `-32029`，而不是 429 —— 区别请见错误目录。
* **Soft envelope 返回 HTTP 200** 且没有 JSON-RPC `error` 字段 —— 仅检查 JSON-RPC 层的客户端会静默地将它们视为成功。务必解析 `result.content[0].text` 并在将 payload 当作数据消费前检查带前导下划线的判别 key（`_budget_exceeded`、`_jmespath_error`）。

## 相关

* [WebMCP](/zh/webmcp) —— 操作可见 WorldMonitor 网站的实验性、标签页绑定工具
* [MCP 快速入门](/zh/mcp-quickstart) —— 五分钟从零到首次调用的演练
* [JMESPath 指南](/zh/mcp-jmespath) —— 投影语法 + 12 个实例
* [MCP 工具参考](/zh/mcp-tools-reference) —— 各工具参数和 `curl` 示例
* [MCP 错误目录](/zh/mcp-error-catalog) —— 服务器发出的每个 JSON-RPC 错误码、HTTP 状态和 soft envelope
* [认证概览](/zh/authentication) —— 浏览器 vs bearer vs OAuth
* [API 参考](/zh/api-reference) —— 通过 REST 获取同样的数据
* [Pro 功能](https://www.worldmonitor.app/pro)