first-epss-mcp-server
by cyanheads
README.md
<div align="center">
<h1>@cyanheads/first-epss-mcp-server</h1>
<p><b>Look up FIRST EPSS exploitation scores and daily history, find CVEs by score threshold, and prioritize CVEs with caller-supplied CVSS via MCP. STDIO or Streamable HTTP.</b>
<div>5 Tools</div>
</p>
</div>
<div align="center">
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/first-epss-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/first-epss-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
</div>
<div align="center">
[](https://github.com/cyanheads/first-epss-mcp-server/releases/latest/download/first-epss-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=first-epss-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvZmlyc3QtZXBzcy1tY3Atc2VydmVyIl19) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22first-epss-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Ffirst-epss-mcp-server%22%5D%7D)
[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
</div>
<div align="center">
**Public Hosted Server:** [https://first-epss.caseyjhand.com/mcp](https://first-epss.caseyjhand.com/mcp)
</div>
---
## Overview
Daily forecasts of observed CVE exploitation within the next 30 days from [FIRST EPSS](https://www.first.org/epss/), generated by Empirical Security and published by FIRST. Look up scores, inspect daily movement, discover CVEs by score or year, and combine likelihood with caller-supplied CVSS severity. The [public API](https://api.first.org/epss/) needs no key or registration.
### Tools
| Tool | Description |
|:---|:---|
| `epss_get_scores` | Fetch current or historical EPSS probability and percentile for supplied CVEs |
| `epss_get_timeseries` | Inspect daily history, exact-date changes, peaks, gaps, and model transitions |
| `epss_query_threshold` | Discover CVEs by inclusive score bounds, CVE year, or recent dataset addition |
| `epss_prioritize_cves` | Assign configurable remediation tiers using EPSS and caller-supplied CVSS severity |
| `epss_list_reference` | Explain score interpretation, models, coverage, and prioritization conventions |
### Skills
| Skill | Description |
|:---|:---|
| `first-epss-guide` | Gates and workflows for the calling agent: when an NVD or KEV source must answer instead, where score dates and offsets come from, when paging is done, why discovery pages are not EPSS-ranked, and how to tell a model change from real score movement |
Served over MCP as `skill://first-epss-guide/SKILL.md` and shipped in the npm package under `skills/`.
## Capability reference
### `epss_get_scores` <sub>tool</sub>
- Up to 5,000 `cves` as an array or a whitespace/comma/semicolon-delimited string; case and Unicode dashes are normalized. Process up to 500 unique identifiers from `batchOffset` (default 0). Optional `date` (`2021-04-14` through today, UTC) selects a historical snapshot; omitted or blank means latest available
- Each score carries `epss`, `percentile`, `date`, and `modelVersionSource` (`csv_header`, `published_schedule`, or `unavailable`), ordered by EPSS descending
- `unscoredCves` separates `invalid_format` from `not_returned`; a missing score is unknown, never zero
- `snapshot_unavailable` identifies a dated snapshot FIRST cannot supply; select another date or omit it. A CVE omitted from a published snapshot remains `not_returned`
---
### `epss_get_timeseries` <sub>tool</sub>
- Same `cves` / `date` / `batchOffset` inputs; process up to 50 unique identifiers per call
- Each item pairs the anchor `current` with up to 30 preceding daily observations in `series`, plus `missingDates`, `peak`, and `delta7d` / `delta30d`, which need an exact calendar baseline and otherwise appear in `unavailableDeltas`
- `modelBoundariesCrossed` and each comparison's `crossesModelBoundary` flag published model transitions; neither explains why a score moved
- Derived deltas are rounded to nine decimals; original scores retain their precision. Re-anchor on `previousAnchorDate` for the preceding window without overlap; the pointer does not guarantee a published snapshot
---
### `epss_query_threshold` <sub>tool</sub>
- Inclusive `minEpss` / `maxEpss` / `minPercentile` / `maxPercentile` bounds, `year`, and `addedWithinDays` intersect, with optional historical `date`; at least one filter and ordered bounds are required, otherwise `invalid_filter_combination`. `addedWithinDays` is dataset-addition recency and ignores `date`
- One candidate page per call in FIRST's upstream order, which is not ranked by EPSS: to rank, narrow the bounds, page through every match, and sort locally. Positive safe-integer `limit` (default 100) plus `offset`. Limits above 10,000 are clamped to 10,000; the notice reports requested/applied values and both `filters.limit` and `pagination.limit` echo the applied limit. With `year`, `candidateTotal` counts broad candidates and `total` is `null` (`totalRelation: "unknown"`), so a filtered page can be empty with `hasMore: true`
- Complete score rows fit within the 65,536-byte limit on each serialized response surface. When rows are withheld, `pagination.budgetLimited` is true and `withheldCount` counts inspected matches omitted; `examinedCount` still counts every inspected candidate. `nextOffset` resumes at the first withheld match's original candidate position, including with year filtering
- Continue with the same filters and `limit`, `provenance.scoreDates[0]` as `date`, and `nextOffset` as `offset`
---
### `epss_prioritize_cves` <sub>tool</sub>
- Up to 5,000 `{ cve, cvssBaseScore? }` entries (CVSS 0–10, caller-supplied) against latest or optional dated EPSS; process up to 500 unique CVEs from `batchOffset`. A duplicate CVE with differing CVSS, including missing versus supplied, fails as `conflicting_cvss`. Unavailable dated snapshots fail as `snapshot_unavailable`
- Defaults `severityThreshold: 7` and `likelihood: { metric: "epss", threshold: 0.10 }`, both inclusive; `metric: "percentile"` is an explicit alternative, and neither is FIRST guidance
- Tiers are `act_now` (high severity, high likelihood), `scheduled` (high, low), `monitor` (low, high), and `defer` (low, low); missing CVSS lands in `epssOnly`, missing EPSS in `unscoredCves` with its CVSS kept
---
### `epss_list_reference` <sub>tool</sub>
- `topic`: `interpretation`, `models`, `coverage`, `prioritization`, or `all` (default)
- Static, source-linked guidance with a `verifiedAt` date; makes no upstream request
### Batch continuation
All four dynamic tools bound each JSON-serialized `content` array and `structuredContent` object to 65,536 UTF-8 bytes, including notices, provenance, filters and pagination. Threshold discovery uses candidate continuation as described above; supplied-CVE tools use the batch continuation below.
Scores, timeseries and prioritization retain whole score rows, history items and unscored entries. `processedCount` still counts the workload processed, including invalid identifiers; `returnedCount` counts complete entries retained and `withheldCount` counts processed entries omitted by the byte limit. `deferredCount` counts entries never queried. `withheldCves` and `deferredCves` retain their array types; their `*Complete` flags explicitly identify previews when the full lists cannot fit. `budgetLimited` discloses any response shortening.
Malformed identifiers in unscored, withheld and deferred text are JSON string literals, escaped for Markdown. JSON decoding recovers the normalized identifier, including embedded CR, LF, tabs and backslashes; canonical CVEs remain plain identifiers. Structured identifiers are unchanged. Exhausted batch offsets report completion without upstream lookups or missing-score claims. Threshold notices distinguish a globally empty search, exhausted candidate offsets, and an exact-year page without matches, including the final page.
When `nextBatchOffset` is present, call the same tool with the **original** `cves`, `nextBatchOffset` as `batchOffset`, and `provenance.scoreDates[0]` as `date` (retain the requested date if no score date was returned). Prioritization also keeps every original `cvssBaseScore`, `severityThreshold` and `likelihood`. The offset counts normalized unique identifiers in first-occurrence input order, including invalid entries; score sorting does not change it. Continue until `nextBatchOffset` is absent. An offset past the end returns explicit empty accounting. Lists are for inspection; continuation through the original batch preserves entries even when lists are previews.
## Features
Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.
FIRST EPSS-specific:
- Keyless lookup against FIRST's public API, with bounded batches rather than corpus synchronization
- Shared API request pacing, transient-failure retries, cancellation, and a 45-second whole-call deadline
- Model attribution from a matching daily CSV header or the verified published schedule for explicitly dated requests and preceding history; current-anchor verification failures remain visible
Agent-friendly output:
- Provenance: API source, retrieval time, score dates, and model metadata marked `verified`, `inferred`, or `unavailable`
- Explicit coverage: missing EPSS and CVSS remain unknown; `unscoredCves` and `deferredCves` distinguish omissions from work not queried. Transport failures fail the call
- Structured results and formatted text carry the same accounting, history gaps, pagination, thresholds, and recovery guidance
## Getting started
Connect to the hosted instance, no install:
```sh
claude mcp add --transport http first-epss-mcp-server https://first-epss.caseyjhand.com/mcp
```
Or run it locally:
```sh
claude mcp add first-epss-mcp-server -- npx -y @cyanheads/first-epss-mcp-server
```
For other clients, add this to the MCP config file:
```json
{
"mcpServers": {
"first-epss-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/first-epss-mcp-server"]
}
}
}
```
FIRST's EPSS API is keyless; the server needs only internet access to it. For Docker or a source build, see [Running the server](#running-the-server).
## Configuration
No server-specific settings are required.
| Variable | Description | Default |
|:---|:---|:---|
| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
| `MCP_HTTP_HOST` | HTTP bind address. | `127.0.0.1` |
| `MCP_HTTP_PORT` | HTTP server port. | `3010` |
| `MCP_HTTP_ENDPOINT_PATH` | HTTP MCP endpoint path. | `/mcp` |
| `MCP_SESSION_MODE` | HTTP session mode: `stateless`, `stateful`, or `auto`. The server declares `stateless` in code; an explicit value overrides it. | `stateless` |
| `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth`. | `none` |
| `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.). | `debug`; Docker selects `info` |
| `LOGS_DIR` | Directory for log files (Node.js only). | `<app-root>/logs` |
| `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`. | `in-memory` |
| `OTEL_ENABLED` | Enable [OpenTelemetry](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |
See [`.env.example`](./.env.example) for every server setting and the common framework overrides.
## Running the server
### Local development
Requires [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).
- **Clone and install:**
```sh
git clone https://github.com/cyanheads/first-epss-mcp-server.git
cd first-epss-mcp-server && bun install
cp .env.example .env # optional: framework transport, auth, logging, telemetry
```
- **Build and run:**
```sh
# One-time build
bun run rebuild
# Run the built server
bun run start:stdio
# or
bun run start:http # http://localhost:3010/mcp
```
- **Run checks and tests:**
```sh
bun run devcheck # Lint, format, typecheck, security
bun run test # Vitest test suite
bun run lint:mcp # Validate MCP definitions against spec
```
### Docker
```sh
docker run --rm -p 3010:3010 ghcr.io/cyanheads/first-epss-mcp-server:latest
```
The image defaults to HTTP transport, stateless session mode, and logs to `/var/log/first-epss-mcp-server`. To run it over stdio from an MCP client, use `"command": "docker"` with `"args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/first-epss-mcp-server:latest"]`. To build locally, `docker build -t first-epss-mcp-server .`; OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.
## Project structure
| Directory | Purpose |
|:---|:---|
| `src/mcp-server/tools` | Five tool definitions, shared schemas, formatting, and history policy. |
| `src/services/epss` | FIRST API requests, normalization, pacing, retries, and model metadata. |
| `tests/` | Unit and integration tests mirroring `src/`, plus bundle-script tests under `tests/scripts/`. |
## Development guide
See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — no `try/catch` in tool logic
- Use `ctx.log` for logging, `ctx.state` for storage
- Export new tools from the `src/mcp-server/tools/definitions/index.ts` barrel, which `src/index.ts` passes to `createApp()`
- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
## Contributing
Issues are welcome. Run checks and tests before submitting:
```sh
bun run devcheck
bun run test
```
## License
This project is licensed under the Apache 2.0 License. See the [LICENSE](./LICENSE) file for details.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues