echelongraph-mcp 2.6.1 → 2.6.3

package/CHANGELOG.md

@@ -6,6 +6,93 @@ 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.6.3 — 2026-10-04
+
+- `exposure_radar` relays the observation window each count was measured over, where the API now
+  serves one: `exposed_databases.window` (when our verifier last confirmed each host),
+  `leaked_credentials.window` (when each key was last seen) and `shadow_ai.confirmed_exposed.window`
+  (when our verifier's deciding probe ran). A window is relayed only when no counted row is undated;
+  otherwise the note says how many are, and a malformed window is left out and named. KEV-exposure
+  carries no observation time yet. `exposure_radar` stays `not_assessed` with `measured_at` null:
+  a window's end is not one observation time (#2438).
+- `vendor_advisories_for_cve`, `search_vendor_advisories` and `get_vendor_advisory` read each
+  vendor's window from `GET /api/v1/public/vendor-advisories/coverage` beside their own request,
+  and relay it in `coverage` (`vendor_windows`, or `vendor_window` for the detail): the advisories
+  held, `earliest_vendor_published_at`, `latest_vendor_published_at` and `history_backfill`.
+  `vendor_advisories_for_cve` adds `cve_year` and `vendors_not_fully_held`, the vendors with no
+  advisory in the answer of which EchelonGraph holds none, whose earliest held advisory is dated
+  after 1 January of the year in the CVE ID, or whose history is still being read, and its note
+  names each with its window: an empty answer for CVE-2024-3400 can no longer be read as Palo Alto
+  having published none. Its description no longer says an empty answer means none of the polled
+  feeds names the CVE: it means none of the advisories EchelonGraph holds does. The search
+  and the detail name the vendors whose history is still being read. When the windows cannot be
+  read, the answer is still relayed, measured, with the windows null and a note saying so (#2729).
+- `search_vendor_advisories`: a query of 1 or 2 characters matches whole words only
+  (`search_match` `word`), as the API now answers it, and the description and the note say so; a
+  search's total is counted to at most 1,000, and a capped total (`total_capped` true) is written
+  "1,000+" in the note, never as a count. `coverage` gains `total_capped` and `search_match`
+  (#2728).
+- `check_sbom`'s 50-second budget bounds the whole call, not only when a batch may start: each
+  batch's request may take only what is left of it, and a batch still unanswered when the budget
+  runs out is cut off and its purls answered as not sent (`not_sent_reason` `time_budget`). Before,
+  a batch started at 49.9 s could run for the 15-second request timeout, past the 60-second limits
+  of the SDK's client and the hosted endpoint, which then answered nothing at all. A Retry-After
+  wait that ends at the budget's end, before any batch was answered, answers that 429 instead of
+  sending a request with no time left (#2756).
+- Repository only, not in the package: the production synthetic probes `check_sbom` with 201
+  purls, so every run sends two batches, and fails the probe (`expectation_unmet`) unless both
+  were answered; core-backend's tests fail when `MAX_COMPONENTS`, `MAX_PURL_LEN` or
+  `API_COMPONENTS_PER_MINUTE` disagree with the API's own values, and every core-backend deploy runs
+  them before it builds (`scripts/check-outbound-identity.sh`'s table), refusing on drift (#2757).
+- A success's first text block is cut to fit 30,000 characters when the API's JSON is longer, and
+  `structuredContent.data` still carries the answer whole. Through 2.6.2 that block was the JSON
+  whatever its size: on production's answers of 2026-10-04 a default `search_cves` for "openssl"
+  was 133,300 characters of text, `get_cve` CVE-2021-44228 80,897, `check_affected` openssl 3.0.0
+  156,058 (the Linux kernel at 5.10.0, 364,408), `check_sbom` on a 50-component SBOM 112,820,
+  `kev_recent` at limit 200 105,925 and `search_vendor_advisories` at limit 50 103,147, against
+  the 60,000-character ceiling; the same calls now measure 13,513, 22,960, 25,951 (27,717),
+  28,733, 31,588 and 19,917. The JSON is first laid out one row a line, which loses nothing; past
+  that, a list tool cuts each row to the fields it names (the description cut to 200 characters,
+  every long string ending in "…"), then to fewer, and leaves rows out only when its leanest cut
+  is still too long (`check_sbom` leaves out `not_affected` rows first); `get_cve` keeps the first
+  entries of `cpe_match` and `references`. The note then ends with a sentence starting
+  `TEXT CUT` that names what the first text block leaves out, which tool returns a row whole, and,
+  when rows are left out, the `offset` or page size at which they fit. An answer that fits is sent
+  as before. Every tool description, the server instructions and the methodology resource say so
+  (#2783).
+- `search_cves` takes `offset` (0 to 10,000), so the next page a cut text names can be read (#2783).
+- A list beside the rows is cut before the rows are: `check_affected`'s `excluded` and
+  `undetermined` samples keep each entry's `cve_id` and `reason`, and `cve_ids` (each match's
+  `cve_id`, in order) its first 10, so every match stays in the text (`flash_player` 10.0.0, 200
+  matches and 50 excluded entries, had 75 matches left out of it, two of them KEV-listed), and `check_sbom`'s `not_sent_purls` keeps its first 10, with the note
+  saying from which position of the input the purls not sent run. A 2,000-purl `check_sbom` call
+  that the API's budget stops after 1,200 now keeps the affected rows before the clean ones in the
+  text. A cut `check_affected` match keeps `match_reason` (a registry match's advisory interval,
+  which names the fixed version) where it fits, and the note names `cve_intel` for fixed versions
+  (#2783).
+
+## 2.6.2 — 2026-10-04
+
+- `kev_recent` reads an RFC 3339 `since` or `until` as the date written in it, dropping the time
+  and offset. It used to convert the timestamp to UTC first, so `2024-04-12T00:00:00+02:00` was
+  answered for 2024-04-11, and `2024-04-12T23:30:00-05:00` for 2024-04-13, while still reporting
+  a measured result. `kev_added_date` is a calendar date, so the written date is the one meant.
+  `Z` timestamps, such as those `get_cve` returns, are unaffected (#2755).
+- Hosted endpoint only: a `tools/call` of `check_sbom`, or a `prompts/get` of `sbom_review`, may
+  now send a request body of up to 6 MiB, so a real CycloneDX or SPDX document (up to the tool's
+  5,000,000-character cap) is accepted over `https://mcp.echelongraph.io/mcp`; before, any body
+  over 64 KiB was refused, and only a purl list fit. Every other request keeps the 64 KiB cap.
+  Each server instance serves at most two such large bodies at once; a third is answered HTTP 503
+  with `Retry-After` and JSON-RPC error `-32030`. The per-client limit is unchanged (120 requests
+  a minute). New settings `MCP_MAX_SBOM_BODY_BYTES` and `MCP_LARGE_BODY_SLOTS`. The `check_sbom`
+  description and the README say that over the hosted endpoint the document reaches
+  EchelonGraph's server, which reads the purls from it and neither logs nor keeps it (#2747).
+- `cve_summary` says what the answer's `poller` block is: the in-memory counters of the NVD
+  poller of the one API instance that answered, since it last started, zeroed on every restart,
+  never the feed's size, intake, reliability or freshness. The note says so whenever the block is
+  present, quoting `cves_ingested`, `poll_count` and `poll_errors`; the description and the
+  outputSchema describe the block and each counter. The JSON is still relayed as sent (#2647).
+
 ## 2.6.1 — 2026-10-04
 
 - Hosted endpoint only: when the production synthetic calls `https://mcp.echelongraph.io/mcp`, the

package/README.md

@@ -155,14 +155,14 @@ 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.* |
+| `search_cves` | Search CVEs | Search/filter CVEs (severity, min CVSS, text, sort) with EchelonGraph scores and `score_assessed`; page with `limit` and `offset`; 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 2,000 distinct purls, or a CycloneDX JSON or SPDX JSON document: the purls are read from it on your machine and only they are sent, in POST bodies of at most 200 each, one after another; the document is not. When the API's per-component rate limit answers 429, the tool waits the `Retry-After` it names, within 50 seconds per call; past that it answers what it has, with the purls not sent counted in `coverage.not_sent`, the reason in `coverage.not_sent_reason`, and the list in `data.not_sent_purls`, never dropped silently. 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.* |
+| `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 2,000 distinct purls, or a CycloneDX JSON or SPDX JSON document: the purls are read from it by the MCP server (on your machine when it runs from npm) and only they are sent to the API, in POST bodies of at most 200 each, one after another; the document is not. When the API's per-component rate limit answers 429, the tool waits the `Retry-After` it names, within 50 seconds per call; past that it answers what it has, with the purls not sent counted in `coverage.not_sent`, the reason in `coverage.not_sent_reason`, and the list in `data.not_sent_purls`, never dropped silently. 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?* |
@@ -312,6 +312,7 @@ A `newest_kev` row's `exposure_state` says whether its count is a measurement:
 | `exposed_databases.engines` | Distinct engine types among them (for example `redis` or `grafana`). |
 | `exposed_databases.top_engines`, `exposed_databases.top_countries` | Up to 15 engines and 10 countries, ranked by those services. |
 | `exposed_databases.pii_likely`, `exposed_databases.pci_likely` | Services whose schema names pass a high-confidence gate for personal data, or for payment-card data. The names are index, database, table or field names in the Shodan or LeakIX banner or in the check's response, never record values; the gate passes one unambiguous term (such as `ssn` or `cardholder`) or two distinct indicators. It is a precision-first schema gate, not a census: a service whose names do not pass it is not counted, whatever it holds, so the other services are not shown to hold no such data. |
+| `exposed_databases.window.from`, `exposed_databases.window.to` | Timestamps, not counts: when EchelonGraph's check last confirmed the oldest and the newest of the services counted answering without authentication, a span of checks made at different times. Relayed only when every counted service has such a time; otherwise the note says how many do not. |
 | `exposed_databases.last_run_at` | A timestamp, not a count: when the radar last completed a check, a cycle in which its Shodan search, or the LeakIX fallback, answered at least one query (others may have failed), its list of services due for a re-check was read, and the scan opt-out register could be consulted. A cycle that searched nothing, or whose reads failed, does not move it. |
 
 #### `leaked_credentials`
@@ -322,6 +323,7 @@ A `newest_kev` row's `exposure_state` says whether its count is a measurement:
 | `leaked_credentials.distinct_secrets` | Each secret once. |
 | `leaked_credentials.distinct_repos` | Public GitHub repositories with at least one. |
 | `leaked_credentials.top_providers`, `leaked_credentials.top_types` | Up to 15 providers and secret types, ranked by (repository, secret) pairs. |
+| `leaked_credentials.window.from`, `leaked_credentials.window.to` | Timestamps, not counts: when EchelonGraph's detector last found the oldest and the newest of the (repository, secret) pairs counted in a public commit. |
 | `leaked_credentials.last_run_at` | A timestamp, not a count: when the radar last completed a check, a cycle that read the public GitHub event stream (fetches of some of the commits it lists may have failed). A cycle whose read of that stream failed does not move it. |
 
 None of them is validated. Each is a credential-shaped string in a public commit that passed
@@ -339,6 +341,7 @@ labels each one. Only `shadow_ai.confirmed_exposed` counts exposed services.
 | `confirmed_exposed.total` | Confirmed exposed: services EchelonGraph's probes found answering without an authentication gate (liveness `active`, or `rechecking` during a re-check). It is the sum of `confirmed_exposed.by_category`. |
 | `confirmed_exposed.by_category` | The same services, by category. |
 | `confirmed_exposed.last_24h` | Confirmed-exposed services first recorded in the last 24 hours. |
+| `confirmed_exposed.window.from`, `confirmed_exposed.window.to` | Timestamps, not counts: when EchelonGraph's verifier ran the probe that last decided the oldest and the newest of the confirmed-exposed services, a span of probes made at different times. Relayed only when every one has such a time. |
 | `observed.total` | Every Certificate Transparency or Shodan observation on record, whatever its verification state: observed, not exposed. |
 | `observed.by_category` | The same observations, by category. |
 | `observed.last_24h` | Observations first recorded in the last 24 hours. |
@@ -485,7 +488,8 @@ never "not affected", and each figure cites its `measured_at`. A prompt makes no
 Every tool answers in one of two shapes, so a model reading the result cannot mistake an
 outage for an all-clear:
 
-- **Success** — the first text block is the API's JSON verbatim; the second is a one-line
+- **Success** — the first text block is the API's JSON verbatim (cut to fit 30,000 characters
+  when it is longer: see "Long answers" below); the second is a one-line
   note saying the call succeeded, which base URL answered, and what it found; the third is
   the structured result as JSON, less what the first two already say (below). When the
   feed genuinely holds nothing for the query the note says so in words ("we looked and
@@ -515,6 +519,37 @@ what an earlier block already says, so a client that passes only `content` to th
 sees how the answer was measured. The first text block (the API's JSON, or the failure) and the
 note after it are where 1.x put them.
 
+
+### Long answers
+
+A model pays for every character of text it reads, and some clients cap what they pass on:
+Claude Code warns past 10,000 tokens of tool output and, past 25,000, saves the result to a
+file and hands the model its path instead. Through 2.6.2 the first text block was the API's JSON
+whatever its size: on production's answers of 2026-10-04 a default `search_cves` page for
+"openssl" was 133,300 characters of text, `get_cve` for CVE-2021-44228 80,897, `check_affected`
+for the Linux kernel at 5.10.0 364,408, `kev_recent` at its largest page 105,925 and
+`search_vendor_advisories` at its largest page 103,147.
+
+So when the API's JSON is longer than 30,000 characters, the first text block holds it cut to
+fit, and `structuredContent`'s `data` still holds it whole. First the same JSON is laid out with
+each row on a line of its own, which drops no character of the answer but the indentation. If
+that is still too long, a tool that returns a list of rows cuts each row to the fields it names,
+most kept first (`search_cves` keeps `cve_id`, `severity`, `cvss_v3_score`, `echelongraph_score`,
+`score_assessed`, `epss_score`, `kev_listed` and the first 200 characters of the description,
+among others), with every long string ending in "…". A list beside the rows is cut before any
+row field the first level keeps, and before any row leaves the text: `check_affected`'s
+`excluded` and `undetermined` samples keep each entry's `cve_id` and `reason`, and its `cve_ids`
+(each match's `cve_id`, in order) its first 10, so that every match stays in the text, and `check_sbom`'s `not_sent_purls` keeps its first 10, the note saying from
+which position of the input the purls not sent run, so that a second call can send them without
+reading the list. When even the leanest cut is too long, rows are left out of the text
+(`check_sbom` leaves out the `not_affected` rows first, then the `not_assessed` ones), and the
+note says how to read them: the `offset` to call next, or a smaller `limit`. Any other answer
+keeps the first entries of each of its lists (`get_cve`'s `cpe_match` and `references`). The note
+then ends with one sentence starting `TEXT CUT` that says what the first text block leaves out
+and which tool returns a row whole (`get_cve`, `get_vendor_advisory`, `check_affected`, and
+`cve_intel` a CVE's fixed versions). An answer that fits is sent as before, pretty-printed and
+whole. The same answer is always cut the same way.
+
 ## Structured results
 
 Since 2.0.0 every result, success or failure, carries `structuredContent`, and every tool
@@ -530,7 +565,7 @@ declares its shape as an `outputSchema` in `tools/list`, with a title and the an
 | `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. |
+| `data` | On a success only: the API's JSON, whole: the first text block carries the same JSON, or, past 30,000 characters, a cut of it that the note names (`TEXT CUT`). |
 | `error` | On a failure only: `kind`, `path`, `status` and `message`. |
 
 The last text block of every result is this structured result serialized as JSON, less what
@@ -574,7 +609,8 @@ a note says so. Per tool:
   answer gives one time at which what it counts was observed, so no count is presented as a
   dated measurement. `mcp_servers` dates its verdicts only by a window, `mcp_servers.window.from`
   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
+  time; so, since #2438, do `exposed_databases.window`, `leaked_credentials.window` and
+  `shadow_ai.confirmed_exposed.window`. `kev_exposure` gives no observation time at all. 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
@@ -626,11 +662,11 @@ Where each tool's input travels:
 | 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`: `search` | The `X-EG-Search` request header, never the URL. Its severity, minimum CVSS, sort and limit go in the query string. |
+| `search_cves`: `search` | The `X-EG-Search` request header, never the URL. Its severity, minimum CVSS, sort, limit and offset go in the 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 POST bodies of at most 200 each. A CycloneDX or SPDX document is read on your machine and only the purls in it are sent; the document is not. |
+| `check_sbom`: `purls`, or an `sbom` document | The purls, in POST bodies of at most 200 each. A CycloneDX or SPDX document is read on your machine and only the purls in it are sent; the document is not. (Over the hosted endpoint the document goes to EchelonGraph's server instead: see below.) |
 | `cve_summary`, `exposure_radar` | No input. |
 
 The API marks its answers to header-carried lookups `no-store`, so no shared cache keeps them,
@@ -640,7 +676,11 @@ and request logs and trace spans that record URLs do not hold what was looked up
 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
+client's User-Agent. It never logs tool arguments or a query string. A `check_sbom` document (or
+an `sbom_review` prompt's) is a tool argument like any other here: it is in the request body, so
+the whole document reaches EchelonGraph's server, which reads the purls from it in memory, sends
+only those to the API, and neither logs nor keeps the document. To keep the document on your
+machine, run the npm package, or pass `check_sbom` the purls. 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.
@@ -675,7 +715,10 @@ 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.
+64 KiB is refused (HTTP 413, code `-32600`), except a `tools/call` of `check_sbom` or a
+`prompts/get` of `sbom_review`, which may be up to 6 MiB: enough for a CycloneDX or SPDX document
+at the tool's 5,000,000-character cap. Each server instance reads at most two such large bodies at
+once; a third is answered HTTP 503 with `Retry-After` and a JSON-RPC error (code `-32030`).
 
 ## Configuration
 
@@ -695,7 +738,9 @@ variables above and:
 |---|---|---|
 | `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. |
+| `MCP_MAX_BODY_BYTES` | `65536` | The largest request body it reads, except for an SBOM (below). |
+| `MCP_MAX_SBOM_BODY_BYTES` | `6291456` | The largest body of a `tools/call` of `check_sbom` or a `prompts/get` of `sbom_review`. |
+| `MCP_LARGE_BODY_SLOTS` | `2` | How many bodies over `MCP_MAX_BODY_BYTES` it reads and serves at once; past that, 503 with `Retry-After`. |
 | `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
@@ -707,8 +752,12 @@ npm test           # build, then the behavioural suite over both protocol eras,
 npm run smoke      # spawn the server + call cve_exposure against the production API
 ```
 
-`npm run smoke` calls the production API with this package's User-Agent, so its requests are
-counted as external MCP adoption. `npm test` never leaves the machine.
+`npm run smoke` calls the production API with this package's User-Agent. Run from our own
+workspace, whose egress address the API recognises as ours, its requests are counted as our own
+traffic and appear in no adoption count. Run from any other machine, they are counted as external
+MCP adoption unless you set `ECHELONGRAPH_MCP_UA` (for example
+`ECHELONGRAPH_MCP_UA=my-smoke/1.0 npm run smoke`), which files them under that token's family
+instead. `npm test` never leaves the machine.
 
 `npm test` runs the suite once over a 2026-07-28 `server/discover` and once over a 2025-06-18
 `initialize`, plus the era tests. To run it against an installed package rather than `dist/`,

package/dist/http.js

@@ -24,7 +24,7 @@
 import http from "node:http";
 import { createMcpHandler } from "@modelcontextprotocol/server";
 import { forwardToken, markHttpEntrypoint, SYNTHETIC_UA_FAMILY, withClient } from "./runtime.js";
-import { BODY_TOO_LARGE_CODE, DEFAULT_RATE_LIMIT_PER_MIN, FixedWindowLimiter, ORIGIN_REFUSED_CODE, RATE_LIMITED_CODE, bodyFacts, originVerdict, resolveClient, revisionLabel, rpcError, uaFamily, } from "./httpPolicy.js";
+import { BODY_TOO_LARGE_CODE, BUSY_CODE, DEFAULT_LARGE_BODY_SLOTS, DEFAULT_MAX_BODY_BYTES, DEFAULT_MAX_SBOM_BODY_BYTES, DEFAULT_RATE_LIMIT_PER_MIN, LARGE_BODY_TARGETS_TEXT, Slots, FixedWindowLimiter, ORIGIN_REFUSED_CODE, RATE_LIMITED_CODE, bodyFacts, originVerdict, resolveClient, revisionLabel, rpcError, isLargeBodyTarget, largeBodyAdmissible, uaFamily, } from "./httpPolicy.js";
 // Must run before index.ts is evaluated: it is how index.ts knows not to start stdio.
 markHttpEntrypoint();
 const { createServer, NAME, VERSION, SHOWN_BASE, TIMEOUT_MS } = await import("./index.js");
@@ -37,9 +37,12 @@ const PORT = (() => {
     return Number.isInteger(n) && n >= 0 && n < 65536 && process.env.PORT !== "" && process.env.PORT !== undefined ? n : 8080;
 })();
 const RATE_LIMIT_PER_MIN = positiveInt(process.env.MCP_RATE_LIMIT_PER_MIN, DEFAULT_RATE_LIMIT_PER_MIN);
-// Tool arguments are a CVE ID or a short search; 64 KiB is far above any real request and far
-// below the SDK's 4 MiB default.
-const MAX_BODY_BYTES = positiveInt(process.env.MCP_MAX_BODY_BYTES, 64 * 1024);
+// The body caps and the large-body slots (#2747): see httpPolicy.ts "Request-body caps".
+const MAX_BODY_BYTES = positiveInt(process.env.MCP_MAX_BODY_BYTES, DEFAULT_MAX_BODY_BYTES);
+const MAX_SBOM_BODY_BYTES = Math.max(MAX_BODY_BYTES, positiveInt(process.env.MCP_MAX_SBOM_BODY_BYTES, DEFAULT_MAX_SBOM_BODY_BYTES));
+const LARGE_BODY_SLOTS = positiveInt(process.env.MCP_LARGE_BODY_SLOTS, DEFAULT_LARGE_BODY_SLOTS);
+// A large body's wait for a slot is not queued: the client is told to come back.
+const BUSY_RETRY_AFTER_SEC = 5;
 const MCP_PATH = "/mcp";
 const HEALTH_PATH = "/health";
 // One JSON object per line on stdout: Cloud Logging reads `severity` and `message`.
@@ -57,11 +60,13 @@ const handler = createMcpHandler(createServer, {
     // responseMode stays the SDK default, "auto": a modern request is answered with one JSON body
     // unless a handler emits something before its result (none of these tools does). The legacy
     // leg answers over SSE, as a 2025-era streamable HTTP server does.
-    maxRequestBodySize: MAX_BODY_BYTES,
+    // The largest body readBody can hand on; which request may be that large is decided here first.
+    maxRequestBodySize: MAX_SBOM_BODY_BYTES,
     // Names only: an SDK error message can quote what the client sent.
     onerror: (e) => log("WARNING", "mcp_handler_error", { error_name: e.name }),
 });
 const limiter = new FixedWindowLimiter(RATE_LIMIT_PER_MIN);
+const largeBodies = new Slots(LARGE_BODY_SLOTS);
 // CORS for a browser client on an https Origin (the Origin policy has already admitted it).
 // A wildcard is safe here because nothing is credentialed: no cookies, no auth.
 const CORS_HEADERS = {
@@ -79,39 +84,69 @@ function send(res, status, body, headers = {}) {
     res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store", ...headers });
     res.end(body);
 }
-// Reads the body up to MAX_BODY_BYTES. Over the cap: "too_large", and the rest is discarded
-// unread (the response closes the connection).
 function readBody(req) {
+    const mayBeLarge = largeBodyAdmissible(header(req, "mcp-method"), header(req, "mcp-name"));
+    const cap = mayBeLarge ? MAX_SBOM_BODY_BYTES : MAX_BODY_BYTES;
     const declared = Number(req.headers["content-length"]);
-    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+    if (Number.isFinite(declared) && declared > cap) {
         req.resume();
         return Promise.resolve("too_large");
     }
+    let slot = false;
+    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+        if (!largeBodies.tryAcquire()) {
+            req.resume();
+            return Promise.resolve("busy");
+        }
+        slot = true;
+    }
     return new Promise((resolve, reject) => {
         const chunks = [];
         let size = 0;
         let done = false;
+        const stop = (r) => {
+            done = true;
+            chunks.length = 0;
+            if (slot)
+                largeBodies.release();
+            slot = false;
+            resolve(r);
+        };
         req.on("data", (chunk) => {
             if (done)
                 return;
             size += chunk.length;
-            if (size > MAX_BODY_BYTES) {
-                done = true;
-                resolve("too_large");
-                return;
+            if (size > cap)
+                return stop("too_large");
+            if (size > MAX_BODY_BYTES && !slot) {
+                if (!largeBodies.tryAcquire())
+                    return stop("busy");
+                slot = true;
             }
             chunks.push(chunk);
         });
         req.on("end", () => {
             if (!done)
-                resolve(Buffer.concat(chunks));
+                resolve({ body: Buffer.concat(chunks), slot });
         });
         req.on("error", (e) => {
-            if (!done)
-                reject(e);
+            if (done)
+                return;
+            done = true;
+            if (slot)
+                largeBodies.release();
+            reject(e);
         });
     });
 }
+function header(req, name) {
+    const v = req.headers[name];
+    return Array.isArray(v) ? v.join(", ") : v;
+}
+function tooLarge(res, cors) {
+    send(res, 413, rpcError(BODY_TOO_LARGE_CODE, `Request body too large: at most ${MAX_BODY_BYTES} bytes, or ${MAX_SBOM_BODY_BYTES} bytes for ${LARGE_BODY_TARGETS_TEXT}. A larger SBOM can be passed to check_sbom as its purls.`, { max_bytes: MAX_BODY_BYTES, max_bytes_sbom: MAX_SBOM_BODY_BYTES }), { ...cors, Connection: "close" });
+    return { status: 413, refused: "body_size" };
+}
 async function serveMcp(req, res, pathname) {
     const method = req.method ?? "GET";
     const origin = req.headers.origin;
@@ -135,14 +170,39 @@ async function serveMcp(req, res, pathname) {
         return { status: 429, throttled: true };
     }
     let body;
+    let facts;
+    let slot = false;
     if (method === "POST") {
         const read = await readBody(req);
-        if (read === "too_large") {
-            send(res, 413, rpcError(BODY_TOO_LARGE_CODE, `Request body too large: at most ${MAX_BODY_BYTES} bytes.`), { ...cors, Connection: "close" });
-            return { status: 413, refused: "body_size" };
+        if (read === "too_large")
+            return tooLarge(res, cors);
+        if (read === "busy") {
+            send(res, 503, rpcError(BUSY_CODE, `Server busy: this instance is already reading its ${LARGE_BODY_SLOTS} large request bodies at once. Retry after ${BUSY_RETRY_AFTER_SEC} s, or pass check_sbom the SBOM's purls.`, { retry_after_seconds: BUSY_RETRY_AFTER_SEC }), { ...cors, "Retry-After": String(BUSY_RETRY_AFTER_SEC), Connection: "close" });
+            log("WARNING", "mcp_large_body_busy", { slots: LARGE_BODY_SLOTS });
+            return { status: 503, refused: "large_body_busy" };
+        }
+        body = read.body;
+        slot = read.slot;
+        facts = bodyFacts(body);
+        // Past the general cap, the body itself must be what the headers (if any) said: one of
+        // LARGE_BODY_TARGETS. A 2025-era client sends no Mcp-Method, so this is where its large body
+        // is held to that.
+        if (body.length > MAX_BODY_BYTES && !isLargeBodyTarget(facts)) {
+            if (slot)
+                largeBodies.release();
+            return { ...tooLarge(res, cors), body, facts };
         }
-        body = read;
     }
+    try {
+        return { ...(await relay(req, res, pathname, method, cors, client, body)), facts };
+    }
+    finally {
+        if (slot)
+            largeBodies.release();
+    }
+}
+// Hands one admitted request to the SDK's handler and streams its answer back.
+async function relay(req, res, pathname, method, cors, client, body) {
     const headers = new Headers();
     for (const [k, v] of Object.entries(req.headers)) {
         if (v === undefined || HOP_BY_HOP.has(k))
@@ -187,7 +247,7 @@ const server = http.createServer((req, res) => {
     }
     const method = req.method ?? "GET";
     const finish = (o) => {
-        const facts = o.body ? bodyFacts(o.body) : { rpc_method: "(none)" };
+        const facts = o.facts ?? (o.body ? bodyFacts(o.body) : { rpc_method: "(none)" });
         log("INFO", "mcp_request", {
             method,
             path: pathname === MCP_PATH || pathname === HEALTH_PATH ? pathname : "(other)",
@@ -235,6 +295,8 @@ server.listen(PORT, () => {
         forward_token_configured: forwardToken() !== "",
         rate_limit_per_min: RATE_LIMIT_PER_MIN,
         max_body_bytes: MAX_BODY_BYTES,
+        max_sbom_body_bytes: MAX_SBOM_BODY_BYTES,
+        large_body_slots: LARGE_BODY_SLOTS,
     });
 });
 const shutdown = () => {

package/dist/httpPolicy.js

@@ -10,6 +10,7 @@ import { isIP } from "node:net";
 export const ORIGIN_REFUSED_CODE = -32000; // the SDK's own code for an Origin refusal (originValidationResponse)
 export const RATE_LIMITED_CODE = -32029; // implementation-defined server error range (-32000..-32099); "429"
 export const BODY_TOO_LARGE_CODE = -32600; // Invalid Request
+export const BUSY_CODE = -32030; // implementation-defined server error range; "503", no large-body slot free (#2747)
 export function rpcError(code, message, data) {
     return JSON.stringify({ jsonrpc: "2.0", id: null, error: { code, message, ...(data ? { data } : {}) } });
 }
@@ -198,6 +199,80 @@ export class FixedWindowLimiter {
         }
     }
 }
+// ── Request-body caps (#2747) ──
+//
+// Two caps, because one tool's input is a document and every other tool's is a CVE ID or a short
+// search.
+//
+//   - 64 KiB for every request: far above any real request but an SBOM's, and the cap the
+//     endpoint shipped with (#2316).
+//   - 6 MiB for one tools/call of check_sbom, or one prompts/get of sbom_review, which takes the
+//     same document to hand to check_sbom (LARGE_BODY_TARGETS). The sbom argument is up to MAX_SBOM_CHARS
+//     (5,000,000) characters, and over this endpoint that document IS the JSON-RPC body: JSON
+//     text passed as a string is escaped once more (every '"' and newline doubles), which for a
+//     pretty-printed CycloneDX document is about 10% (a 4,998,809-character one is a 5,470,320-byte
+//     body; test/http.test.mjs holds the cap above it). Below Cloud Run's 32 MiB HTTP/1 request
+//     limit. OWASP Juice Shop 11.1.2's 0.74 MB SBOM, which the 64 KiB cap refused, fits eight
+//     times over; a 2,000-component one in the same shape is a ~2 MB body.
+//
+// Which request may be large is decided before it is read where the client says so (a
+// 2026-07-28 client sends Mcp-Method and Mcp-Name; another value is held to 64 KiB without
+// reading on), and from the body itself otherwise: a body past 64 KiB that is not one of
+// LARGE_BODY_TARGETS is refused 413 once read.
+//
+// Memory, not the cap, is what bounds this. An instance has 256 MiB and serves up to 250
+// requests at once (deploy-all.sh SVC_MEMORY / SVC_CONCURRENCY); a check_sbom call holds the raw
+// body, its JSON parse here, the SDK's own parse, the tool's parse of the document and the answer.
+// Measured 2026-10-04 on dist/http.js, Node 22, peak RSS (VmHWM) over an idle ~80 MB: one
+// 2,000-purl ~2 MB body +62 MB; one 5.47 MB body +76 MB; two 5.47 MB bodies at once 209 MB in
+// all, also with V8's old space held to 64 MB: ~59 MB of 256 MiB left for everything else, so
+// not a third. So a body past 64 KiB must hold one of DEFAULT_LARGE_BODY_SLOTS (2) slots per
+// instance for as long as it is read and served; with none free it is answered 503 with
+// Retry-After, never queued. The per-client limit still counts each large request as one
+// request, before its body is read.
+export const DEFAULT_MAX_BODY_BYTES = 64 * 1024;
+export const DEFAULT_MAX_SBOM_BODY_BYTES = 6 * 1024 * 1024;
+export const DEFAULT_LARGE_BODY_SLOTS = 2;
+/** The requests whose body may pass DEFAULT_MAX_BODY_BYTES: JSON-RPC method → the one tool or prompt name. */
+export const LARGE_BODY_TARGETS = { "tools/call": "check_sbom", "prompts/get": "sbom_review" };
+/** LARGE_BODY_TARGETS in words, for the refusals. */
+export const LARGE_BODY_TARGETS_TEXT = Object.entries(LARGE_BODY_TARGETS)
+    .map(([m, n]) => `a ${m} of ${n}`)
+    .join(" or ");
+/** Whether a request's own Mcp-Method / Mcp-Name headers leave it free to be one of LARGE_BODY_TARGETS. Absent headers do (a 2025-era client sends neither). */
+export function largeBodyAdmissible(mcpMethod, mcpName) {
+    const name = mcpName?.trim();
+    if (mcpMethod === undefined)
+        return name === undefined || Object.values(LARGE_BODY_TARGETS).includes(name);
+    const want = Object.hasOwn(LARGE_BODY_TARGETS, mcpMethod.trim()) ? LARGE_BODY_TARGETS[mcpMethod.trim()] : undefined;
+    return want !== undefined && (name === undefined || name === want);
+}
+/** Whether a read body is one of LARGE_BODY_TARGETS, by its bodyFacts. */
+export function isLargeBodyTarget(facts) {
+    const name = facts.rpc_method === "tools/call" ? facts.tool : facts.rpc_method === "prompts/get" ? facts.prompt : undefined;
+    return name !== undefined && Object.hasOwn(LARGE_BODY_TARGETS, facts.rpc_method) && LARGE_BODY_TARGETS[facts.rpc_method] === name;
+}
+/** A counting semaphore that never waits: tryAcquire answers at once. */
+export class Slots {
+    max;
+    used = 0;
+    constructor(max) {
+        this.max = max;
+    }
+    tryAcquire() {
+        if (this.used >= this.max)
+            return false;
+        this.used++;
+        return true;
+    }
+    release() {
+        if (this.used > 0)
+            this.used--;
+    }
+    get inUse() {
+        return this.used;
+    }
+}
 // ── Bounded access-log fields ──
 //
 // The access line carries no body, no query string, no argument and no client address: only
@@ -206,7 +281,7 @@ const RPC_METHOD = /^[a-z][a-z/_]{0,39}$/i;
 const TOOL_NAME = /^[a-z][a-z0-9_]{0,39}$/;
 const REVISION = /^\d{4}-\d{2}-\d{2}$/;
 const UA_FAMILY = /^[A-Za-z0-9._-]{1,40}$/;
-/** The JSON-RPC method and, for tools/call, the tool name, shape-checked; never anything else from the body. */
+/** The JSON-RPC method and, for tools/call, the tool name (for prompts/get, the prompt name), shape-checked; never anything else from the body. */
 export function bodyFacts(body) {
     if (!body || body.length === 0)
         return { rpc_method: "(none)" };
@@ -226,10 +301,11 @@ export function bodyFacts(body) {
         return { rpc_method: "(response)" };
     if (!RPC_METHOD.test(m))
         return { rpc_method: "(other)" };
-    if (m !== "tools/call")
+    if (m !== "tools/call" && m !== "prompts/get")
         return { rpc_method: m };
     const name = parsed.params?.name;
-    return { rpc_method: m, tool: typeof name === "string" && TOOL_NAME.test(name) ? name : "(other)" };
+    const shaped = typeof name === "string" && TOOL_NAME.test(name) ? name : "(other)";
+    return m === "tools/call" ? { rpc_method: m, tool: shaped } : { rpc_method: m, prompt: shaped };
 }
 export function revisionLabel(v) {
     if (v === undefined)