echelongraph-mcp 2.6.3 → 2.6.6

package/dist/resources.js

@@ -5,16 +5,19 @@
 //                               docs). No API request.
 //   echelongraph://sources      the feeds and what the API itself reports about their polling,
 //                               read from the API at request time and never hard-coded: the CVE
-//                               summary's poller block (/api/v1/public/cves/summary) and the KEV
+//                               summary's poller block (/api/v1/public/cves/summary; its interval,
+//                               last poll and two counters, the answering instance's) and the KEV
 //                               answer's catalog block and method (/api/v1/public/kev/recent).
 //                               What no endpoint reports is named as not reported.
 //   cve://{cve_id}              get_cve's structured result for one CVE, as JSON: the envelope
-//                               (state, measured_at, method, notes) with data, the API's record.
+//                               (state, measured_at, method, notes) with data, the API's record,
+//                               cut past 30,000 characters as get_cve's first text block is.
 //
 // A resource read either answers or is a JSON-RPC error; it never answers a failure as data that
 // reads like a record. sources is the exception by design: each feed it reads carries its own
 // state, and a feed that could not be read says so (state failed), never an empty block.
 import { ProtocolError, ProtocolErrorCode, ResourceNotFoundError, ResourceTemplate } from "@modelcontextprotocol/server";
+import { DATA_TEXT_BUDGET, dataText } from "./textBudget.js";
 export const METHODOLOGY_URI = "echelongraph://methodology";
 export const SOURCES_URI = "echelongraph://sources";
 export const CVE_TEMPLATE = "cve://{cve_id}";
