ioda-outages-mcp-server

---

概述

通过 IODA 的公共 v2 API 获取互联网中断证据。解析国家、地区和自治系统；检查近期检测结果和测量覆盖范围；随后调查事件、警报状态转换、各实体的中断排名及数值信号。支持通过 stdio、无状态 Streamable HTTP，或上方的公共托管端点运行，无需 API 密钥。

工具

工具	描述
ioda_search_entities	解析国家、地区、ASN 或 geoasn 名称及代码
ioda_get_status	检查近期检测证据，以及三个数值来源的覆盖范围
ioda_find_outages	获取某个实体或全局范围内时间重叠的中断事件
ioda_summarize_outages	按 IODA 的每时间窗口中断评分，对某一类型的实体进行排名
ioda_get_signals	获取 BGP、主动 IPv4 /24 探测或 Merit telescope 数值序列
ioda_get_alerts	获取检测和恢复状态转换及各来源基线

功能参考

ioda_search_entities _工具

• 必填 entityType: country | region | asn | geoasn（geoasn 是某个地区或国家内的一个 ASN）；选择 query（修剪后最多 200 个 UTF-16 代码单元）或 entityCode，也可以两者都省略以列出该类型。国家代码使用两个字母，地区使用 IODA 数字代码，ASN 使用十进制数字，geoasn 将 ASN 与地区或国家代码组合在一起（40934-576、59962-IR）。
• 可选的 relatedToType 和 relatedToCode 用于列出某个国家、地区、ASN 或 geoasn 内属于 entityType 的实体；两者必须同时提供或同时省略，且必须提供 entityType，不得提供 entityCode，范围条件可与 query 组合使用。请对该解析器分页，以便为单个中断调查选择代码。
• limit 为 1–1,000，默认值为 20，实际最多返回 100 条；page 从 0 开始。返回原始 entities、pagination 和 provenance；元数据匹配并不能证明测量覆盖范围。

---

ioda_get_status _工具

• 必填 entityType（country、region、asn 或 geoasn）和 entityCode；lookbackHours 为 1–240，默认值为 6，实际最多处理 24 小时，并会通过提示说明未覆盖的更早时间段。收集返回的 window 内的事件、警报以及 bgp、ping-slash24 和 merit-nt 摘要。
• detection 为 observed、none_returned 或 unknown；来源的 coverage 独立取值为 recent、stale、no_data 或 unknown。recent 表示最新的已完成观测在调用时间起 1,800 秒的发布宽限期内结束，该要求对三个来源均相同；这是服务端策略，并非上游 SLA。宽限期内末尾的 null 值计入 pendingCount，而非 nullCount。
• 每个 signals 条目都包含该来源对应的 IODA unit（Visible /24s、Up /24s、Unique Source IPs）；latest、minimum 和 maximum 均以该单位表示。
• components 会披露部分失败情况，并支持使用独立工具恢复。事件和警报分页会携带续页元数据；原始样本来自 ioda_get_signals。所有组件均失败时，调用会失败；未知的国家、地区或 geoasn 代码会报错 entity_not_found。

---

ioda_find_outages _工具

• 必填 from 和 until；可选 entityType（country、region、asn 或 geoasn）、entityCode 和 source: bgp | ping-slash24 | merit-nt | gtr。如需全局范围，请省略实体筛选条件；提供代码时必须同时提供其类型。可选的 relatedToType 和 relatedToCode 用于将结果限定为某个国家、地区、ASN 或 geoasn 内属于 entityType 的实体（两者必须同时提供或同时省略，且必须提供 entityType，不得提供 entityCode）。limit 为 1–1,000，默认值为 20，实际最多返回 100 条。
• 返回来源 events、pagination 和 provenance。分数保留其来源含义；开始时间可能早于窗口，而截断在 until 的结束时间并不能证明已恢复。
• includeAlerts 默认为 false；extendWindowSeconds 为 0–12,096,000，实际最多为 1,209,600。省略时，若提供 entityType，默认值为 1,209,600；若未提供，则为 86,400，因为大范围的全局扩展可能导致超时；实际应用的值会回显，并且提示会说明全局默认值。跨越多日窗口的全局搜索仍可能超时：请缩小窗口或添加 entityType。将扩展设为零可能会漏掉持续时间较长的检测结果。

---

ioda_summarize_outages _工具

