first-epss-mcp-server

---

概述

FIRST EPSS 提供未来 30 天内观测到的 CVE 利用情况每日预测，由 Empirical Security 生成并由 FIRST 发布。查询评分、查看每日变化、按评分或年份发现 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 _工具

• 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 分开；缺少分数表示未知，绝不表示 0
• snapshot_unavailable 表示 FIRST 无法提供指定日期的快照；请选择其他日期或省略日期。若某个 CVE 未出现在已发布的快照中，则归为 not_returned

---

epss_get_timeseries _工具

• 使用相同的 cves / date / batchOffset 输入；每次调用最多处理 50 个唯一标识符
• 每个条目将锚点 current 与 series 中最多 30 个此前的每日观测值配对，并提供 missingDates、peak 和 delta7d / delta30d；这些指标需要精确的日历基准，否则会显示在 unavailableDeltas 中
• modelBoundariesCrossed 及各项比较的 crossesModelBoundary 标志会标出已发布的模型变更；两者都不会说明分数变动的原因
• 派生的变化量会四舍五入到 9 位小数；原始分数保留其精度。对于前一个时间窗口，可将锚点重新设为 previousAnchorDate，以避免重叠；该指针不保证对应已发布的快照

---

epss_query_threshold _工具

• minEpss / maxEpss / minPercentile / maxPercentile 边界、year 和 addedWithinDays 会取交集，并可选用历史 date；必须至少指定一个筛选条件，且边界顺序必须正确，否则返回 invalid_filter_combination。addedWithinDays 表示数据集收录时间范围，不受 date 影响
• 每次调用返回一页候选项，按 EPSS 降序排列：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 _工具

• 最多可输入 5,000 个 { cve, cvssBaseScore? } 条目（CVSS 范围为 0–10，由调用方提供），使用最新或可选的指定日期 EPSS；从 batchOffset 开始处理最多 500 个唯一 CVE。同一 CVE 的 CVSS 不同（包括一个缺失、另一个已提供）时，会返回错误 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 _工具

• topic：interpretation、models、coverage、prioritization 或 all（默认值）
• 静态且链接到来源的指南，包含 verifiedAt 日期；不会向上游发送请求

批次续传

所有四种动态工具都会将每个 JSON 序列化的 content 数组和 structuredContent 对象限制在 65,536 个 UTF-8 字节以内，其中包括通知、来源信息、筛选条件和分页信息。阈值发现按上述方式使用候选项续传；指定 CVE 的工具则使用下述批次续传。

分数、时间序列和优先级排序结果会保留完整的分数行、历史项和未评分条目。processedCount 仍统计已处理的工作量，包括无效标识符；returnedCount 统计保留的完整条目数，withheldCount 统计因字节数限制而省略的已处理条目数。deferredCount 统计从未查询的条目。withheldCves 和 deferredCves 保留其数组类型；当完整列表无法容纳时，其 *Complete 标志会明确指出列表为预览。budgetLimited 会说明响应是否有所缩短。

未评分、暂缓返回和延后处理文本中的格式错误标识符会表示为 JSON 字符串字面量，并针对 Markdown 进行转义。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 标头，或明确指定日期的请求及此前历史数据对应的已验证发布时间表，归属模型信息；当前锚点验证失败仍会显示

便于 Agent 使用的输出：

• 来源信息：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	五个工具定义、共享架构、格式化和历史记录策略。
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 文件。