ioda-outages-mcp-server

---

概要

IODA の公開 v2 API を使用して、インターネット障害の証拠を確認します。国、地域、自律システムを特定し、最近の検出結果と測定範囲を確認したうえで、イベント、アラートの遷移、エンティティ別の障害ランキング、数値シグナルを調査できます。API キーは不要で、stdio またはステートレスな Streamable HTTP 経由で動作します。

ツール

ツール	説明
ioda_search_entities	国、地域、ASN、または geoasn の名前やコードを特定します
ioda_get_status	3 種類の数値ソースにおける最近の検出証拠と測定範囲を確認します
ioda_find_outages	エンティティ単位または全体の、期間が重なる障害イベントを取得します
ioda_summarize_outages	IODA の期間別障害スコアに基づき、1 種類のエンティティを順位付けします
ioda_get_signals	BGP、アクティブな IPv4 /24 プロービング、または Merit テレスコープの数値系列を取得します
ioda_get_alerts	ソースのベースラインとともに、検出と復旧の遷移を取得します

機能リファレンス

ioda_search_entities _ツール

• 必須の entityType: country | region | asn | geoasn（geoasn は、ある地域または国に属する 1 つの ASN）を指定し、query（前後の空白を除いて最大 200 文字）または entityCode を選択します。両方を省略すると、そのタイプの一覧が返されます。国コードは 2 文字、地域コードは IODA の数値コード、ASN は 10 進数の数字、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 秒の公開猶予時間内に終了したことを意味します。これは 3 つのソースすべてに適用され、アップストリームの SLA ではなくサーバーのポリシーです。この猶予時間内の末尾の null は nullCount ではなく pendingCount として数えられます。
• 各 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 を追加してください。拡張を 0 にすると、長時間継続している検知を見逃すことがあります。

---

ioda_summarize_outages _ツール

• entityType、from、until は必須です。1つのエンティティを指定する場合は entityCode を、1つの国、地域、ASN、または geoasn 内で entityType のエンティティを順位付けする場合は relatedToType と relatedToCode を指定します（両方を指定するか、どちらも指定しないでください。entityCode とは併用できません）。limit の範囲は 1～1,000、デフォルトは 20 で、提供上限は 100 です。extendWindowSeconds の範囲は 0～12,096,000、デフォルトは 1,209,600 で、提供上限は 1,209,600 です。source 入力はありません。
• IODA の順序（scores.overall の降順）で summaries を返し、pagination と provenance も含みます。各行には entity、event_cnt（マージ前の IODA のソースイベント数）、および変更されていない scores が含まれます。scores は overall と、各 <source>.<method> キーのイベントスコアの合計で構成されます。IODA は異なるソースの重複するイベントをマージし、マージした各イベントのスコアを各ソースのスコアの積として算出し、マージしたイベントのスコアを合計して overall を算出します。
• スコアは1回のリクエスト内で行を順位付けするためのウィンドウ合計であり、現在の状態を示すものではなく、ウィンドウの異なるリクエスト間で比較できません。型だけを指定した大規模な順位付け（たとえば、すべての地域）はタイムアウトすることがあります。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 エラーになります。from、until、step、nativeStep、および null 値によって、バケット境界の整合性と観測値の欠落が保たれます。目標値を小さくすると、時間分解能が低下します。

---

ioda_get_alerts _ツール

• from と until は必須です。エンティティ、ソース、および関連スコープのフィルターは ioda_find_outages と同じものを任意で指定できます。関連スコープはページ 0 でのみ提供されます。これは IODA がスコープを指定したアラートの取得を続行できないためです。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 日間です。より長い調査は、隣接するウィンドウに分割してください。
• ページネーションはゼロベースです。フィルターと limit を変更せずに nextPage をたどってください。more: "possible" は、継続の可能性を示しますが、総件数が判明しているわけではありません。limit を変更した場合は、ページ 0 からやり直してください。
• 数値入力には、提供上限の最大 10 倍まで指定できます（limit は 100、maxPoints は 2,000、lookbackHours は 24、extendWindowSeconds は 1,209,600）。より大きな値を指定した場合は上限値で提供され、通知には要求値、提供値、残りのデータを取得するためのルートが示されます。最小値を下回る値や受け入れ可能な最大値を超える値は、引数の検証でエラーになります。
• 共通のリクエスト間隔制御により、同時進行のリクエストは 1 件に制限され、リクエスト開始の間隔は最低 2 秒になります。呼び出しの期限は 45 秒です。同時に複数の調査を行わないでください。
• IODA が示すのは、マクロな接続状況です。検出されなかったことは、問題がないことを意味しません。ソーススコアは普遍的な深刻度を示すものではなく、観測データから停止の原因や個々のオフィスの接続状況を特定することもできません。

エージェントに適した出力：

• 出典情報 — エンドポイントへのリンク、取得時刻、元の Georgia Tech Research Corporation の帰属表示が、返される証拠に付属します。applied には実際に適用された入力が反映されます。
• 不確実性の明示 — null サンプル、欠損フィールド、ソースのカバレッジ、コンポーネントの部分的な障害は、それぞれ区別して保持されます。
• 完全で上限のあるレスポンス — content[] と structuredContent には、エンリッチメントを含む同じデータが格納されます。上流のレスポンス本文は 2 MiB、結合後のレスポンスは 96 KiB が上限です。これを超える場合、レコードを破棄する代わりに、より小さい呼び出しを指定する response_too_large が返されます。

はじめに

以下を 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/	6 つの読み取り専用ツール
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 呼び出しをラップし、未加工データの検証 → ドメイン型への正規化 → 出力スキーマの返却を行ってください。不足しているフィールドを捏造せず、両方のレスポンス形式を完全な状態に保ってください

コントリビューション

Issue を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0。詳細は LICENSE を参照してください。IODA データの著作権は引き続き Georgia Tech Research Corporation に帰属し、元データの利用条件が適用されます。