first-epss-mcp-server

---

概要

Empirical Security が生成し、FIRST が公開する FIRST EPSS に基づき、今後 30 日以内に観測される CVE の悪用を日次で予測します。スコアの照会、日々の推移の確認、スコアや年による CVE の検索、呼び出し元から提供された CVSS の深刻度との組み合わせが可能です。公開 API の利用にキーや登録は必要ありません。

ツール

ツール	説明
epss_get_scores	指定した CVE の現在または過去の EPSS 確率とパーセンタイルを取得します
epss_get_timeseries	日次履歴、指定日の変化、ピーク、欠損、モデルの切り替わりを確認します
epss_query_threshold	スコアの範囲（上下限を含む）、CVE の年、またはデータセットへの最近の追加に基づいて CVE を検索します
epss_prioritize_cves	EPSS と呼び出し元から提供された CVSS 深刻度を使い、設定可能な修正優先度を割り当てます
epss_list_reference	スコアの解釈、モデル、対象範囲、優先順位付けの慣例について説明します

機能リファレンス

epss_get_scores _tool

• cves は最大5,000件まで、配列または空白／カンマ／セミコロン区切りの文字列で指定できます。大文字と小文字、および Unicode ダッシュは正規化されます。batchOffset（デフォルトは0）から最大500件の一意な識別子を処理します。省略可能な date（2021-04-14 から今日まで、UTC）を指定すると過去のスナップショットを選択できます。省略または空欄の場合は、利用可能な最新のスナップショットが使われます
• 各スコアには epss、percentile、date、modelVersionSource（csv_header、published_schedule、unavailable）が含まれ、EPSS の降順で並びます
• unscoredCves では invalid_format と not_returned が区別されます。スコアがない場合は不明であり、ゼロではありません
• snapshot_unavailable は、FIRST が提供できない日付指定のスナップショットを示します。別の日付を選択するか、省略してください。公開済みスナップショットから省かれた CVE は not_returned のままです

---

epss_get_timeseries _tool

• cves／date／batchOffset は同じ入力を使用します。1回の呼び出しで最大50件の一意な識別子を処理します
• 各項目では、基準となる current と、その前の最大30日分の観測値を series に組み合わせ、さらに missingDates、peak、delta7d／delta30d を含めます。これらの差分には正確な暦上の基準日が必要で、基準がない場合は unavailableDeltas に表示されます
• modelBoundariesCrossed と各比較の crossesModelBoundary フラグは、公開されたモデルの移行を示します。いずれもスコアが変動した理由を説明するものではありません
• 算出された差分は小数点以下9桁に丸められます。元のスコアの精度は維持されます。重複のない直前の期間を取得するには、previousAnchorDate を基準日にしてください。このポインターは、公開済みスナップショットの存在を保証しません

---

epss_query_threshold _tool

• 包含的な minEpss／maxEpss／minPercentile／maxPercentile の範囲、year、addedWithinDays は相互に適用され、過去の日付を指定する date は任意です。少なくとも1つのフィルターが必要で、範囲の上下限は順序どおりでなければなりません。そうでない場合は invalid_filter_combination になります。addedWithinDays はデータセットへの追加時期を示すもので、date は無視されます
• 1回の呼び出しにつき、EPSS の降順で候補ページを1つ返します。正のセーフ整数である limit（デフォルトは100）と offset を指定します。10,000を超える上限値は10,000に制限されます。通知には要求値と適用値が報告され、filters.limit と pagination.limit の両方に適用後の上限値が反映されます。year を指定した場合、candidateTotal は広範な候補数を数え、total は null（totalRelation: "unknown"）になります。そのため、フィルター適用後のページが空でも hasMore: true となることがあります
• 完全なスコア行は、シリアライズされたレスポンスの各面で65,536バイトの制限内に収まります。行が省かれた場合、pagination.budgetLimited は true になり、withheldCount は確認済みの一致項目のうち省かれた件数を数えます。examinedCount は確認したすべての候補を引き続き数えます。nextOffset は、年によるフィルタリングを含め、省かれた最初の一致項目の元の候補位置から再開します
• 同じフィルターと limit を使い、provenance.scoreDates[0] を date に、nextOffset を offset に指定して続行します

---

epss_prioritize_cves _tool

• 最大5,000件の { cve, cvssBaseScore? } エントリー（CVSS は0～10、呼び出し元が指定）を対象に、最新または任意の日付指定の EPSS を使用します。batchOffset から最大500件の一意な CVE を処理します。CVSS が異なる同一 CVE（未指定と指定の違いを含む）は conflicting_cvss エラーになります。利用できない日付指定スナップショットは snapshot_unavailable エラーになります
• デフォルトは severityThreshold: 7 と likelihood: { metric: "epss", threshold: 0.10 } で、どちらも境界値を含みます。metric: "percentile" は明示的に選択できる代替指標です。いずれも FIRST による推奨値ではありません
• ティアは act_now（深刻度が高く、可能性も高い）、scheduled（深刻度が高く、可能性は低い）、monitor（深刻度は低く、可能性は高い）、defer（深刻度も可能性も低い）です。CVSS がない場合は epssOnly に分類され、EPSS がない場合は CVSS を保持したまま unscoredCves に分類されます

---

epss_list_reference _tool

• topic：interpretation、models、coverage、prioritization、または all（デフォルト）
• 出典リンク付きの静的なガイダンスで、verifiedAt の日付が含まれます。上流へのリクエストは行いません

バッチの続き

4 つの動的ツールでは、通知、出典情報、フィルター、ページネーションを含む、JSON シリアライズされた各 content 配列と structuredContent オブジェクトが UTF-8 で 65,536 バイトに制限されています。しきい値の探索では前述のとおり候補を続けて処理し、CVE を指定するツールでは以下のバッチ継続方法を使用します。