@@ -22,7 +25,7 @@ export const METHODOLOGY = `# How EchelonGraph MCP results are measured
 
 Every tool result carries an evidence envelope in its structuredContent, and repeats it in its last text block (less what an earlier text block already carries verbatim), so a client that passes text blocks alone still sees it.
 
-A success's first text block is the API's JSON, cut to fit 30,000 characters when it is longer: the note then says what the cut leaves out and how to read it (TEXT CUT), and structuredContent's data holds the answer whole.
+A success's first text block is the API's JSON, cut to fit 30,000 characters when it is longer: the note then says what the cut leaves out and how to read it (TEXT CUT), and structuredContent's data holds the answer whole. The resource ${CVE_TEMPLATE} cuts its data the same way, and its notes say so (DATA CUT).
 
 ## Envelope fields
 
@@ -34,7 +37,7 @@ A success's first text block is the API's JSON, cut to fit 30,000 characters whe
 | coverage | What the answer covers, where the tool can say: for example in_scope for cve_exposure, the list's account of its own count for search_cves, assessed and not_assessed_reason first for check_affected. |
 | freshness | The producing radar's or fetcher's last completed check, where the API serves one; null where it serves none. |
 | notes | The caveats, one sentence each. |
-| data | On a success: the API's JSON (exposure_radar and cve_intel relay a labelled selection). |
+| data | On a success: the API's JSON (exposure_radar and cve_intel relay a labelled selection, and cve_summary leaves out a poller field of another JSON type, named in the note). |
 | error | On a failure: kind, path, status and message. |
 
 ## state
@@ -70,9 +73,17 @@ const KEV_PATH = "/api/v1/public/kev/recent";
 const obj = (v) => (v !== null && typeof v === "object" && !Array.isArray(v) ? v : undefined);
 const pick = (o, keys) => Object.fromEntries(keys.filter((k) => o !== undefined && o[k] !== undefined).map((k) => [k, o[k]]));
 const failure = (r) => ({ state: "failed", error: { kind: r.kind, path: r.path, status: r.status ?? null, message: r.detail } });
-// What /api/v1/public/cves/summary reports about the NVD poller: its interval and last poll, of
-// the server instance that answered (core-backend cve/poller.go Stats, in memory).
+// A JSON value's type in words, for a value that is not the JSON object read here.
+const jsonKind = (v) => Array.isArray(v) ? "an array" : typeof v === "number" ? "a number" : typeof v === "boolean" ? "a boolean" : typeof v === "string" ? "a string" : typeof v;
+// What /api/v1/public/cves/summary reports about the NVD poller: its interval and last poll, and
+// its poll and failed-poll counts, of the server instance that answered (core-backend
+// cve/poller.go Stats, in memory).
 const POLLER_FIELDS = ["interval", "last_poll_at", "poll_count", "poll_errors"];
+// #2770: poll_count and poll_errors are that instance's counters since it last started, zeroed on
+// every restart (cve_summary's summaryPollerNote, #2647, says the same of the whole block). 2.6.3
+// relayed them here with a note on interval and last_poll_at alone, so poll_errors 0 over
+// poll_count 7 read as the feed's track record. Whenever reported carries either, notes says so.
+const SOURCES_POLLER_COUNTERS_NOTE = "poll_count and poll_errors, where reported carries them, are that one instance's counters since it last started, zeroed on every restart: they count that instance's polls and failed polls, never the feed's reliability.";
 const CATALOG_FIELDS = ["source", "feed_url", "last_successful_fetch_at", "catalog_version", "date_released", "catalog_count"];
 export async function readSources(kit) {
     const [summary, kev] = await Promise.all([kit.api(SUMMARY_PATH), kit.api(KEV_PATH, { headers: { "X-EG-Limit": "1" } })]);
@@ -80,16 +91,29 @@ export async function readSources(kit) {
     if (!summary.ok)
         Object.assign(nvd, failure(summary));
     else {
-        const poller = obj(obj(summary.data)?.poller);
-        if (poller === undefined) {
+        const sent = obj(summary.data)?.poller;
+        const poller = obj(sent);
+        if (poller === undefined && sent !== undefined && sent !== null) {
+            // #2770's review: a poller of another JSON type (cve_summary leaves it out and names it,
+            // #2771) is one the answer carries, so it is never described as missing.
+            Object.assign(nvd, {
+                state: "not_reported",
+                reported: null,
+                notes: [`The answer carries poller as ${jsonKind(sent)}, where a JSON object was expected, so it reports neither a poll interval nor a last poll time.`],
+            });
+        }
+        else if (poller === undefined) {
             Object.assign(nvd, { state: "not_reported", reported: null, notes: ["The answer carries no poller block, so it reports neither a poll interval nor a last poll time."] });
         }
         else {
+            const reported = pick(poller, POLLER_FIELDS);
+            const counted = reported.poll_count !== undefined || reported.poll_errors !== undefined;
             Object.assign(nvd, {
                 state: "reported",
-                reported: pick(poller, POLLER_FIELDS),
+                reported,
                 notes: [
                     "poller is the NVD poller of the server instance that answered, held in its memory: interval is its configured interval (each cycle adds a start-up jitter), and last_poll_at is that instance's last poll, not a fleet-wide time.",
+                    ...(counted ? [SOURCES_POLLER_COUNTERS_NOTE] : []),
                 ],
             });
         }
@@ -121,6 +145,31 @@ export async function readSources(kit) {
     };
 }
 const json = (uri, v) => ({ contents: [{ uri, mimeType: "application/json", text: JSON.stringify(v, null, 2) }] });
+// cve://{cve_id}'s text (#2801). Through 2.6.3 it was get_cve's structuredContent pretty-printed
+// whole: 86,559 characters for CVE-2021-44228 on the hosted endpoint (2026-10-04), past #2467's
+// ceiling of 60,000 (test/text-bound.mjs), its notes ending with get_cve's TEXT CUT sentences, which
+// describe a first text block the resource does not have ("Every list in it keeps at most its first
+// 64 entries: cpe_match (396)…" beside all 396 of them). A resource is one text, with no
+// structuredContent beside it, so its data is now cut as get_cve's first text block is (dataText:
+// the same answer, cut the same way, laid out as that block lays it out) after the envelope,
+// pretty-printed as before; its notes leave out get_cve's sentences about its first text block and,
+// when data is cut, end with the resource's own, starting DATA CUT, which names get_cve's
+// structuredContent.data as the record whole. A record that fits is the structured result
+// pretty-printed, character for character as before.
+const CVE_RESOURCE_CUT = {
+    opens: (chars) => `DATA CUT: the API's answer is ${chars} characters of JSON, more than the ${DATA_TEXT_BUDGET} this resource's data holds, so data here is cut, and get_cve's structuredContent.data carries the answer whole.`,
+};
+export function cveResourceText(structured, sentences) {
+    const { data, ...envelope } = structured;
+    if (data === null || typeof data !== "object" || Array.isArray(data))
+        return JSON.stringify(structured, null, 2);
+    const firstBlock = new Set(sentences(dataText(data).said));
+    const own = dataText(data, undefined, CVE_RESOURCE_CUT);
+    const notes = Array.isArray(envelope.notes) ? [...envelope.notes.filter((n) => !firstBlock.has(n)), ...sentences(own.said)] : envelope.notes;
+    const head = JSON.stringify({ ...envelope, ...(notes === undefined ? {} : { notes }) }, null, 2);
+    const body = own.text.replace(/\n/g, "\n  ");
+    return head === "{}" ? `{\n  "data": ${body}\n}` : `${head.slice(0, -2)},\n  "data": ${body}\n}`;
+}
 export function registerResources(server, kit) {
     server.registerResource("methodology", METHODOLOGY_URI, {
         title: "How results are measured",
@@ -129,12 +178,12 @@ export function registerResources(server, kit) {
     }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: METHODOLOGY }] }));
     server.registerResource("sources", SOURCES_URI, {
         title: "Feed sources and polling",
-        description: "The feeds and what the API reports about their polling, read from the API when the resource is read: the NVD poller's interval and last poll (of the instance that answered) and the CISA KEV catalog's last successful fetch and method. What no endpoint reports is named as not reported.",
+        description: "The feeds and what the API reports about their polling, read from the API when the resource is read: the NVD poller's interval, last poll, poll_count and poll_errors, all of the one instance that answered (the two counts since that instance last started, zeroed on every restart, never the feed's reliability), and the CISA KEV catalog's last successful fetch and method. What no endpoint reports is named as not reported.",
         mimeType: "application/json",
     }, async (uri) => json(uri.href, await readSources(kit)));
     server.registerResource("cve", new ResourceTemplate(CVE_TEMPLATE, { list: undefined }), {
         title: "CVE record",
-        description: "One CVE's record as get_cve returns it, as JSON: the evidence envelope (state, measured_at, method, notes) with data, the API's record. cve_id is a CVE ID such as CVE-2024-3400.",
+        description: "One CVE's record as get_cve returns it, as JSON: the evidence envelope (state, measured_at, method, notes) with data, the API's record. Past 30,000 characters of JSON, data is cut as get_cve's first text block is, and a note starting DATA CUT says what the cut leaves out; get_cve's structured result holds the record whole. cve_id is a CVE ID such as CVE-2024-3400.",
         mimeType: "application/json",
     }, async (uri, vars) => {
         const raw = Array.isArray(vars.cve_id) ? vars.cve_id[0] : vars.cve_id;
@@ -150,6 +199,6 @@ export function registerResources(server, kit) {
                 throw new ResourceNotFoundError(uri.href);
             throw new ProtocolError(ProtocolErrorCode.InternalError, msg, { uri: uri.href, state: r.structuredContent.state ?? null, error: err ?? null });
         }
-        return json(uri.href, r.structuredContent);
+        return { contents: [{ uri: uri.href, mimeType: "application/json", text: cveResourceText(r.structuredContent, kit.sentences) }] };
     });
 }

package/dist/runtime.js

