echelongraph-mcp 2.3.4 → 2.5.0

package/CHANGELOG.md

@@ -0,0 +1,136 @@
+# Changelog
+
+Every version of `echelongraph-mcp` published to npm, newest first. Dates are the npm publish
+dates (UTC). Issue numbers refer to EchelonGraph's tracker. Since 2.3.3 each version is published
+with a provenance attestation by the release workflow of
+[github.com/echelongraph/echelongraph-mcp](https://github.com/echelongraph/echelongraph-mcp),
+from the commit tagged `v<version>`.
+
+## 2.5.0 — 2026-10-04
+
+- Four prompts (`triage_cve`, `kev_weekly_brief`, `am_i_affected`, `sbom_review`) and three
+  resources (`echelongraph://methodology`, `echelongraph://sources`, `cve://{cve_id}`), in both
+  protocol eras (#2722).
+- README: a quick start for Claude Desktop, Claude Code, Cursor, VS Code, Windsurf and Cline,
+  and for the hosted endpoint; a title and an example question per tool; what is sent where;
+  the API's and the hosted endpoint's rate limits; the HTTP entrypoint's settings.
+- This changelog, now in the npm package.
+- `server.json`: a description covering the 14 tools, and the icon.
+
+## 2.4.0 — 2026-10-04
+
+Nine new tools, 14 in all (#2726):
+
+- `kev_recent`: the CVEs CISA has added to its KEV catalog, newest first, with due date,
+  ransomware use, EPSS and when EchelonGraph first saw each in the catalog; filter by date
+  range, ransomware and vendor, and page with a cursor (#2717).
+- `epss_history`: how one CVE's EPSS score has changed, as EchelonGraph recorded it, change-only
+  and never a daily series (#2718).
+- `check_affected`: whether a product (CPE path) or a registry package at a version is affected
+  by known CVEs; `assessed` false is never "not affected" (#2716).
+- `check_sbom`: up to 200 purls, or a CycloneDX or SPDX JSON document read on your machine,
+  checked against the advisory corpus, one verdict per component (#2721).
+- `cve_intel`: weakness (CWE), public exploit code, affected packages and fixed versions for one
+  CVE (#2720).
+- `get_cwe`: one CWE and the CVEs classified under it, CISA-KEV-listed first (#2720).
+- `vendor_advisories_for_cve`, `get_vendor_advisory`, `search_vendor_advisories`: the
+  vendor-published advisories that name a CVE, one advisory in full, and search (#2719).
+
+Also:
+
+- An HTTP entrypoint, `dist/http.js` (`npm run start:http`): the same tools over stateless
+  Streamable HTTP on `POST /mcp`, in both protocol eras, with an Origin policy, a per-client limit
+  and a body cap. It is what EchelonGraph's hosted endpoint, `https://mcp.echelongraph.io/mcp`,
+  runs (#2316).
+- `ECHELONGRAPH_MCP_UA`: one product token put ahead of the package's User-Agent, so an
+  automated caller such as a monitor is told apart from people using the server (#2724).
+- Inputs a user types for `check_affected`, `kev_recent` and `search_vendor_advisories` travel in
+  `X-EG-*` request headers, never in the URL (#1983).
+- `get_cve` relays NVD's configuration tree (`cpe_configurations`) when the API serves it, and
+  says when it does not; a missing tree does not mean no product is affected (#2720).
+- A failure message names the HTTP method of a request that is not a GET (`check_sbom`'s POST).
+- Listing files for directories (`glama.json`, a `Dockerfile`, an MCPB manifest); none of them is
+  in the npm package (#2723).
+
+## 2.3.4 — 2026-09-30
+
+- `cve_summary` says what `summary.nvd_critical` … `summary.nvd_none` count (the same active
+  CVEs by NVD's severity label, as provenance, never EchelonGraph's severity) and what
+  `summary.rejected` counts (withdrawn records, outside the total) (#2641).
+
+## 2.3.3 — 2026-09-30
+
+- The first release published by the public repo's release workflow, with npm provenance. No
+  change to the server beyond the version (#2317).
+
+## 2.3.2 — 2026-09-30
+
+- `cve_summary`: `summary.none` is labelled as CVEs not yet scored, never as a severity rating of
+  None (#2610).
+
+## 2.3.1 — 2026-09-30
+
+- `get_cve` and `search_cves` label a CVE EchelonGraph has not scored NOT YET SCORED (a rejected
+  record NOT SCORED), never as an EchelonGraph score of 0 (#2535).
+
+## 2.3.0 — 2026-09-30
+
+- `exposure_radar` reads a fifth radar, `mcp_servers`: hostnames named like an MCP server in
+  EchelonGraph's own Certificate Transparency feed, by their latest verdict on record (RFC 9728
+  protected, pending re-adjudication, or not assessed by reason), with the protocol era and
+  transport splits. An answer that does not say `service` `mcp` is refused, never relayed (#2315).
+
+## 2.2.0 — 2026-09-28
+
+- `not_assessed` no longer says its numbers are not findings: a count it relays is what the
+  source holds on record, undated (#2465).
+- The last text block stops repeating what an earlier block already says (#2467).
+
+## 2.1.0 — 2026-09-27
+
+- `cve_exposure` answers `not_assessed`, with `measured_at` null: its `last_seen` is when
+  EchelonGraph last wrote a row, not when a service was observed (#2439).
+- Every result's last text block carries the structured result, for clients that pass only
+  `content` to the model (#2440).
+
+## 2.0.0 — 2026-09-27
+
+- Both MCP protocol eras on stdio: `server/discover` (2026-07-28) and `initialize` (2025-11-25
+  and earlier) (#2311).
+- Every tool has a title, annotations (`readOnlyHint` and the rest) and an `outputSchema`; every
+  result carries `structuredContent` with `state`, `measured_at`, `method`, `coverage`,
+  `freshness` and `notes` (#2313).
+- `@modelcontextprotocol/server` 2.1.0 replaces `@modelcontextprotocol/sdk` 1.x; Node.js 20 or
+  later (Node.js 18 dropped).
+
+## 1.0.4 — 2026-09-27
+
+- `exposure_radar` labels every number of every radar by what it counts, leaves out and names a
+  field it cannot label, and never relays a CVE the radar does not track as "0 exposed" (#2313).
+- `exposure_radar` relays each radar's `last_run_at`, its last completed check (#2335).
+- The MIT `LICENSE` file ships in the package.
+
+## 1.0.3 — 2026-09-27
+
+- `exposure_radar` regroups the shadow-AI radar's numbers by what each counts
+  (`confirmed_exposed`, `observed`, `authentication`) and relays no number unlabelled (#2307).
+
+## 1.0.2 — 2026-09-27
+
+- Freshness is the radar's last completed cycle, not a follower instance's zero time (#2307).
+- Every Shodan-derived field states Shodan's ownership and copyright (#2306).
+
+## 1.0.1 — 2026-09-27
+
+- An API failure is an error result, never a success with empty data (#1874).
+- Wording: no claim the code does not support; exposure counts are internet-facing services
+  (distinct ip:port), attributed as derived from Shodan data (#2306).
+- `cve_exposure` refuses an id that is not a CVE ID, and reports a CVE outside the radar's
+  tracked set as not assessed, not 0 (#2313).
+- `mcpName` and `server.json` for the official MCP Registry (#1879); the handshake and the
+  User-Agent carry the package version.
+
+## 1.0.0 — 2026-06-25
+
+- First release: `cve_summary`, `search_cves`, `get_cve`, `cve_exposure` and `exposure_radar`
+  over stdio.

package/README.md

@@ -1,6 +1,6 @@
 # EchelonGraph MCP server
 
-**CVE and internet-exposure data** for Claude, Cursor, Cline, and any
+**CVE and internet-exposure data** for Claude, Cursor, VS Code, Cline, and any
 [MCP](https://modelcontextprotocol.io) client, straight from
 [EchelonGraph](https://echelongraph.io)'s free public feed.
 
@@ -10,18 +10,168 @@ internet-facing services (distinct ip:port) EchelonGraph's KEV-exposure radar ha
 running a version that maps to the CVE. Exposure counts are derived from Shodan data.
 Shodan data is owned by Shodan, which holds its copyright (© Shodan).
 
+Its 14 tools look up one CVE (record, exploit code and fixed versions, EPSS history, vendor
+advisories, exposure footprint), list CISA's newest KEV additions, check whether a product or
+package version is affected, check an SBOM, and read a CWE and its CVEs. Every result says how
+it was measured (`state`, `measured_at`, `method`, `coverage`, `freshness`, `notes`), so a model
+cannot mistake an outage or an unassessed lookup for an all-clear.
+
+It also serves four prompts, ready-made workflows a client can show as slash commands
+(`triage_cve`, `kev_weekly_brief`, `am_i_affected`, `sbom_review`; see "Prompts"), and three
+resources (`echelongraph://methodology`, `echelongraph://sources` and `cve://{cve_id}`; see
+"Resources").
+
 Free and keyless: no API key, no auth, read-only. The server makes no request other than the
 API call a tool needs to answer.
 
+- npm: [`echelongraph-mcp`](https://www.npmjs.com/package/echelongraph-mcp) · Official MCP
+  Registry: `io.echelongraph/echelongraph-mcp` · Docs: <https://echelongraph.io/pulse/mcp>
+- Source: <https://github.com/echelongraph/echelongraph-mcp> · Changes:
+  [CHANGELOG.md](CHANGELOG.md) · Security: [SECURITY.md](SECURITY.md)
+
+## Quick start
+
+The local server runs through `npx` and needs Node.js 20 or later; nothing is installed
+globally. Add one of the blocks below to your client, restart it, then ask: *"Is
+CVE-2023-44487 actively exploited, and how many exposed services does EchelonGraph's radar
+have on record for it?"*
+
+### Claude Desktop
+
+Settings → Developer → Edit Config opens `claude_desktop_config.json`
+(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`; Windows:
+`%APPDATA%\Claude\claude_desktop_config.json`). Add:
+
+```json
+{
+  "mcpServers": {
+    "echelongraph": {
+      "command": "npx",
+      "args": ["-y", "echelongraph-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add --transport stdio echelongraph -- npx -y echelongraph-mcp
+```
+
+Add `--scope user` before the `--` to make it available in every project, or `--scope project`
+to share it through the project's `.mcp.json`.
+
+### Cursor
+
+`~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project):
+
+```json
+{
+  "mcpServers": {
+    "echelongraph": {
+      "command": "npx",
+      "args": ["-y", "echelongraph-mcp"]
+    }
+  }
+}
+```
+
+### VS Code
+
+`.vscode/mcp.json` in the workspace (VS Code's key is `servers`, not `mcpServers`):
+
+```json
+{
+  "servers": {
+    "echelongraph": {
+      "command": "npx",
+      "args": ["-y", "echelongraph-mcp"]
+    }
+  }
+}
+```
+
+or from a terminal:
+
+```bash
+code --add-mcp '{"name":"echelongraph","command":"npx","args":["-y","echelongraph-mcp"]}'
+```
+
+### Windsurf, Cline and other clients
+
+Clients that read an `mcpServers` block (Windsurf's `mcp_config.json`, Cline's MCP settings,
+and most others) take the same block as Cursor above.
+
+### Remote (no install)
+
+The same 14 tools, four prompts and three resources are served over Streamable HTTP at:
+
+```text
+https://mcp.echelongraph.io/mcp
+```
+
+Keyless, no sign-in, stateless; both protocol eras. The hosted endpoint is being rolled out:
+until `https://mcp.echelongraph.io/health` answers `{"status":"ok",…}`, use the `npx` setup
+above.
+
+- **claude.ai** (Free, Pro, Max, Team and Enterprise plans):
+  Customize → Connectors → **+ Add** → **Add custom connector**. Name it `EchelonGraph`, paste
+  the URL, choose **No sign in**, and add it. On Team and Enterprise an Owner adds it for the
+  organization first, and each member then connects it. Free plans allow one custom connector.
+- **Claude Code**:
+
+  ```bash
+  claude mcp add --transport http echelongraph https://mcp.echelongraph.io/mcp
+  ```
+
+- **Cursor** (`mcp.json`):
+
+  ```json
+  { "mcpServers": { "echelongraph": { "url": "https://mcp.echelongraph.io/mcp" } } }
+  ```
+
+- **VS Code** (`.vscode/mcp.json`):
+
+  ```json
+  { "servers": { "echelongraph": { "type": "http", "url": "https://mcp.echelongraph.io/mcp" } } }
+  ```
+
+- **Windsurf** (`mcp_config.json`):
+
+  ```json
+  { "mcpServers": { "echelongraph": { "serverUrl": "https://mcp.echelongraph.io/mcp" } } }
+  ```
+
+The hosted endpoint runs this package's code (`dist/http.js`, below) against the same public
+API, so its answers are the npm package's answers. What it sees and logs is under "Privacy",
+and its per-client limit under "Rate limits".
+
 ## Tools
 
-| Tool | What it does |
-|---|---|
-| `cve_summary` | Counts of active CVEs by severity band, the count with no severity band from any source (`summary.none`, sent again as `summary.unscored`: CVEs not yet scored, not a rating of None), the same CVEs counted by NVD's severity label, as provenance (`summary.nvd_critical` to `summary.nvd_none`), the rejected (withdrawn) records outside the total (`summary.rejected`), and when the feed was last updated. |
-| `search_cves` | Search/filter CVEs (severity, min CVSS, text, sort) with EchelonGraph scores and `score_assessed`; the note names each row not yet scored. |
-| `get_cve` | Full record for one CVE: CVSS v3 and (when scored) v4, the EchelonGraph score and its confidence, whether EchelonGraph has scored it (`score_assessed`), EPSS, CISA-KEV status and known ransomware use, the GitHub GHSA id, references, and its published, modified and `updated_at` times. |
-| `cve_exposure` | Internet-exposure footprint for a CVE: exposed service count (distinct ip:port, the `exposed_hosts` field) + country/product breakdown, from the KEV-exposure radar. |
-| `exposure_radar` | Aggregate totals across the exposure radars: services running CISA-KEV CVEs; unauthenticated data stores and observability UIs, found through Shodan (LeakIX when Shodan query credits run low) and then confirmed by EchelonGraph's own identified check, which is not a pure read (on Redis it names its client; on ClickHouse its query lands in the server's query log); leaked credentials; shadow AI; and MCP servers found in EchelonGraph's own Certificate Transparency feed, by RFC 9728 verdict, protocol era and transport. Every number is labelled by what it counts, and a field the tool cannot label is left out and named. |
+Every tool is read-only (`readOnlyHint: true`) and declares a title and an `outputSchema`.
+The example questions are ones a client can answer with that tool alone.
+
+| Tool | Title | What it answers | Example question |
+|---|---|---|---|
+| `cve_summary` | CVE feed summary | Counts of active CVEs by severity band, the count with no severity band from any source (`summary.none`, sent again as `summary.unscored`: CVEs not yet scored, not a rating of None), the same CVEs counted by NVD's severity label, as provenance (`summary.nvd_critical` to `summary.nvd_none`), the rejected (withdrawn) records outside the total (`summary.rejected`), and when the feed was last updated. | *How many critical CVEs does the feed hold, and when was it last updated?* |
+| `search_cves` | Search CVEs | Search/filter CVEs (severity, min CVSS, text, sort) with EchelonGraph scores and `score_assessed`; the note names each row not yet scored. | *Find critical CVEs that mention Tomcat with a CVSS of 9 or more.* |
+| `get_cve` | CVE detail | Full record for one CVE: CVSS v3 and (when scored) v4, the EchelonGraph score and its confidence, whether EchelonGraph has scored it (`score_assessed`), EPSS, CISA-KEV status and known ransomware use, the GitHub GHSA id, references, and its published, modified and `updated_at` times. | *What are CVE-2024-3094's CVSS, EPSS and CISA-KEV status?* |
+| `cve_exposure` | Internet exposure for one CVE | Internet-exposure footprint for a CVE: exposed service count (distinct ip:port, the `exposed_hosts` field) + country/product breakdown, from the KEV-exposure radar. | *How many exposed services does EchelonGraph's radar have on record for CVE-2023-44487?* |
+| `exposure_radar` | Exposure radar totals | Aggregate totals across the exposure radars: services running CISA-KEV CVEs; unauthenticated data stores and observability UIs, found through Shodan (LeakIX when Shodan query credits run low) and then confirmed by EchelonGraph's own identified check, which is not a pure read (on Redis it names its client; on ClickHouse its query lands in the server's query log); leaked credentials; shadow AI; and MCP servers found in EchelonGraph's own Certificate Transparency feed, by RFC 9728 verdict, protocol era and transport. Every number is labelled by what it counts, and a field the tool cannot label is left out and named. | *How many unauthenticated data stores has EchelonGraph's radar confirmed?* |
+| `kev_recent` | Recent CISA KEV additions | The CVEs CISA has added to its Known Exploited Vulnerabilities catalog, newest first (`kev_added_date`), from EchelonGraph's copy of the catalog, polled from CISA every 5 minutes: due date, vendor, product, known ransomware use, EchelonGraph's severity, CVSS, EPSS and `eg_kev_tier`, and `our_first_seen_kev`. Filter by date range, ransomware and vendor; page with `limit` and `next_cursor`. Dated by `last_successful_fetch_at`, our last successful fetch of CISA's feed; the filters travel as request headers, never in the URL. | *Which CVEs has CISA added to KEV since 1 September, and which have known ransomware use?* |
+| `epss_history` | EPSS change history for one CVE | How one CVE's EPSS score has changed, as EchelonGraph recorded it: one point per recorded change (`series_kind` `change_only`), never a daily series, with the value now and `series_starts_at`, when recording began; before it a missing point means not recorded, not unchanged. | *How has CVE-2023-44487's EPSS score changed, as EchelonGraph recorded it?* |
+| `check_affected` | Am I affected? (product or package at a version) | Whether a product (its NVD CPE product token) or a registry package (`ecosystem` and `package`) at a given version is affected by known CVEs, from the matcher behind echelongraph.io/am-i-affected: `assessed` first (false: not evaluated, with `not_assessed_reason`, and a count of 0 then is not "not affected"), the matching CVEs with `kev_listed`, `ransomware`, `epss_score`, `effective_score` and `score_assessed`, and advisories it cannot decide counted as `undetermined_count`, never as safe. What you look up travels in request headers, never in the URL. | *Is openssl 3.0.0 affected by known CVEs? Is lodash 4.17.15 on npm?* |
+| `check_sbom` | Check an SBOM against the advisory corpus | A dependency list checked against EchelonGraph's advisory corpus (OSV.dev records), one verdict per component: `affected`, `not_affected`, `undetermined` or `not_assessed`, each with its `not_assessed_reason`. Pass up to 200 purls, or a CycloneDX JSON or SPDX JSON document: the purls are read from it on your machine and only they are sent, in a POST body; the document is not. A deb, apk or rpm purl without a `distro` qualifier naming its release is not assessed (`distro_release_unknown`): EchelonGraph does not guess a release. Only `not_affected` is clean. No ranking, no score. | *Check this CycloneDX SBOM against the advisory corpus.* |
+| `cve_intel` | CVE weakness, exploits and packages | Weakness, public exploit code, affected packages and fixed versions for one CVE, from EchelonGraph's per-CVE enrichment: `cwes`, `exploits` (at most 10, verified first) with `exploits_total`, `exploits_capped`, `exploits_by_kind` and `exploits_by_status`, `affected_packages`, `fixed_versions` and `timeline`. `verified_status` is the label stored with each reference, not a guarantee that the exploit works. An empty `exploits` list is not evidence that no public exploit exists; a section the API could not read is named in `coverage.sections_failed`, never relayed as an empty list. | *Is there public exploit code for CVE-2021-44228, and which versions fix it?* |
+| `get_cwe` | CWE and its CVEs | One CWE (weakness class) and the CVEs classified under it: `name` and `description` from the MITRE CWE catalog EchelonGraph embeds, `total`, and one page of 50 `cves`, ordered as `order` states (CISA-KEV-listed first, then EchelonGraph score). A `total` of 0 says that no CVE in EchelonGraph's feed is classified under that CWE, not that none exists. | *Which CVEs are classified under CWE-79, CISA-KEV-listed first?* |
+| `vendor_advisories_for_cve` | Vendor advisories for one CVE | The vendor-published advisories (Microsoft MSRC, Red Hat, Cisco, Palo Alto Networks, GitHub GHSA and the other feeds EchelonGraph polls) that name one CVE, newest first, at most 20. | *Which vendor advisories name CVE-2024-3400?* |
+| `get_vendor_advisory` | Vendor advisory detail | One vendor advisory in full: description, severity, `cve_ids` and the subset with a CVE record here (`known_cve_ids`), `affected_products`, `remediation` and `references`. | *Show one of those advisories in full: affected products, remediation and references.* |
+| `search_vendor_advisories` | Search vendor advisories | Search vendor advisories by text (title, description, vendor, advisory ID, products, CVE IDs), vendor, severity and whether they name a CVE. The search text is sent in a request header, never in the URL. | *Search vendor advisories for FortiOS, critical severity only.* |
+
+The three vendor-advisory tools relay `vendor_published_at` (the vendor's date), `our_first_seen_at`
+(when EchelonGraph first recorded the advisory) and `withdrawn` (the vendor rescinded it; the note
+names each one, and the search leaves them out).
 
 Every figure is as fresh as the schedule that refreshes it. The CVE feed is polled from its
 sources on a schedule; each radar refreshes on its own.
@@ -276,6 +426,60 @@ above, each a whole number adding up to the count it divides, is left out whole
 field this version does not know is left out, and named only when its name is shaped like a
 field name.
 
+### How `check_affected` decides
+
+`check_affected` asks the matcher behind
+[echelongraph.io/am-i-affected](https://echelongraph.io/am-i-affected) whether a version is
+affected, by one of two lookup paths:
+
+- **CPE path** — `product` and `version`. `product` is the NVD CPE product token (`openssl`,
+  `nginx`), which can differ from a package name. It returns the CVEs whose NVD CPE match
+  criteria name that product with a version range that includes the version. It matches the
+  token across vendors, so each match carries `cpe_vendor` and `vendor_unknown`: a match with
+  `vendor_unknown` true is real, but its vendor is not verified to be yours.
+- **Registry path** — `ecosystem` (`npm`, `PyPI`, `Maven`, …), `package` and `version`. Each OSV
+  advisory record EchelonGraph holds for the package is decided against the version as
+  affected (a match), not affected (`not_affected_count`) or undetermined.
+
+Read `assessed` before `count`. `assessed` false means the lookup did not evaluate the
+component, and `not_assessed_reason` says why: `product_not_in_cpe_corpus`,
+`package_not_cpe_nameable`, `candidate_load_pending` (with `degraded` true),
+`candidate_window_truncated`, `package_not_in_advisory_corpus` or `no_decidable_advisory`. The
+result's `state` is then `not_assessed`, and its `count` of 0 never means "not affected". An
+advisory whose version range cannot be decided at this version is counted in
+`undetermined_count` (up to 50 listed in `undetermined`) and is never reported as safe. `capped`
+says the match list stopped at its cap, and `candidates_capped` that not every candidate CVE was
+loaded. A failed advisory lookup (`advisory_lookup_failed`) comes back as a failure. Each match
+keeps `kev_listed`, `ransomware`, `epss_score`, `effective_score`, `effective_severity` and
+`score_assessed` as the API sent them.
+
+`product`, `version`, `ecosystem` and `package` travel in the `X-EG-Product`, `X-EG-Version`,
+`X-EG-Ecosystem` and `X-EG-Package` request headers, never in the URL, so request logs and
+trace spans that record URLs do not hold what was looked up. The endpoint reads a CPE vendor
+from the URL only, so this tool takes none.
+
+## Prompts
+
+Ready-made workflows a client can show as slash commands. Each prompt names the tools to call, in
+order, and tells the model to read every result's `state`, `measured_at`, `method`, `coverage`
+and `notes`: `not_assessed` is never reported as clean, a count of 0 under `assessed: false` is
+never "not affected", and each figure cites its `measured_at`. A prompt makes no API request.
+
+| Prompt | Arguments | What it asks the model to do |
+|---|---|---|
+| `triage_cve` | `cve_id` | `get_cve`, `cve_intel`, `vendor_advisories_for_cve`, `epss_history` and `cve_exposure` (and `kev_recent` for the due date when the CVE is KEV-listed), then a decision template: exploited, likelihood, reachable, patch, deadline, decision. |
+| `kev_weekly_brief` | `days` (1 to 365, default 7) | Work out the start date from `days`, page through `kev_recent` from it, and write a brief grouped by vendor with ransomware flags and due dates. |
+| `am_i_affected` | `product`, or `ecosystem` and `package`; `version` | `check_affected`, read `assessed` before `count`, with the not-assessed wording. |
+| `sbom_review` | `sbom` (CycloneDX or SPDX JSON text, up to 5,000,000 characters) | Pass the document to `check_sbom`, look up each affected CVE with `get_cve`, and write a fix list ordered by CISA-KEV listing, then EPSS, then score, each key stated. |
+
+## Resources
+
+| Resource | What it holds |
+|---|---|
+| `echelongraph://methodology` | What each envelope field and `state` value means, and how each tool measures (Markdown). |
+| `echelongraph://sources` | What the API reports about its feeds when the resource is read: the NVD poller's interval and last poll (of the instance that answered, from `/api/v1/public/cves/summary`) and the CISA KEV catalog's last successful fetch and method (from `/api/v1/public/kev/recent`). It names the feeds no endpoint reports a schedule for, and states none for them (JSON). |
+| `cve://{cve_id}` | One CVE as `get_cve` returns it: the structured result, envelope and record, as JSON. An ID that is not a CVE ID is refused before any request; a CVE the API has no record of is not found. |
+
 ## What a result means
 
 Every tool answers in one of two shapes, so a model reading the result cannot mistake an
@@ -323,7 +527,7 @@ declares its shape as an `outputSchema` in `tools/list`, with a title and the an
 | `state` | `measured`, `not_assessed`, `failed` or `invalid_input` (below). |
 | `measured_at` | When the underlying observation was made, as the API states it. `null` when the answer does not say or holds no observation; never the Go zero time. |
 | `method` | How the numbers were produced. `null` on a failure. |
-| `coverage` | What the answer covers, where the tool can say: `in_scope` for `cve_exposure`, the list's own account of its count for `search_cves`, and the radars that answered for `exposure_radar`. |
+| `coverage` | What the answer covers, where the tool can say: `in_scope` for `cve_exposure`, the list's own account of its count for `search_cves`, the radars that answered for `exposure_radar`, and `assessed`, `not_assessed_reason`, the lookup path and the match counts for `check_affected`. |
 | `freshness` | The producing radar's last completed check (`last_run_at`), where the API serves one; `null` where it serves none. |
 | `notes` | The caveats, one sentence each: what the envelope itself needs saying, then the note from the text block. |
 | `data` | On a success only: the same JSON as the first text block. |
@@ -372,21 +576,26 @@ a note says so. Per tool:
   to `mcp_servers.window.to`, over checks made at different times, which is not one observation
   time. Its numbers keep the labels above. `freshness` holds each radar's `last_run_at` where the
   API serves one, for `shadow_ai` also `running`, and for `mcp_servers` also `enabled`.
+- `check_affected` is `measured` only when the answer says `assessed` true, and `not_assessed`
+  when it says false or does not say. Its `measured_at` and `freshness` are `null`: a match answer
+  carries no observation time. Its `coverage` gives `assessed` and `not_assessed_reason` first,
+  then `lookup` (`cpe` or `registry`), `match_layer`, `count`, `capped`, `candidates_capped`,
+  `excluded_count`, `undetermined_count`, `not_affected_count` and `degraded`.
 
 The CVE feed tools' `freshness` is `null`: the feed's answers carry no time at which its
 pollers last completed a poll for the feed as a whole.
 
 A success whose fields do not fit the tool's `outputSchema` (a field of a type the schema does
 not allow) is returned as a failure with `error.kind` `unexpected_shape`, never relayed. A
-field the API adds later is still relayed by the four tools that relay the API's JSON, and
-`exposure_radar` leaves it out and names it, as above.
+field the API adds later is still relayed by every tool that relays the API's JSON as data, and
+`exposure_radar` and `cve_intel`, which relay a selection, leave it out and name what they leave out.
 
 ## Protocol versions
 
 The server answers both eras of the Model Context Protocol on stdio:
 
 - **2026-07-28**: a client that opens with `server/discover` receives a DiscoverResult listing
-  `2026-07-28`, the tools capability and the server instructions, and then sends each request
+  `2026-07-28`, the tools, prompts and resources capabilities and the server instructions, and then sends each request
   with the per-request `_meta` envelope.
 - **2025 and earlier**: a client that opens with `initialize`, as every 1.x SDK client does,
   negotiates `2025-11-25`, `2025-06-18`, `2025-03-26` or `2024-11-05`; a version the server does
@@ -402,50 +611,86 @@ Both handshakes also carry the server instructions: the data is public; what `st
 numbers are aggregate counts of ip:port services, not an internet-wide census; and that Shodan
 data is Shodan's.
 
-## Install
-
-Requires Node.js 20 or later. Add it to your MCP client's config. It runs via `npx` — no global
-install needed.
+## Privacy: what is sent where
 
-### Claude Desktop
+**The npm package (stdio).** The server runs on your machine and sends HTTPS requests to one
+host, `ECHELONGRAPH_API_BASE` (default `https://app.echelongraph.io`), one per API call a tool
+makes (`exposure_radar` makes five; every other tool makes one). No telemetry: it sends nothing
+else, to EchelonGraph or anyone. Every request carries the User-Agent
+`echelongraph-mcp/<version> (+https://echelongraph.io/pulse/mcp)`, with the
+`ECHELONGRAPH_MCP_UA` token ahead of it when you set one, so the API's access log can count use
+per version. Like any HTTPS request, it also reaches the API from your network address.
 
-`claude_desktop_config.json` → `mcpServers`:
+Where each tool's input travels:
 
-```json
-{
-  "mcpServers": {
-    "echelongraph": {
-      "command": "npx",
-      "args": ["-y", "echelongraph-mcp"]
-    }
-  }
-}
-```
+| Input | Where it is sent |
+|---|---|
+| A CVE ID (`get_cve`, `cve_exposure`, `epss_history`, `cve_intel`, `vendor_advisories_for_cve`), a CWE ID and page (`get_cwe`), a vendor and advisory ID (`get_vendor_advisory`) | The URL path. |
+| `search_cves`: the search text, severity, minimum CVSS, sort and limit | The URL query string. |
+| `search_vendor_advisories`: `query` | The `X-EG-Advisory-Search` request header, never the URL. Its vendor, severity, CVE filter, limit and offset go in the query string. |
+| `check_affected`: `product`, `version`, `ecosystem`, `package` | The `X-EG-Product`, `X-EG-Version`, `X-EG-Ecosystem` and `X-EG-Package` request headers, never the URL. |
+| `kev_recent`: `since`, `until`, `ransomware`, `vendor`, `limit`, `cursor` | The `X-EG-Since`, `X-EG-Until`, `X-EG-Ransomware`, `X-EG-Vendor`, `X-EG-Limit` and `X-EG-Cursor` request headers, never the URL. |
+| `check_sbom`: `purls`, or an `sbom` document | The purls, in a POST body. A CycloneDX or SPDX document is read on your machine and only the purls in it are sent; the document is not. |
+| `cve_summary`, `exposure_radar` | No input. |
+
+The API marks its answers to header-carried lookups `no-store`, so no shared cache keeps them,
+and request logs and trace spans that record URLs do not hold what was looked up there.
+
+**The hosted endpoint.** A request to `https://mcp.echelongraph.io/mcp` reaches EchelonGraph's
+server first, which then calls the same API as above. Per request it logs the HTTP method and
+path, the status, the duration, the body size, the JSON-RPC method and (for `tools/call`) the
+tool name, the protocol version, whether an `Origin` header was sent, and the family of your
+client's User-Agent. It never logs tool arguments or a query string. When a client passes the
+per-client limit it logs that client's address key. It passes your client's public address to
+the API, in a header the API trusts only with a token it checks, so the API's rate limit counts
+you and not the hosted service.
+
+EchelonGraph's privacy policy: <https://echelongraph.io/privacy>.
+
+## Rate limits
+
+No API key, so the API limits each caller, one IPv4 address or one IPv6 /64 network as its
+platform records it. Its WAF counts all your requests together in a 60-second window and
+refuses one once the count passes the ceiling for its path:
+
+| Path | Ceiling per minute | Tools |
+|---|---|---|
+| `/api/v1/public/cves` and every path under it | 12,000 | `cve_summary`, `search_cves`, `get_cve`, `epss_history`, `cve_intel`, `check_affected`, `check_sbom` |
+| `/api/v1/public/cwes`, `/api/v1/public/vendor-advisories`, `/api/v1/public/kev/recent`, `/api/v1/public/shadow-ai-radar` | 6,000 | `get_cwe`, the three vendor-advisory tools, `kev_recent`, and one of `exposure_radar`'s five calls |
+| any other `/api/v1/public` path | 600 | `cve_exposure`, and the rest of `exposure_radar`'s calls |
+
+Because the count is shared, heavy use of one path also uses up the lower ceilings. On top of
+that, 500 requests per second per caller is a burst cap on each serving instance, and
+`check_sbom`'s batch route is charged per component: 1,200 components a minute per caller.
+Over a limit the API answers 429 with `Retry-After`, and the tool returns a failure
+(`state` `failed`, `error.status` 429), never empty data. The API's own documentation of these
+limits: <https://echelongraph.io/pulse/api>.
+
+The hosted endpoint adds its own limit before the API's: 120 MCP requests a minute per client
+address, counted by each server instance, answered over it with HTTP 429, `Retry-After` and a
+JSON-RPC error (code `-32029`) that names the limit and the seconds to wait. A request body over
+64 KiB is refused.
 
-### Cursor / Cline / Windsurf
+## Configuration
 
-`~/.cursor/mcp.json` (or the client's MCP settings):
+The npm package (stdio):
 
-```json
-{
-  "mcpServers": {
-    "echelongraph": {
-      "command": "npx",
-      "args": ["-y", "echelongraph-mcp"]
-    }
-  }
-}
-```
+| Env var | Default | Purpose |
+|---|---|---|
+| `ECHELONGRAPH_API_BASE` | `https://app.echelongraph.io` | Override the API base (self-host / proxy). A credential in the URL is masked wherever a result quotes the base. |
+| `ECHELONGRAPH_API_TIMEOUT_MS` | `15000` | Per-request timeout. A slower answer is reported as a failed lookup, not as empty data. |
+| `ECHELONGRAPH_MCP_UA` | unset | One product token (for example `my-monitor/1.0`) put ahead of this package's own User-Agent, so automated callers such as monitors are told apart from people using the server. A value that is not a single token is ignored. |
 
-Restart the client, then ask: *"Is CVE-2023-44487 actively exploited, and how many exposed
-services does EchelonGraph's radar have on record for it?"*
-
-## Configuration
+The HTTP entrypoint, `dist/http.js` (`npm run start:http`), serves the same tools over
+Streamable HTTP on `POST /mcp`, with a liveness check on `GET /health`. It reads the three
+variables above and:
 
 | Env var | Default | Purpose |
 |---|---|---|
-| `ECHELONGRAPH_API_BASE` | `https://app.echelongraph.io` | Override the API base (self-host / proxy). |
-| `ECHELONGRAPH_API_TIMEOUT_MS` | `15000` | Per-request timeout. A slower answer is reported as a failed lookup, not as empty data. |
+| `PORT` | `8080` | The port it listens on. |
+| `MCP_RATE_LIMIT_PER_MIN` | `120` | MCP requests a minute per client address, per instance. |
+| `MCP_MAX_BODY_BYTES` | `65536` | The largest request body it reads. |
+| `ECHELONGRAPH_FORWARD_TOKEN`, `ECHELONGRAPH_FORWARD_HOST`, `MCP_REQUIRE_FORWARD_TOKEN` | unset | EchelonGraph's hosted deployment only: the token with which it names each client to the API. Leave them unset when you run it yourself; the API then counts every request as coming from your server. |
 
 ## Develop
 
@@ -464,6 +709,19 @@ counted as external MCP adoption. `npm test` never leaves the machine.
 set `ECHELONGRAPH_MCP_BIN` to that package's `echelongraph-mcp` bin: the tests then run the bin
 directly, as `npx` does, and read that package's own files.
 
+## Versioning
+
+Semantic versioning: a major version changes protocol behaviour or drops a Node.js version, a
+minor version adds tools or fields, a patch fixes wording or behaviour without changing a tool's
+shape. Every release is published to npm with a provenance attestation by the public repo's
+release workflow, from the commit tagged `v<version>`. Changes per version:
+[CHANGELOG.md](CHANGELOG.md).
+
+## Security
+
+Report a vulnerability privately to **support@echelongraph.io**, not in a public issue. The
+policy, the supported versions and the scope are in [SECURITY.md](SECURITY.md).
+
 ## License
 
 The code is MIT-licensed.