• 必填 entityType、from 和 until；可选 entityCode，用于指定单个实体；或使用 relatedToType 和 relatedToCode，在单个国家、地区、ASN 或 geoasn 范围内对 entityType 实体进行排序（两者必须同时提供或都不提供，且不能同时提供 entityCode）。limit 范围为 1–1,000，默认值为 20，实际最多处理 100；extendWindowSeconds 范围为 0–12,096,000，默认值为 1,209,600，实际最多处理 1,209,600。没有 source 输入参数。
• 按 IODA 的顺序返回 summaries，按 scores.overall 降序排列，并包含 pagination 和 provenance。每行包含 entity、event_cnt（IODA 合并前的源事件计数）以及未经修改的 scores：overall，加上每个 <source>.<method> 键对应的事件分数总和。IODA 会合并来自不同来源的重叠事件，将每个合并事件的分数计算为其来源分数的乘积，并将合并后的事件分数累加为 overall。
• 分数是用于对单次请求中的行排序的时间窗口总值，不代表当前状态，也不能与时间窗口不同的请求进行比较。仅按类型进行大范围排序（例如所有地区）可能会超时；请添加 entityCode 或相关范围。结果为空不代表一切正常。

---

ioda_get_signals _工具

• 必填实体对（entityType 可以是 geoasn）、from、until 和 source: bgp | ping-slash24 | merit-nt（此处 gtr 和 ucsd-nt 不是数值来源）。maxPoints 范围为 1–20,000，默认值为 200，实际最多处理 2,000：这是上游聚合目标，并非返回样本数的硬性上限。
• 在 series 中返回所有数值子类型，以及特定于来源的 semantics（测量值、IODA 的 unit、注意事项）和 provenance。未知的国家、地区或 geoasn 代码会导致 entity_not_found 错误。返回的 until 是不包含在内的分桶边界；对齐操作可能会超出请求的边界。粗粒度序列会附带说明：其值不一定等于返回的较细粒度分桶值的非加权平均值，且非空聚合无法证明较细分辨率的数据覆盖完整。值、空值和单位保持不变；粗粒度序列的状态覆盖情况仍为 unknown。

---

ioda_get_alerts _工具

• 必填 from 和 until；可选实体、来源和相关范围筛选条件与 ioda_find_outages 相同；由于 IODA 无法继续获取带范围的告警，相关范围仅在第 0 页生效。limit 范围为 1–1,000，默认值为 20，实际最多处理 100；extendWindowSeconds 范围为 0–12,096,000，默认值为 0，实际最多处理 1,209,600。
• 返回 alerts、pagination 和 provenance，并保留来源报告的 level、condition、value 和 historyValue。对于 bgp、ping-slash24 和 merit-nt，value 和 historyValue 使用来源单位；对于 gtr，它们是 IODA Traffic 除以 1,000,000 后截断的值。缺少状态转换信息并不能证明网络正常，也不能排除更早开始的事件。

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并提供结构化日志记录和可选的 OpenTelemetry 跟踪。

IODA 专属功能：

• 从固定的 HTTPS API 源站进行无需密钥的读取；无需本地数据库或原生辅助程序。
• 历史时间窗口使用 UTC 整数 Unix 秒：from < until <= now，最长 31 天。警报会包含两个边界处的状态变化（通过扩展窗口实现）；事件和摘要会包含在 until 时开始的内容。相邻窗口可能重复包含边界检测结果。信号边界表示对齐后的时间桶；对于选择规则不同的组件，状态会回显请求的时间窗口。
• 事件、警报和排名中的 ignoreMethods: string[] 会在构建事件和评分前，于上游排除检测结果：可使用 source.method、source.* 或 *.method，其中来源包括 bgp、ping-slash24、merit-nt 和 gtr。系统会规范大小写和空白，并去除重复项；空数组不会排除任何内容。格式错误的条目和 *.* 会触发 invalid_arguments；同时指定 source 及其对应的 source.* 会触发 invalid_ignore_methods。翻页和排名下钻查询时，请固定排除项；提供方的分数和顺序会保留。
• 每个相关范围的中断响应都会警告成员覆盖情况尚未核实，即使页面很短或为空也一样。请使用相同的实体类型、范围和 limit 对 ioda_search_entities 翻页，然后使用原始时间窗口、来源/排除项、扩展量和翻页 limit，逐个查询选定的代码；每个响应都会提供具体调用方式。pagination.more 表示行分页是否还有后续页面，不代表范围完整性。
• 分页从 0 开始；使用不变的筛选条件和 limit 跟进 nextPage。more: "possible" 表示可能还有后续内容，而非已知总数；更改 limit 后，请从第 0 页重新开始。
• 数值输入最多可超过其服务上限 10 倍（limit 为 100、maxPoints 为 2,000、lookbackHours 为 24、extendWindowSeconds 为 1,209,600）；超出服务上限的值会按上限处理，通知会指出请求值、实际服务值，以及获取剩余内容的调用方式。低于最小值或超过可接受最大值的输入会导致参数验证失败。
• 共享请求节流机制允许同时有一个请求在途，并要求每次请求启动之间至少间隔两秒；每次调用的截止时间为 45 秒。请避免并发调查。
• IODA 描述的是宏观层面的连接状况。未检测到故障不代表一切正常；来源评分并非通用严重程度指标，观测结果也无法确定中断原因或单个办公室的连接状况。

便于 Agent 使用的输出：

• 来源信息——返回的证据附带端点链接、获取时间和 Georgia Tech Research Corporation 的原始署名；applied 会回显生效的输入。
• 明确标示不确定性——将空样本、缺失字段、来源覆盖情况和部分组件故障分别呈现。
• 完整且有界的响应——content[] 和 structuredContent 携带相同的数据，包括补充信息。上游响应正文上限为 2 MiB，组合响应上限为 96 KiB；超过上限时，会通过 response_too_large 指出更小范围的调用方式，而不会丢弃记录。

开始使用

公共托管实例

公共实例位于 https://ioda-outages.caseyjhand.com/mcp，无需安装。它使用 Streamable HTTP；不同客户端的配置格式各不相同。

对于 Claude Code：

claude mcp add --transport http ioda-outages-mcp-server https://ioda-outages.caseyjhand.com/mcp

对于 Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "ioda-outages-mcp-server": {
      "type": "streamableHttp",
      "url": "https://ioda-outages.caseyjhand.com/mcp"
    }
  }
}

对于 Cursor（mcp.json）：

{
  "mcpServers": {
    "ioda-outages-mcp-server": {
      "url": "https://ioda-outages.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在 Settings → Connectors 下添加远程服务。

自托管 / 本地

将以下内容添加到 MCP 客户端配置文件中。IODA 无需 API 密钥。

{
  "mcpServers": {
    "ioda-outages-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/ioda-outages-mcp-server@latest"]
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "ioda-outages-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/ioda-outages-mcp-server@latest"]
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "ioda-outages-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/ioda-outages-mcp-server:latest"]
    }
  }
}

对于 Streamable HTTP，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 可向 api.ioda.inetintel.cc.gatech.edu 发起出站 HTTPS 请求。无需 API 密钥或账户。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/ioda-outages-mcp-server.git

2. 进入目录：

cd ioda-outages-mcp-server

3. 安装依赖：

bun install

4. 配置环境（可选）：

cp .env.example .env
# no server-specific variables; edit framework overrides as needed

配置

服务没有自己的设置。通用框架变量如下：

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_HOST	HTTP 绑定地址。	127.0.0.1
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_HTTP_ENDPOINT_PATH	MCP 端点路径。	/mcp
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<app-root>/logs
OTEL_ENABLED	启用 OpenTelemetry。	false

完整的框架覆盖项列表请参见 .env.example。

运行服务

本地开发

• 构建并运行生产版本：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• 运行检查和测试：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

项目结构

目录	用途
src/index.ts	服务身份、工具注册、服务生命周期
src/mcp-server/tools/definitions/	六个只读工具
src/mcp-server/tools/ioda-common.ts	共享的输入规范化、渲染和响应预算
src/services/ioda/	固定源 API 客户端、模式、请求节流、状态评估
tests/	契约、服务和格式化测试
docs/design.md	领域契约、设计决策、API 依据
docs/tree.md	生成的目录清单

开发指南

开发指南和架构规则请参见 CLAUDE.md，领域契约请参见 docs/design.md。简而言之：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.signal 进行取消，使用 ctx.enrich 提供已应用的输入和通知
• 在 src/index.ts 中的 createApp() 数组内注册新工具
• 包装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出模式；绝不捏造缺失字段，并确保两个响应表面都完整

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0；详见 LICENSE。IODA 数据保留其 Georgia Tech Research Corporation 版权，并继续受来源条款约束。