@@ -18,12 +18,34 @@ export function markHttpEntrypoint() {
 export function isHttpEntrypoint() {
     return httpEntrypoint;
 }
-// The client a tool call is being answered for. http.ts runs each request inside
-// withClient(), and the SDK dispatches the tool handler inside that same async context, so
-// api() can read it without the tool module passing it through every function.
 const clientStore = new AsyncLocalStorage();
 export function withClient(clientIp, fn, opts = {}) {
-    return clientStore.run({ clientIp, synthetic: opts.synthetic === true }, fn);
+    return clientStore.run({ clientIp, synthetic: opts.synthetic === true, signal: opts.signal, work: opts.work }, fn);
+}
+// #2775: a hosted client can go before its answer is ready (its own timeout, a closed tab, a
+// retry). Nobody will read that answer, so the request's API calls are cancelled (index.ts api()
+// reads this signal) and check_sbom sends no further batch: they would spend the client's API
+// budget and hold the instance's memory for nothing. On stdio there is none: the SDK's own
+// cancellation (notifications/cancelled) reaches check_sbom through its handler's signal.
+export function requestSignal() {
+    return httpEntrypoint ? clientStore.getStore()?.signal : undefined;
+}
+/** Registers `p` as the hosted request's work, so its admission and large-body slot are held until p settles; on stdio, p untouched. */
+export function holdRequest(p) {
+    const work = httpEntrypoint ? clientStore.getStore()?.work : undefined;
+    if (!work)
+        return p;
+    work.add(p);
+    const drop = () => {
+        work.delete(p);
+    };
+    p.then(drop, drop);
+    return p;
+}
+/** Resolves once everything held for a request (holdRequest) has settled, including what is held while it waits. */
+export async function requestSettled(work) {
+    while (work.size > 0)
+        await Promise.allSettled([...work]);
 }
 // #2737: the production MCP synthetic probes this endpoint too, and its calls must reach the API
 // under its own family, never as hosted MCP adoption. The synthetic names itself to this service

package/dist/textBudget.js

@@ -34,9 +34,13 @@
 //   4. else every list keeps its first n entries, n halving, and then strings are cut too.
 // Whenever the text is not the JSON whole, the note ends with one sentence, starting TEXT CUT,
 // that says what the first text block leaves out, that structuredContent.data carries all of it,
-// and how to read the rest in the text: the tool that returns one row whole, and the page size or
-// offset at which a page fits. The cut is deterministic: the same answer is cut the same way.
+// and how to read the rest in the text: the tool that returns one row, and what of it, and the page
+// size or offset at which a page fits. The cut is deterministic: the same answer is cut the same way.
 export const DATA_TEXT_BUDGET = 30_000;
+// What a note may say of reading one CVE's record through get_cve (#2802): get_cve's own first text
+// block is cut too past the budget (each list to its first entries, every other field kept), so
+// only its structuredContent.data is the record whole. A row tool's `whole` sentence starts with it.
+export const GET_CVE_WHOLE = "get_cve returns any one of these CVEs' records, whole in its structuredContent.data, and in its first text block with every field (past 30,000 characters, each list cut to its first entries)";
 // What every tool description says about it, one constant string (marketing-site
 // lib/mcpToolClaims.test.ts folds only constant strings); the suite holds its number to
 // DATA_TEXT_BUDGET's. It uses none of the words that check reviews as the page's own prose (how,
@@ -158,8 +162,11 @@ function cutSides(data, sides) {
     }
     return { fields, said };
 }
+export const FIRST_TEXT_BLOCK = {
+    opens: (chars) => `TEXT CUT: the API's answer is ${chars} characters of JSON, more than the ${DATA_TEXT_BUDGET} the first text block holds, so that block is cut, and structuredContent.data carries the answer whole.`,
+};
 /** The first text block for `data` within DATA_TEXT_BUDGET, and the TEXT CUT sentence when it is cut. */