スコア、時系列、優先順位付けでは、スコア行、履歴項目、未スコア項目を全体のまま保持します。processedCount は無効な識別子を含む処理対象数を引き続きカウントし、returnedCount は保持された完全な項目数を、withheldCount はバイト数制限によって省略された処理済み項目数をカウントします。deferredCount は一度も照会されなかった項目数をカウントします。withheldCves と deferredCves の配列型は維持され、リスト全体を収められない場合は、それぞれの *Complete フラグでプレビューであることを明示します。budgetLimited は、応答が短縮された場合にそのことを示します。

未スコア、保留、繰り越しのテキストに含まれる不正な識別子は、Markdown 用にエスケープされた JSON 文字列リテラルです。JSON デコードにより、埋め込みの CR、LF、タブ、バックスラッシュを含め、正規化された識別子を復元できます。正規の CVE は通常の識別子として保持されます。バッチオフセットを使い切った場合は、上流への照会やスコア欠落の申告を行わず、完了を報告します。しきい値の通知では、検索結果が全体的にない場合、候補オフセットを使い切った場合、該当する年のページに一致項目がない場合を区別し、最終ページも対象に含めます。

nextBatchOffset がある場合は、元の cves と、nextBatchOffset を batchOffset として、provenance.scoreDates[0] を date として指定し（スコア日付が返されなかった場合は要求した日付を維持して）、同じツールを呼び出してください。優先順位付けでは、元の cvssBaseScore、severityThreshold、likelihood もすべて維持します。オフセットは、無効な項目も含め、入力順で最初に出現する正規化済みの一意な識別子を数えます。スコア順の並べ替えによってオフセットは変わりません。nextBatchOffset がなくなるまで続けてください。末尾を超えるオフセットには、項目が空であることを明示した集計が返されます。リストは確認用です。元のバッチを使って続行すれば、リストがプレビューの場合でも項目を保持できます。

機能

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、差し替え可能な認証（none／jwt／oauth）、差し替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレースに対応した構造化ログを提供します。

FIRST EPSS 固有の機能：

• FIRST の公開 API に対する、コーパス同期ではなく、上限付きバッチによるキー不要の照会
• API リクエストの共有ペーシング、一時的な障害時の再試行、キャンセル、45 秒の呼び出し全体の期限
• 一致する日次 CSV ヘッダー、または明示的に日付指定されたリクエストとそれ以前の履歴について検証済みの公開スケジュールに基づくモデル情報。現在の基準日の検証に失敗した場合は、その事実も表示されます

エージェント向けの出力：

• 出典情報：API ソース、取得時刻、スコア日付、モデルのメタデータを verified、inferred、unavailable として示します
• 明示的なカバレッジ：EPSS と CVSS が欠落している場合は不明のまま扱います。unscoredCves と deferredCves により、省略された項目と未照会の項目を区別します。トランスポート障害が発生した場合、呼び出しは失敗します
• 構造化された結果と整形済みテキストで、集計、履歴の欠落、ページネーション、しきい値、復旧手順を同じ内容で提示します

はじめに

公開ホストインスタンス

公開インスタンスは https://first-epss.caseyjhand.com/mcp で利用できます。インストールは不要です。Streamable HTTP を提供しており、各クライアントで設定形式が異なります。

Claude Code の場合：

claude mcp add --transport http first-epss-mcp-server https://first-epss.caseyjhand.com/mcp

Cline の場合（cline_mcp_settings.json）：

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

Cursor の場合（mcp.json）：

{
  "mcpServers": {
    "first-epss-mcp-server": {
      "url": "https://first-epss.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop では、設定 → コネクタからリモートサーバーを追加します。

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加してください。

{
  "mcpServers": {
    "first-epss-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/first-epss-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または npx を使用します（Bun は不要です）。

{
  "mcpServers": {
    "first-epss-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/first-epss-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または Docker を使用します。

{
  "mcpServers": {
    "first-epss-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/first-epss-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 以降）。
• FIRST の公開 EPSS API へのインターネット接続。API キーやアカウントは不要です。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/first-epss-mcp-server.git

2. ディレクトリに移動します：

cd first-epss-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# Optional: edit framework transport, auth, logging, and telemetry settings

設定

サーバー固有の設定は不要です。

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_HOST	HTTP のバインドアドレス。	127.0.0.1
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_HTTP_ENDPOINT_PATH	HTTP MCP エンドポイントのパス。	/mcp
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto。	auto；.env.example と Docker では stateless が選択されます
MCP_AUTH_MODE	認証：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）。	debug；クライアントの例と Docker では info が選択されます
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）。	<app-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
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/mcp-server/tools	5 つのツール定義、共有スキーマ、フォーマット処理、履歴ポリシー。
src/services/epss	FIRST API リクエスト、正規化、リクエスト間隔の調整、再試行、モデルのメタデータ。
tests/	src/ の構成に対応する単体テストと統合テスト。

開発ガイド

開発ガイドラインとアーキテクチャルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックでは try/catch を使用しません
• ログには ctx.log、ストレージには ctx.state を使用します
• 新しいツールは src/mcp-server/tools/definitions/index.ts のバレルからエクスポートします。src/index.ts がそれを createApp() に渡します
• 外部 API 呼び出しをラップし、生データを検証 → ドメイン型に正規化 → 出力スキーマを返します。不足しているフィールドを捏造してはいけません

貢献

問題の報告を歓迎します。提出前にチェックとテストを実行してください：

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 License の下でライセンスされています。詳細については、LICENSE ファイルを参照してください。