-export function dataText(data, cut) {
+export function dataText(data, cut, place = FIRST_TEXT_BLOCK) {
     const pretty = JSON.stringify(data, null, 2);
     if (pretty.length <= DATA_TEXT_BUDGET)
         return { text: pretty, said: "" };
@@ -167,7 +174,7 @@ export function dataText(data, cut) {
     const all = layout(data);
     if (all.length <= DATA_TEXT_BUDGET)
         return { text: all, said: "" };
-    const head = `TEXT CUT: the API's answer is ${pretty.length} characters of JSON, more than the ${DATA_TEXT_BUDGET} the first text block holds, so that block is cut, and structuredContent.data carries the answer whole.`;
+    const head = place.opens(pretty.length);
     const say = (...xs) => [head, ...xs].filter((x) => Boolean(x)).join(" ");
     let base = data;
     let rowsSaid = "";

package/dist/tools/check_affected.js

@@ -27,7 +27,7 @@
 // The JSON is relayed verbatim as data (#1874): every match keeps kev_listed, ransomware,
 // epss_score, effective_score, effective_severity and score_assessed as the API sent them.
 import * as z from "zod";
-import { TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
+import { GET_CVE_WHOLE, TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
 const TOOL = "check_affected";
 export const MATCH_PATH = "/api/v1/public/cves/match";
 // handler.go, the four request headers the endpoint reads before the query string.
@@ -129,7 +129,7 @@ export const CHECK_AFFECTED_TITLE = "Am I affected? (product or package at a ver
 export const CHECK_AFFECTED_DESCRIPTION = "Whether a product or package at a given version is affected by known CVEs, from the same matcher as echelongraph.io/am-i-affected. Two lookup paths. The CPE path takes product (the NVD CPE product token, such as openssl or nginx) and version, and 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 names the vendor NVD asserts (cpe_vendor) and whether that vendor was verified (vendor_unknown). The registry path takes ecosystem (npm, PyPI, Maven and other OSV ecosystem names), package and version, and decides each OSV advisory record EchelonGraph holds for that package as affected, not affected or undetermined. Read assessed before count: assessed false means the lookup did not evaluate this component, not_assessed_reason says why (product_not_in_cpe_corpus, package_not_cpe_nameable, candidate_load_pending, candidate_window_truncated, package_not_in_advisory_corpus, no_decidable_advisory), the structured result's state is not_assessed, and a count of 0 there must never be reported as not affected. An advisory whose version range cannot be decided at this version is reported as undetermined (undetermined_count, and up to 50 of them in undetermined), never as safe. The answer also carries match_layer (which path answered), capped (the match list stopped at its cap), candidates_capped (not every candidate CVE was loaded), excluded_count (CPE candidates suppressed by the vendor or platform gate), not_affected_count (advisories decided in your favour) and degraded (the lookup ran out of time). Each match carries cve_id, kev_listed, ransomware, epss_score, effective_score, effective_severity and score_assessed (false: EchelonGraph has not scored the CVE yet, so its echelongraph_score is withheld). Product, version, ecosystem and package travel in request headers, never in the URL. Its structured result carries state (measured only when the answer says assessed true), measured_at (null), method (which matcher answered), coverage (assessed and not_assessed_reason first, then the lookup path and the counts above), freshness (null) and notes, with data equal to the API's JSON." +
     " " +
     TEXT_BUDGET_DESCRIPTION +
-    " Cut, each entry of the excluded and undetermined samples keeps its cve_id and reason, cve_ids keeps its first 10 (each match carries its cve_id), and each match keeps fewer fields, cve_id, kev_listed, effective_score, effective_severity and score_assessed at least, so that every match stays in the text.";
+    " Cut, the excluded and undetermined samples keep their first 10 entries, each its cve_id and reason, cve_ids keeps its first 10 (each match carries its cve_id), and each match keeps fewer fields, cve_id, kev_listed, ransomware, epss_score, effective_score and score_assessed at least, so that every match stays in the text.";
 export const CHECK_AFFECTED_INPUT = z.object({
     product: z.string().optional().describe("CPE path: the NVD CPE product token, such as openssl, nginx or linux_kernel. Leave out for the registry path."),
     ecosystem: z.string().optional().describe("Registry path: the package's ecosystem, such as npm, PyPI or Maven. Give with package, not with product."),
@@ -172,17 +172,26 @@ function matchesNote(matches) {
 // description and match_reason, so openssl 3.0.0 (71 matches) was 156,058 characters of text and
 // linux_kernel 5.10.0 (200, the API's cap) 364,408. Past DATA_TEXT_BUDGET each match in the first
 // text block keeps its scores, flags, vendor attribution and match_reason (for a registry match,
-// the advisory interval its version falls inside, which names the fixed version) with the
+// the advisory interval its version falls inside: "[A, B)" names the fixed version B, "[A, B]" the
+// last affected one, #2830) with the
 // description cut to 200 characters; then the same without the description; then only the fields
-// the description promises; and last, for a list at the cap, cve_id, the effective score and
-// band, kev_listed and score_assessed. The lists beside the matches, the excluded sample (up to 50
-// CPE candidates the vendor or platform gate suppressed, each with a sentence of detail, 13,861
-// characters for flash_player 10.0.0) and the undetermined sample (up to 50), keep each entry's
-// cve_id and reason once the first level does not fit with them whole, before any match field
-// that level keeps goes, and the registry path's cve_ids, which is each match's cve_id in the
-// order of matches (core-backend cve/handler.go), keeps its first 10, so that every match stays
-// in the text, 200 at the cap with 50 undetermined beside them: this tool has no page to read
-// more from. structuredContent.data keeps every list whole.
+// the description promises; then, for a list at the cap, without cpe_vendor and vendor_unknown;
+// and last without effective_severity, the band of effective_score. kev_listed, ransomware,
+// epss_score, effective_score and score_assessed stay in every level (#2799): the am_i_affected
+// prompt asks for each match's ransomware and epss_score, and through 2.6.3 the last level left
+// them out of every match of a list at the cap (hosted linux_kernel 5.10.0, 200 matches, 1 with
+// known ransomware use, named nowhere in the text). 200 matches with effective_severity beside
+// them are 33,240 characters, past the budget alone, so the band goes first. The lists beside the
+// matches, the excluded sample (up to 50 CPE candidates the vendor or platform gate suppressed,
+// each with a sentence of detail, 13,861 characters for flash_player 10.0.0) and the undetermined
+// sample (up to 50), keep their first 10 entries, each its cve_id and reason, once the first level
+// does not fit with them whole, before any match field that level keeps goes (50 of them beside
+// 200 matches left the last level 120 characters past the budget for flash_player 10.0.0, and
+// 1,071 for a registry answer at the cap with 50 undetermined); and the registry path's cve_ids,
+// which is each match's cve_id in the order of matches (core-backend cve/handler.go), keeps its
+// first 10, so that every match stays in the text, 200 at the cap: this tool has no page to read
+// more from. excluded_count and undetermined_count count every entry. structuredContent.data keeps
+// every list whole.
 const CHECK_AFFECTED_TEXT = {
     rows: "matches",
     levels: [
@@ -208,14 +217,15 @@ const CHECK_AFFECTED_TEXT = {
             clip: 100,
         },
         { keep: ["cve_id", "kev_listed", "ransomware", "epss_score", "effective_score", "effective_severity", "score_assessed", "cpe_vendor", "vendor_unknown"], clip: 100 },
-        { keep: ["cve_id", "kev_listed", "effective_score", "effective_severity", "score_assessed"], clip: 100 },
+        { keep: ["cve_id", "kev_listed", "ransomware", "epss_score", "effective_score", "effective_severity", "score_assessed"], clip: 100 },
+        { keep: ["cve_id", "kev_listed", "ransomware", "epss_score", "effective_score", "score_assessed"], clip: 100 },
     ],
     sides: [
         { list: "cve_ids", cap: 10, said: () => "cve_ids lists each match's cve_id, in the order of matches." },
-        { list: "excluded", keep: ["cve_id", "reason"], clip: 100 },
-        { list: "undetermined", keep: ["cve_id", "reason"], clip: 100 },
+        { list: "excluded", keep: ["cve_id", "reason"], clip: 100, cap: 10 },
+        { list: "undetermined", keep: ["cve_id", "reason"], clip: 100, cap: 10 },
     ],
-    whole: "get_cve returns any one of these CVEs' records whole, and cve_intel a CVE's affected packages and fixed versions.",
+    whole: `${GET_CVE_WHOLE}, and cve_intel a CVE's affected packages and fixed versions.`,
 };
 async function checkAffected(kit, a) {
     const product = (a.product ?? "").trim();

package/dist/tools/check_sbom.js

@@ -42,6 +42,12 @@ const NOTE_AFFECTED_MAX = 25;
 const NOTE_CVES_MAX = 5;
 // CycloneDX nests components; this bounds the walk.
 const MAX_DEPTH = 32;
+// The order in which extract() reads and counts the distinct purls (#2799 review): purls as listed;
+// a CycloneDX document's components depth first, each one's nested components right after it
+// (fromCycloneDX); an SPDX document's packages as listed; each purl trimmed and kept at its first
+// place (dedupe). The note says it beside the position from which the purls not sent run, so a
+// second call can rebuild them from its own input whether or not the text cuts not_sent_purls.
+const READ_ORDER = "counted in the order this tool read them (the order of purls, or of the document's components or packages, each component's nested components right after it and before its next sibling, each purl at its first place)";
 const METHOD = "EchelonGraph's registry advisory matcher (POST /api/v1/public/cves/match/batch): each component's purl is mapped to its OSV ecosystem, package name and version, and matched against the affected version ranges EchelonGraph holds from OSV.dev advisory records, the same matcher GET /api/v1/public/cves/match uses when given an ecosystem. No CPE matching, no score, no ranking.";
 // Always in the envelope's notes, whatever the answer: the refusals a model must not read as clean.
 const DISTRO_NOTE = "A deb, apk or rpm purl without a distro qualifier naming its release (for example ?distro=debian-12 or ?distro=alpine-3.20) is not assessed (distro_release_unknown): the advisory corpus is keyed per distro release, and EchelonGraph does not guess one.";
@@ -57,7 +63,8 @@ export const CHECK_SBOM_DESCRIPTION = "Check a dependency list against EchelonGr
 // a CVE with its description, so the 50-component Juice Shop document was 112,820 characters of
 // text, and 2,000 purls about 1,200,000. Past DATA_TEXT_BUDGET each row in the first text block
 // keeps its verdict, counts and cve_ids, and each match its scores, flags and match_reason (the
-// advisory interval the version falls inside, which names the fixed version) without the
+// advisory interval the version falls inside: "[A, B)" names the fixed version B, "[A, B]" the last
+// affected one, #2830) without the
 // description; then the same without match_reason; then only index, purl, verdict,
 // not_assessed_reason and cve_ids. When rows must still go, the clean ones (not_affected) leave
 // first, then the not_assessed ones, both counted in data.summary and the note, so the affected
@@ -68,7 +75,8 @@ export const CHECK_SBOM_DESCRIPTION = "Check a dependency list against EchelonGr
 // fit with that list whole, the text keeps its first 10 and the note says which they are: the
 // input's distinct purls from position `sent` + 1 on, in input order, which is how check_sbom read
 // them (x.purls.slice(answers.length * MAX_COMPONENTS)), so a second call can send them without
-// reading the list.
+// reading the list. noteFor gives that order (READ_ORDER) beside the position, so this sentence
+// points to it.
 export function sbomText(sent) {
     const matches = ["cve_id", "severity", "effective_severity", "effective_score", "kev_listed", "ransomware", "epss_score", "score_assessed"];
     const row = ["index", "purl", "ecosystem", "package", "version", "verdict", "assessed", "not_assessed_reason", "count", "not_affected_count", "undetermined_count", "cve_ids"];
@@ -83,11 +91,13 @@ export function sbomText(sent) {
             {
                 list: "not_sent_purls",
                 cap: 10,
-                said: (_inText, total) => `The ${total} purls not sent are the input's distinct purls from position ${sent + 1} on, in the order this tool read them (the order of purls, or of the document's components, nested ones after their parent, each purl at its first place), so a second call can send them without reading the list.`,
+                said: (_inText, total) => `The ${total} purls not sent are the input's distinct purls from position ${sent + 1} on, counted in the order the note gives for them, so a second call can send them without reading the list.`,
             },
         ],
         leaveOutFirst: { field: "verdict", values: ["not_affected", "not_assessed"], why: "data.summary counts every verdict" },
-        whole: "check_affected, given a row's ecosystem, package and version, returns that component's matches whole, and cve_intel a CVE's affected packages and fixed versions.",
+        // check_affected cuts its text too past the budget (#2802): only its structuredContent.data is
+        // a component's matches whole.
+        whole: "check_affected, given a row's ecosystem, package and version, returns that component's matches, whole in its structuredContent.data, and cve_intel a CVE's affected packages and fixed versions.",
         page: (shown) => `To read every row in the text, check ${shown} or fewer purls per call.`,
     };
 }
@@ -236,9 +246,17 @@ function noteFor(head, x, d, g) {
     if (g.waits > 0) {
         out.push(`The API's component budget (${API_COMPONENTS_PER_MINUTE} components a minute) ran out ${g.waits === 1 ? "once" : `${g.waits} times`}: the tool waited ${Math.round(g.waited_ms / 1000)} s in all, as its Retry-After asked, and sent the batch again.`);
     }
+    // #2799: the position, not only the list. Past DATA_TEXT_BUDGET the first text block keeps the
+    // first 10 of data.not_sent_purls (sbomText), so a model that reads the text alone cannot send
+    // "that list"; the purls not sent are always the input's distinct purls from position sent + 1 on
+    // (x.purls.slice(answers.length * MAX_COMPONENTS)), which it can rebuild from its own input, given
+    // the order they are counted in (READ_ORDER), which this sentence says whenever it gives the
+    // position, not only when the text cuts the list.
     const notSent = g.not_sent_purls.length;
     if (notSent > 0) {
-        out.push(`${plural(notSent, "purl was", "purls were")} NOT sent (not_sent_reason ${g.not_sent_reason}: ${g.not_sent_detail}), so ${notSent === 1 ? "it is" : "they are"} not checked and not clean; data.not_sent_purls lists ${notSent === 1 ? "it" : "them"}: call check_sbom again with purls set to that list${g.not_sent_reason === "request_failed" ? "" : " after a minute"}.`);
+        const one = notSent === 1;
+        const where = one ? `it is the input's distinct purl at position ${g.sent + 1}` : `they are the input's distinct purls from position ${g.sent + 1} on`;
+        out.push(`${plural(notSent, "purl was", "purls were")} NOT sent (not_sent_reason ${g.not_sent_reason}: ${g.not_sent_detail}), so ${one ? "it is" : "they are"} not checked and not clean; ${where}, ${READ_ORDER}, and data.not_sent_purls lists ${one ? "it" : "them"}: call check_sbom again with purls set to ${one ? "it" : "them"}${g.not_sent_reason === "request_failed" ? "" : " after a minute"}.`);
     }
     out.push(`Of the ${components} components checked: ${affected} affected, ${notAffected} not affected, ${undetermined} undetermined, ${notAssessed} not assessed.`);
     const by = field(s, "not_assessed_by_reason");
@@ -335,7 +353,17 @@ export function mergeAnswers(answers) {
     out.results = results;
     return out;
 }
-const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const realSleep = (ms, signal) => new Promise((r) => {
+    if (signal?.aborted)
+        return r();
+    const done = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", done);
+        r();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+});
 export async function checkSbom(deps, a) {
     const tool = CHECK_SBOM;
     const sleep = deps.sleep ?? realSleep;
@@ -384,12 +412,17 @@ export async function checkSbom(deps, a) {
                 headers: { "Content-Type": "application/json" },
                 body: JSON.stringify({ components: batches[answers.length].map((purl) => ({ purl })) }),
                 timeoutMs: Math.max(0, left),
+                signal: deps.signal,
             });
             if (r.ok) {
                 answers.push(r.data);
                 status = r.status;
                 continue;
             }
+            // Cancelled (#2775): this batch was cut off, or never sent after a wait the signal ended.
+            // Nothing more is sent, and the answer goes nowhere.
+            if (deps.signal?.aborted)
+                return deps.failed(tool, r);
             if (r.kind === "http" && r.status === 429) {
                 if (r.retryAfter === undefined) {
                     stop = { reason: "rate_limited", detail: "the API answered 429 without a Retry-After to wait for" };
@@ -400,7 +433,7 @@ export async function checkSbom(deps, a) {
                 else {
                     const waitMs = Math.max(MIN_WAIT_MS, r.retryAfter * 1000);
                     if (now() - started + waitMs <= TIME_BUDGET_MS) {
-                        await sleep(waitMs);
+                        await sleep(waitMs, deps.signal);
                         waits++;
                         waitedMs += waitMs;
                         waitedFor = r;
@@ -567,9 +600,12 @@ export function registerCheckSbom(server, deps) {
             sbom: z
                 .union([z.string(), z.record(z.string(), z.unknown())])
                 .optional()
-                .describe("a CycloneDX JSON or SPDX JSON document, as JSON text or as an object; its purls are read here and only they are sent"),
+                .describe("a CycloneDX JSON or SPDX JSON document, as JSON text or as an object; its purls are read by this MCP server and only they are sent to the API; over the hosted endpoint (mcp.echelongraph.io) the document is the request body"),
         }),
         outputSchema: output,
         annotations: deps.annotations,
-    }, async (a) => deps.checked(CHECK_SBOM, output, await checkSbom(deps, a)));
+    }, async (a, ctx) => {
+        const run = checkSbom({ ...deps, signal: ctx.mcpReq.signal }, a);
+        return deps.checked(CHECK_SBOM, output, await (deps.hold ? deps.hold(run) : run));
+    });
 }

package/dist/tools/cve_intel.js

@@ -24,6 +24,15 @@
 // EXPLOIT_NUCLEI_ENABLED, EXPLOIT_POCGITHUB_ENABLED; core-backend cmd/server/main.go). The answer
 // does not say which ran, so no text here says a source is polled: it names the sources the data
 // model holds, and says coverage depends on which pollers run.
+//
+// Fixed versions (#2817). /enrichment keeps one affected_packages row per (CVE, ecosystem,
+// package), and its fixed_version is one range's fix: the last range's as the advisory was read
+// (core-backend cve/backfill_osv_packages.go summariseAffected). For CVE-2021-44228 production
+// served log4j-core 2.12.2 alone (2026-10-04), the fix for 2.4-2.12.1, below an affected 2.14.1.
+// Since #2817 each row also carries fixed_branches, the fix for every range (core-backend
+// cve/fixed_branches.go, from the version_intervals the matcher evaluates): this tool relays it as
+// sent, its description says how to pick the range for an installed version, and the note counts
+// the rows where fixed_version is not the whole answer.
 import * as z from "zod";
 import { ANNOTATIONS, CVE_ID, NOT_A_FINDING, SHOWN_BASE, api, badInput, boolAt, checked, crashed, envelopeSchema, failed, failure, field, numAt, okHead, opt, strAt, succeeded, } from "../index.js";
 import { TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
@@ -60,7 +69,8 @@ const API_ROW_LIMIT = { exploits: 10, affected_packages: 50, fixed_versions: 200
 const TIMELINE_RELAYED = 20;
 const CVE_INTEL_METHOD = "EchelonGraph's per-CVE enrichment (GET /api/v1/public/cves/:id/enrichment). cwes: CWE classifications stored from NVD, GitHub (GHSA) and CVE.org records, each with the source that gave it, named from the MITRE CWE catalog EchelonGraph embeds. exploits: public exploit references from EchelonGraph's cve_exploits records, whose data model holds Metasploit modules (metasploit), Exploit-DB entries (exploit_db), nuclei templates (nuclei_template), GitHub proof-of-concept repositories (github_poc) and vendor proofs of concept (vendor_poc), filled by a curated seed and by one poller per automated source, each run only where it is enabled, so which sources are current depends on the deployment. affected_packages and fixed_versions: package-ecosystem advisory data, each row naming its source. timeline: EchelonGraph's enrichment history for the CVE, newest first.";
 const VERIFIED_STATUS_DESCRIPTION = "verified_status is the label stored with each reference: verified for a Metasploit module, for an Exploit-DB entry Exploit-DB marks verified, and for curated seed rows marked so; reported for a public artefact nothing has confirmed works (nuclei templates, GitHub proofs of concept, unverified Exploit-DB entries); unconfirmed where a curated row says so. It is a label from the source, not a guarantee that the exploit works against a given system.";
-export const CVE_INTEL_DESCRIPTION = `Weakness, public exploit code, affected packages and fixed versions for one CVE, from EchelonGraph's per-CVE enrichment. Returns cwes (each cwe_id with its name and source), exploits (each with kind, source_name, source_url, first_seen_at and verified_status; at most 10, verified first) with exploits_total (every reference on record), exploits_capped (true when exploits lists fewer than exploits_total), exploits_by_kind and exploits_by_status, affected_packages (ecosystem, package_name, version_range, fixed_version), fixed_versions (ecosystem, package_name, vulnerable_range, fixed_version) and timeline (the newest enrichment-history rows, with timeline_total). ${VERIFIED_STATUS_DESCRIPTION} An empty exploits list is not evidence that no public exploit exists: it covers only the sources EchelonGraph ingests, and which of them are polled depends on the deployment. A section the API could not read is named in coverage.sections_failed and left out of data, never relayed as an empty list. Vendor advisories, patches, generated summaries, trending signals and historical incidents are not relayed. Pass a CVE ID like CVE-2021-44228. Its structured result carries state (measured), measured_at (null: each row carries its own time), method, coverage (the sections relayed, failed and left out, and per-list counts), freshness (null) and notes, with data, which the first text block holds whole up to 30,000 characters; the result's last text block repeats it without data and without the note's sentences (the text block before it), with which notes ends. ${TEXT_BUDGET_DESCRIPTION}`;
+const FIXED_BRANCHES_DESCRIPTION = 'fixed_branches lists each affected range of the package on record: introduced, and fixed (the range\'s fix) or last_affected (its last affected version, where no fix is on record), each null when absent, with advisory_id (the OSV record that published the range) and source (the loader\'s label for that record), both null on a row loaded before they were stored. Ranges with an advisory_id are in the order their record lists them (records in id order); ranges without one are oldest first. To pick the range for an installed version, compare in the ecosystem\'s version order (release numbers part by part, as numbers: 2.4 is below 2.13.0): the version is in a range when it is at or above introduced ("0" is the first version) and below fixed, or at or below last_affected; that range\'s fixed is the fix for it, and a version in no range is outside every range on record. fixed_branches is null where the package\'s ranges were never loaded, and [] where no version range is on record (the advisory gives none, only commit ranges, or more than are stored), which is not a finding that no fix exists: fixed_version can still name one. fixed_version is one range\'s fix, kept for compatibility (one per package: the range the loader kept, the advisory\'s last as a rule), not the fix for every affected range: for CVE-2021-44228, its advisory gives log4j-core three ranges, and fixed_version 2.12.2 is the fix for the one from 2.4, while the range holding 2.14.1 (from 2.13.0) is fixed in 2.15.0.';
+export const CVE_INTEL_DESCRIPTION = `Weakness, public exploit code, affected packages and fixed versions for one CVE, from EchelonGraph's per-CVE enrichment. Returns cwes (each cwe_id with its name and source), exploits (each with kind, source_name, source_url, first_seen_at and verified_status; at most 10, verified first) with exploits_total (every reference on record), exploits_capped (true when exploits lists fewer than exploits_total), exploits_by_kind and exploits_by_status, affected_packages (ecosystem, package_name, version_range, fixed_version, fixed_branches), fixed_versions (ecosystem, package_name, vulnerable_range, fixed_version: one row per fixed version, with the vulnerable_range it fixes where the source gives one) and timeline (the newest enrichment-history rows, with timeline_total). ${FIXED_BRANCHES_DESCRIPTION} ${VERIFIED_STATUS_DESCRIPTION} An empty exploits list is not evidence that no public exploit exists: it covers only the sources EchelonGraph ingests, and which of them are polled depends on the deployment. A section the API could not read is named in coverage.sections_failed and left out of data, never relayed as an empty list. Vendor advisories, patches, generated summaries, trending signals and historical incidents are not relayed. Pass a CVE ID like CVE-2021-44228. Its structured result carries state (measured), measured_at (null: each row carries its own time), method, coverage (the sections relayed, failed and left out, and per-list counts), freshness (null) and notes, with data, which the first text block holds whole up to 30,000 characters; the result's last text block repeats it without data and without the note's sentences (the text block before it), with which notes ends. ${TEXT_BUDGET_DESCRIPTION}`;
 // ── outputSchema ──
 const Rows = (shape) => z.array(z.looseObject(shape));
 const CountMap = z.record(z.string(), z.number());
@@ -88,7 +98,18 @@ function schemas() {
             ecosystem: opt(z.string()),
             package_name: opt(z.string()),
             version_range: opt(z.string()),
-            fixed_version: opt(z.string()),
+            fixed_version: opt(z.string()).describe("One range's fix, kept for compatibility; not the fix for every affected range: read fixed_branches."),
+            fixed_branches: z
+                .array(z.looseObject({
+                introduced: opt(z.string()).describe('The range\'s lower bound, inclusive; "0" is the first version.'),
+                fixed: opt(z.string()).describe("The range's fix: the first version past it. null where no fix is on record."),
+                last_affected: opt(z.string()).describe("The range's last affected version, inclusive, where no fix is on record; never a fix."),
+                advisory_id: opt(z.string()).describe("The OSV record that published the range (GHSA-…, PYSEC-…, CVE-…); null on a row loaded before it was stored."),
+                source: opt(z.string()).describe("The loader's label for that record (osv_bulk, osv); null on a row loaded before it was stored."),
+            }))
+                .nullable()
+                .optional()
+                .describe(FIXED_BRANCHES_DESCRIPTION),
             dependents_count: opt(z.number()),
             source: opt(z.string()),
         }).optional(),
@@ -170,6 +191,50 @@ function listSentence(name, rows) {
     const cut = rows.length >= limit ? `, the most the API returns per CVE, so there may be more` : "";
     return `${name} lists ${rows.length} row${rows.length === 1 ? "" : "s"}${cut}.`;
 }
+// #2817: where fixed_version is not the whole answer. A row with more than one range in
+// fixed_branches has a fix per range; a row with fixed_branches null has only fixed_version on
+// record, and so does a row with fixed_branches [] and a fixed_version (no version range on
+// record: none in the advisory, only commit ranges, or more than core-backend stores); an answer
+// whose rows carry no fixed_branches is an API older than #2817.
+function branchSentences(rows) {
+    if (rows.length === 0)
+        return [];
+    const named = (r, i) => {
+        const eco = strAt(r, "ecosystem");
+        const pkg = strAt(r, "package_name") ?? `affected_packages[${i}]`;
+        return eco ? `${pkg} (${eco})` : pkg;
+    };
+    const withField = rows.filter((r) => field(r, "fixed_branches") !== undefined);
+    if (withField.length === 0) {
+        return [
+            "No affected_packages row carries fixed_branches (an API older than that field): each row's fixed_version is one range's fix, which need not be the fix for a given installed version.",
+        ];
+    }
+    const out = [];
+    const multi = [];
+    const unknown = [];
+    const noRange = [];
+    rows.forEach((r, i) => {
+        const fb = field(r, "fixed_branches");
+        if (Array.isArray(fb) && fb.length > 1)
+            multi.push(named(r, i));
+        if (fb === null)
+            unknown.push(named(r, i));
+        if (Array.isArray(fb) && fb.length === 0 && strAt(r, "fixed_version"))
+            noRange.push(named(r, i));
+    });
+    const few = (xs) => (xs.length <= 3 ? listed(xs) : `${xs.slice(0, 3).join(", ")} and ${xs.length - 3} more`);
+    if (multi.length) {
+        out.push(`${multi.length} affected_packages row${multi.length === 1 ? " lists" : "s list"} more than one affected range in fixed_branches (${few(multi)}): there, fixed_version is one range's fix, and an installed version's fix is the fixed of the range that holds it.`);
+    }
+    if (unknown.length) {
+        out.push(`${unknown.length} affected_packages row${unknown.length === 1 ? " carries" : "s carry"} fixed_branches null (${few(unknown)}): ${unknown.length === 1 ? "its" : "their"} ranges are not on record, so fixed_version, one range's fix, is all the answer holds, and it need not be the fix for a given installed version.`);
+    }
+    if (noRange.length) {
+        out.push(`${noRange.length} affected_packages row${noRange.length === 1 ? " carries" : "s carry"} fixed_branches [] and a fixed_version (${few(noRange)}): no version range is on record there, which is not a finding that no fix exists, so fixed_version, one range's fix, is all the answer holds, and it need not be the fix for a given installed version.`);
+    }
+    return out;
+}
 // ── The tool ──
 export async function cveIntel(cve_id) {
     const id = cve_id.trim();
@@ -218,6 +283,8 @@ export async function cveIntel(cve_id) {
             const xs = rows(k);
             if (xs)
                 said.push(listSentence(k, xs));
+            if (xs && k === "affected_packages")
+                said.push(...branchSentences(xs));
         }
         const timeline = rows("timeline");
         const apiTimeline = field(d, "timeline");

package/dist/tools/get_cwe.js

@@ -13,7 +13,7 @@
 // the note says it can lag the feed.
 import * as z from "zod";
 import { ANNOTATIONS, api, badInput, checked, crashed, envelopeSchema, failed, field, lenAt, numAt, okHead, opt, rowsScoreNote, strAt, succeeded, } from "../index.js";
-import { TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
+import { GET_CVE_WHOLE, TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
 const TOOL = "get_cwe";
 const CWE_ARG = /^(?:CWE-)?0*(\d{1,6})$/i;
 const MAX_PAGE = 200;
@@ -25,7 +25,7 @@ export const GET_CWE_DESCRIPTION = `One CWE (weakness class) and the CVEs classi
 const GET_CWE_TEXT = {
     rows: "cves",
     levels: [{ keep: ["cve_id", "severity", "cvss_v3_score", "echelongraph_score", "echelongraph_severity", "score_assessed", "score_unassessed_reason", "kev_listed", "published", "description"], clip: 120 }],
-    whole: "get_cve returns any one of these CVEs' records whole.",
+    whole: `${GET_CVE_WHOLE}.`,
 };
 function schemas() {
     const row = z.looseObject({

package/dist/tools/kev_recent.js

@@ -1,5 +1,5 @@
 import * as z from "zod";
-import { TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
+import { GET_CVE_WHOLE, TEXT_BUDGET_DESCRIPTION } from "../textBudget.js";
 const TOOL = "kev_recent";
 const PATH = "/api/v1/public/kev/recent";
 export const KEV_RECENT_MAX_LIMIT = 200;
@@ -140,7 +140,8 @@ function kevText(a) {
             { keep: ["cve_id", "kev_added_date", "kev_vendor", "kev_product", "kev_ransomware"], clip: 40 },
             { keep: ["cve_id", "kev_added_date", "kev_vendor", "kev_ransomware"], clip: 40 },
         ],
-        whole: "get_cve returns any one of these CVEs' records whole.",
+        // A record carries the CISA fields a row leaves out (kev_due_date, kev_product, kev_vuln_name).
+        whole: `${GET_CVE_WHOLE}.`,
         page: (shown) => `next_cursor continues after the last row of this page, not after the last row in this text: to read the rows left out in the text, call kev_recent again with the same filters${a.cursor?.trim() ? " and cursor" : ""} and a limit of ${shown}, whose rows are the ones in this text, then with that page's next_cursor and a limit of ${shown} or fewer.`,
     };
 }