echelongraph-mcp 3.0.2 → 3.1.0

package/dist/tools/match_batch.js

@@ -282,6 +282,60 @@ export function sendingSentences(g, distinct, readOrder, retry, positions = true
     }
     return out;
 }
+// One affected component as the note names it: its purl, and its first NOTE_CVES_MAX cve_ids.
+const affectedNamed = (r) => {
+    const who = (typeof field(r, "purl") === "string" && field(r, "purl")) || `${field(r, "ecosystem") ?? ""} ${field(r, "package") ?? ""} ${field(r, "version") ?? ""}`.trim();
+    const ids = field(r, "cve_ids");
+    const list = Array.isArray(ids) ? ids.filter((i) => typeof i === "string") : [];
+    const shown = list.slice(0, NOTE_CVES_MAX).join(", ");
+    return `${who} (${shown}${list.length > NOTE_CVES_MAX ? `, and ${list.length - NOTE_CVES_MAX} more` : ""})`;
+};
+const affectedTail = (more) => (more > 0 ? `; and ${more} more affected components in data.results (whole with full: true)` : "");
+// The note's sentence naming the affected components, the first NOTE_AFFECTED_MAX of `hits`.
+function affectedSaid(hits) {
+    return `Affected: ${hits.slice(0, NOTE_AFFECTED_MAX).map(affectedNamed).join("; ")}${affectedTail(hits.length - NOTE_AFFECTED_MAX)}.`;
+}
+// #3269's third review: the characters, as a JSON string, of each row's name in that sentence,
+// measured once per row object (the structured cut asks of the same rows many times).
+const namedChars = new WeakMap();
+const namedCharsOf = (r) => {
+    if (!isObj(r))
+        return JSON.stringify(affectedNamed(r)).length - 2;
+    let c = namedChars.get(r);
+    if (c === undefined)
+        namedChars.set(r, (c = JSON.stringify(affectedNamed(r)).length - 2));
+    return c;
+};
+const isAffected = (r) => field(r, "verdict") === "affected";
+// The sentence's characters in the answer being cut, once per answer's rows.
+const saidChars = new WeakMap();
+/**
+ * #3269's third review: for a call of `m` of `rows` alone, the most characters (as JSON) the note's
+ * Affected sentence can take there, less what it takes in the answer of `all` (the call being cut;
+ * negative where a call of m of them names fewer or shorter components). A call of other purls
+ * names other components there, so a call that re-checks the rows a cut left out can carry a longer
+ * note than this one; it names at most NOTE_AFFECTED_MAX of its affected rows, so at most that many,
+ * or m, of these rows' longest names, and the tail counting the rest.
+ */
+export function affectedSaidOver(rows, all) {
+    const longest = rows.filter(isAffected).map(namedCharsOf).sort((a, b) => b - a);
+    const top = [0];
+    for (const c of longest.slice(0, NOTE_AFFECTED_MAX))
+        top.push(top[top.length - 1] + c);
+    let now = saidChars.get(all);
+    if (now === undefined) {
+        const own = all.filter(isAffected);
+        saidChars.set(all, (now = own.length ? JSON.stringify(affectedSaid(own)).length - 2 : 0));
+    }
+    const was = now;
+    return (m) => {
+        const hits = Math.min(m, longest.length);
+        if (hits === 0)
+            return -was;
+        const named = Math.min(hits, NOTE_AFFECTED_MAX);
+        return "Affected: ".length + top[named] + 2 * (named - 1) + affectedTail(hits - NOTE_AFFECTED_MAX).length + 1 - was;
+    };
+}
 // The verdict counts, the not-assessed reasons, the affected components by name, and the
 // upstream-matched rows, from the (merged) answer.
 export function verdictSentences(d, g) {
@@ -310,17 +364,10 @@ export function verdictSentences(d, g) {
     if (Array.isArray(rows)) {
         const hits = rows.filter((r) => field(r, "verdict") === "affected");
         if (hits.length) {
-            const named = hits.slice(0, NOTE_AFFECTED_MAX).map((r) => {
-                const who = (typeof field(r, "purl") === "string" && field(r, "purl")) || `${field(r, "ecosystem") ?? ""} ${field(r, "package") ?? ""} ${field(r, "version") ?? ""}`.trim();
-                const ids = field(r, "cve_ids");
-                const list = Array.isArray(ids) ? ids.filter((i) => typeof i === "string") : [];
-                const shown = list.slice(0, NOTE_CVES_MAX).join(", ");
-                return `${who} (${shown}${list.length > NOTE_CVES_MAX ? `, and ${list.length - NOTE_CVES_MAX} more` : ""})`;
-            });
-            out.push(`Affected: ${named.join("; ")}${hits.length > NOTE_AFFECTED_MAX ? `; and ${hits.length - NOTE_AFFECTED_MAX} more affected components in data.results` : ""}.`);
+            out.push(affectedSaid(hits));
             // Said only when the answer carries fixed_in (an API before #2834 sends none).
             if (hits.some((r) => (Array.isArray(field(r, "matches")) ? field(r, "matches") : []).some((m) => isObj(m) && "fixed_in" in m))) {
-                out.push("Each match's fixed_in is the first version above the component's that no affected interval of the advisory holds; null, with fixed_in_reason, where the advisory records no fix for that version.");
+                out.push("Each match's fixed_in is the first version above the component's that no affected interval of the advisory holds; null, with fixed_in_reason, where no higher version is shown to be unaffected.");
             }
         }
         // #2836: rows matched by the source package their purl's upstream qualifier names.
@@ -395,7 +442,7 @@ export const Row = z.looseObject({
         fixed_in_versions: z.array(z.string()).optional(),
     })
         .optional()
-        .describe("Present only on a row whose matches the structured result's cut (DATA CUT) shortened or left out: total, the row's matches in the answer; returned, the ones data keeps (its first, highest effective_score first); and, while they fit, of all its matches, the CVE IDs KEV-listed (kev_listed_cve_ids) or used in ransomware (ransomware_cve_ids), and the distinct fixed_in versions (fixed_in_versions). The same call with full: true returns every match."),
+        .describe("Present only on a row whose matches the structured result's cut (DATA CUT) shortened or left out: total, the row's matches in the answer; returned, the ones data keeps (chosen used in ransomware first, then the other KEV-listed ones, then highest effective_score, and listed in the API's order); and, while they fit, of all its matches, the CVE IDs KEV-listed (kev_listed_cve_ids) or used in ransomware (ransomware_cve_ids), and the distinct fixed_in versions (fixed_in_versions). The same call with full: true returns every match."),
 });
 // The batch route's answer, as data carries it: its fields, merged over the batches.
 export const batchDataShape = {

package/dist/tools/packageRecords.js

@@ -0,0 +1,58 @@
+// #3285: which rows of a CVE's affected packages are one package, as core-backend's registry
+// matcher reads them. A module of its own, with no import, so cve_remediation (fixed_branches) and
+// cve_intel (affected_packages) state the same reading.
+//
+// core-backend cve/pkgecosystem.go: baseTokenMatchableEcosystems names the base tokens whose ":"
+// suffix is a repository locator, not a release (Packagist, Maven), and ecosystemBaseToken is the
+// lowercased, trimmed token before the first ":". cve/pkgmatch_fixedin.go registryRecordKey folds
+// a suffixed ecosystem onto its base only when that base is one of them, so a row of one
+// package_name under "Packagist:https://packages.drupal.org/8" and one under "Packagist" are one
+// record, whose ranges the matcher walks together; a distro's release suffix (Debian:12,
+// Alpine:v3.20) stays in the key and is never folded. CVE-2025-48013 lists drupal/quick_node_block
+// under both (fixed 2.0.1 and fixed 2.0.0, each from 0): read row by row, a Packagist 1.0.0 gets
+// 2.0.0, which the Drupal advisory still holds affected; as one package it gets 2.0.1, the
+// matcher's fixed_in. (registryRecordKey also spells a PyPI name the PEP 503 way; a PyPI row is
+// never listed under two ecosystem strings, so that plays no part here.)
+export const BASE_MATCHABLE_ECOSYSTEMS = ["packagist", "maven"];
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const str = (v, k) => {
+    const x = isObject(v) ? v[k] : undefined;
+    return typeof x === "string" && x.trim() ? x : undefined;
+};
+/** core-backend ecosystemBaseToken: the lowercased, trimmed token before the first ":". */
+export function ecosystemBaseToken(raw) {
+    const t = raw.trim().toLowerCase();
+    const i = t.indexOf(":");
+    return i > 0 ? t.slice(0, i) : t;
+}
+/** The ecosystem part of core-backend's registryRecordKey: lowercased, folded onto its base only where the base is base-matchable. */
+export function recordEcosystem(raw) {
+    const eco = raw.trim().toLowerCase();
+    const base = ecosystemBaseToken(eco);
+    return base !== eco && BASE_MATCHABLE_ECOSYSTEMS.includes(base) ? base : eco;
+}
+/**
+ * The packages `rows` (each with ecosystem and package_name) list under more than one ecosystem
+ * string that the matcher folds into one record, in the order each was first listed; `folded` is
+ * how many rows fold into another so.
+ */
+export function packagesListedTwice(rows) {
+    const groups = new Map();
+    rows.forEach((r, i) => {
+        const eco = str(r, "ecosystem");
+        const name = str(r, "package_name");
+        if (!eco || !name || !BASE_MATCHABLE_ECOSYSTEMS.includes(ecosystemBaseToken(eco)))
+            return;
+        const key = `${recordEcosystem(eco)}\u0000${name.trim().toLowerCase()}`;
+        const g = groups.get(key) ?? { name, ecosystems: [], rows: [] };
+        if (!g.ecosystems.includes(eco))
+            g.ecosystems.push(eco);
+        g.rows.push(i);
+        groups.set(key, g);
+    });
+    const twice = [...groups.values()].filter((g) => g.ecosystems.length > 1);
+    return { twice, folded: twice.reduce((t, g) => t + g.rows.length - 1, 0) };
+}
+// What a note says of such rows, in cve_remediation's entries and cve_intel's rows alike: the rule
+// the matcher applies, stated so that an agent walking the ranges reads them as it does.
+export const ONE_PACKAGE_RULE = (what) => `${what} of one package_name under Packagist or Maven, bare or with a repository URL after ":", are one package, its ranges all of theirs together`;

package/dist/tools/scan_manifest.js

@@ -15,11 +15,16 @@ const TEXT_NOT_CHECKED = 20;
 // The order the distinct purls are counted in, for the position of those not sent (#2799).
 const READ_ORDER = "counted in the order this tool read them (the files in the order given, each file's entries in the order the file lists them, each purl at its first place)";
 const NOT_CHECKED_NOTE = "not_checked entries are not clean: each names a dependency this tool did not send to the API (its version is a range or unresolved, or it comes from a local path, a VCS checkout or a line this tool does not read), so no verdict was looked up for it.";
+// 3.1.0's phase A review: fix C's wording tied "50 seconds a call" to the 429 wait alone, while
+// match_batch.ts's TIME_BUDGET_MS bounds the whole call: a slow batch is cut off at its end
+// (time_budget), and a 429 refused (rate_limited) or a batch failed (request_failed) after the first
+// also answers partial, the rest in not_sent_purls. 3.0.2's "within 50 seconds" said so; the
+// description says it again, the room from shorter wording elsewhere (every claim kept).
 export const SCAN_MANIFEST_TITLE = "Check a lockfile against the advisory corpus";
-export const SCAN_MANIFEST_DESCRIPTION = "Check a project's lockfile or pinned manifest against EchelonGraph's advisory corpus, one verdict per dependency. Pass files: 1 to 20 of filename and content, up to 5,000,000 characters in all; the filename, or format, gives the format. Read: requirements.txt (== and === pins only), go.mod (require, after replace and exclude), package-lock.json and npm-shrinkwrap.json (v1 to v3), Cargo.lock, Gemfile.lock, composer.lock, poetry.lock and gradle.lockfile. package.json, pyproject.toml, Pipfile, Gemfile, Cargo.toml, composer.json and build.gradle hold ranges and are refused, naming the lockfile to pass; go.sum is refused: it lists versions the build does not select. This server reads the files into purls and only the purls are sent to the API, in POST bodies of at most 200, never in a URL; filenames and file contents are not sent on. Run from npm, this server is on your machine; over the hosted endpoint (mcp.echelongraph.io) it is EchelonGraph's, and the files are the request body, accepted up to 6 MiB. data.results holds one row per distinct purl, with verdict (affected, not_affected, undetermined or not_assessed), not_assessed_reason, cve_ids and matched_via; each match carries kev_listed, epss_score and fixed_in or null with fixed_in_reason. not_affected is the only clean verdict. data.not_checked lists each entry not sent, with file, line and reason: version_unpinned (a range), version_unresolved, local_path, vcs_source or unsupported_line; not_checked entries are not clean. At most 2,000 distinct purls per call, within 50 seconds; data.not_sent_purls lists any not sent, unchecked and not clean." +
+export const SCAN_MANIFEST_DESCRIPTION = "Check a project's lockfile or pinned manifest against EchelonGraph's advisory corpus, one verdict per dependency. Pass files: 1 to 20 of filename and content, up to 5,000,000 characters in all; the filename or format gives the format. Read: requirements.txt (== and === pins only), go.mod (require, after replace and exclude), package-lock.json and npm-shrinkwrap.json (v1-v3), Cargo.lock, Gemfile.lock, composer.lock, poetry.lock and gradle.lockfile. package.json, pyproject.toml, Pipfile, Gemfile, Cargo.toml, composer.json and build.gradle hold ranges and are refused, naming the lockfile; go.sum is refused: it lists versions the build does not select. The server reads the files into purls; only the purls are sent to the API, in POST bodies of at most 200, never in a URL; filenames and file contents are not sent on. Run from npm, this server is on your machine; over the hosted endpoint (mcp.echelongraph.io) it is EchelonGraph's, and the files are the request body, up to 6 MiB. data.results holds a row per distinct purl, with verdict (affected, not_affected, undetermined or not_assessed), not_assessed_reason, cve_ids and matched_via; each match carries kev_listed, epss_score and fixed_in or null with fixed_in_reason. not_affected is the only clean verdict. data.not_checked lists each entry not sent (file, line, reason); not_checked entries are not clean. At most 2,000 distinct purls and 50 seconds a call. The API allows 1,200 components a minute per caller; on a 429 it waits out Retry-After within that; a later batch cut off, refused or failed ends the call, the rest in data.not_sent_purls, unchecked, not clean." +
     " " +
     TEXT_BUDGET_DESCRIPTION +
-    " Cut, each row keeps index, purl, verdict, not_assessed_reason and cve_ids at least; not_checked keeps its first 20.";
+    " Cut, each row keeps index, purl, verdict, not_assessed_reason and cve_ids at least; not_checked its first 20.";
 // The text's cut: check_sbom's rows and levels, and data.not_checked beside them, cut to its
 // first TEXT_NOT_CHECKED once the first level does not fit (structuredContent.data keeps it whole).
 // #3132's second review: check_sbom's sentence on not_sent_purls says a second call can send them
@@ -42,12 +47,14 @@ export function manifestText(sent) {
                 said: (inText, total) => `coverage.not_checked_by_reason counts all ${total} entries not checked, ${inText} of them in the text.`,
             },
         ],
-        page: (shown) => `To read every row in the text, pass files that hold ${shown} or fewer distinct purls per call.`,
+        // #3269's second review: no page sentence, as for check_sbom's text (sbomText says why).
     };
 }
 // #3013: the structured result's cut, check_sbom's (sbomData: the lists beside the rows, then every
 // row thinned, then rows leaving, clean ones first) with not_checked beside not_sent_purls.
-const MANIFEST_DATA = sbomData(["not_sent_purls", "not_checked"], (k) => `To read every row in data, pass files that hold ${k} or fewer distinct purls per call.`);
+// #3269's second review: the sentence promises only what holds (check_sbom.ts sbomPageSaid).
+export const manifestPageSaid = (k) => `A call whose files hold the first ${k} of these purls, or fewer, keeps every row in data; a call of other files says in its own note what it leaves out.`;
+const MANIFEST_DATA = sbomData(["not_sent_purls", "not_checked"], manifestPageSaid);
 export function readFiles(a) {
     if (!Array.isArray(a.files))
         return "files must be a list of {filename, content}";

package/dist/tools/vendor_advisories.js

@@ -77,6 +77,18 @@ const CVE_ID = /^CVE-\d{4}-\d{4,}$/i;
 const VENDOR_SLUG = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
 // No control characters (a header or log line could carry them), at most 200 characters.
 const ADVISORY_ID = /^[^\x00-\x1f\x7f]{1,200}$/;
+// #3011: a row's advisory_id is EchelonGraph's own ID for the advisory, a UUID (vendor_advisories,
+// migration 063). The detail route is keyed on the vendor's ID, vendor_advisory_id (handler.go
+// Detail, store.go GetAdvisoryByVendorAndID: WHERE v.slug = $1 AND va.vendor_advisory_id = $2), and
+// the API has no route by the UUID, so get_vendor_advisory given a row's advisory_id answered a
+// 404, worded as no record, for an advisory the API holds (CVE-2024-3400's Palo Alto row,
+// a68d033b-5d1e-4537-8190-5e37897a27e8, 2026-10-10). A vendor's own ID could have that shape too, so
+// the API is still asked; only its 404 for an ID of that shape is answered as the refusal it is.
+const INTERNAL_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// What a row's two IDs are, in the outputSchema of all three tools (the detail echoes advisory_id).
+// Facts only, naming no other tool (test/description-policy.test.mjs: the MCP Directory policy).
+const ROW_ADVISORY_ID_FIELD = "EchelonGraph's internal ID for this advisory, a UUID. It is not the vendor's advisory ID (vendor_advisory_id), and an advisory's detail is not looked up by it: the detail is keyed on vendor and vendor_advisory_id.";
+const VENDOR_ADVISORY_ID_FIELD = "The vendor's own ID for the advisory (e.g. RHSA-2024:1234, GHSA-xxxx-xxxx-xxxx, or the CVE ID for Microsoft and Palo Alto Networks). With vendor, it is the key an advisory's detail is looked up by, as its advisory_id argument.";
 const METHOD = "EchelonGraph's vendor-advisory feed: advisories as each vendor published them in its own feed (for example Microsoft MSRC, Red Hat, Cisco, Palo Alto Networks and GitHub GHSA), each feed polled on a schedule; advisories of a feed EchelonGraph has disabled are left out.";
 const NO_FRESHNESS = "freshness is null: these answers carry no time at which the vendor-advisory pollers last completed a poll.";
 const DATES = "vendor_published_at is the date the vendor gives for the advisory; our_first_seen_at is when EchelonGraph first recorded it, which is not the vendor's date.";
@@ -245,10 +257,10 @@ const REMEDIATION_KINDS_FIELD = "The kinds of remediation the advisory lists (fo
 const REMEDIATION_KINDS = ["vendor_fix", "workaround", "mitigation", "no_fix_planned", "none_available", "other"];
 const REMEDIATION_STATES = ["parsed", "none_in_source", "not_parsed", "withdrawn"];
 const AdvisoryRow = z.looseObject({
-    advisory_id: opt(z.string()),
+    advisory_id: opt(z.string()).describe(ROW_ADVISORY_ID_FIELD),
     vendor: opt(z.string()),
     vendor_display_name: opt(z.string()),
-    vendor_advisory_id: opt(z.string()),
+    vendor_advisory_id: opt(z.string()).describe(VENDOR_ADVISORY_ID_FIELD),
     cve_ids: opt(z.array(z.string())),
     title: opt(z.string()),
     severity: opt(z.string()),
@@ -501,6 +513,13 @@ export function registerVendorAdvisoryTools(server, kit) {
         }
     }
     // ── get_vendor_advisory ──
+    // #3011: advisory_id was a row's advisory_id (a UUID), not its vendor_advisory_id. The API was
+    // asked (a vendor's own ID could be shaped so) and holds no advisory of the vendor under it, which
+    // is the wrong ID passed, not a missing advisory: invalid_input, naming the field to pass.
+    function internalIdRefusal(vendor, id, path) {
+        const why = `advisory_id ${id} has the shape of a row's advisory_id, EchelonGraph's internal ID for an advisory (a UUID), which this tool does not take, and EchelonGraph holds no ${vendor} advisory whose vendor_advisory_id it is (HTTP 404)`;
+        return kit.failure("invalid_input", `get_vendor_advisory FAILED (state: invalid_input): ${why}. Call get_vendor_advisory again with the row's vendor and its vendor_advisory_id as advisory_id (e.g. CVE-2024-3400 for Palo Alto Networks, RHSA-2024:1234 for Red Hat). This says nothing about whether the advisory exists, and it is not a finding.`, { kind: "invalid_input", path, status: 404, message: `${why}; pass the row's vendor_advisory_id as advisory_id` });
+    }
     async function detail(vendorArg, idArg) {
         const tool = "get_vendor_advisory";
         const vendor = vendorArg.trim();
@@ -516,6 +535,8 @@ export function registerVendorAdvisoryTools(server, kit) {
         try {
             const windowsRead = readWindows();
             const r = await kit.api(`/api/v1/public/vendor-advisories/${encodeURIComponent(vendor)}/${encodeURIComponent(id)}`);
+            if (!r.ok && r.kind === "http" && r.status === 404 && INTERNAL_ID.test(id))
+                return internalIdRefusal(vendor, id, r.path);
             if (!r.ok)
                 return kit.failed(tool, r);
             const w = await windowsRead;
@@ -657,10 +678,12 @@ export function registerVendorAdvisoryTools(server, kit) {
     }, async ({ cve_id, full }) => kit.checked("vendor_advisories_for_cve", FOR_CVE_OUTPUT, await answering(full, FOR_CVE_DATA, () => forCVE(cve_id))));
     server.registerTool("get_vendor_advisory", {
         title: "Vendor advisory detail",
-        description: `One vendor advisory in full, by vendor and the vendor's advisory ID (the vendor and vendor_advisory_id of a vendor advisory row): title, description, severity, cvss_v3_score, cve_ids and known_cve_ids (those with a record in EchelonGraph's CVE feed), affected_products, remediation, references, vendor_modified_at, and withdrawn_at and withdrawn_reason when the vendor withdrew it. remediations lists each remediation the vendor lists, with kind (the vendor's own category, never read from the text: vendor_fix, workaround, mitigation, no_fix_planned, none_available or other), source_category, text, url and the cve_ids and product_ids it covers; each text is the vendor's, verbatim, untested by EchelonGraph. remediation_state is parsed, none_in_source, not_parsed or withdrawn: none_in_source and not_parsed are not a finding that no fix exists. ${DATES_DESCRIPTION} ${REJECTED_CVE_DESCRIPTION} coverage.vendor_window is that vendor's window in what EchelonGraph holds: ${WINDOW_HEAD}; null when the windows could not be read or carry none for that vendor. measured_at is our_first_seen_at. ${ENVELOPE_DESCRIPTION} ${TEXT_BUDGET_DESCRIPTION}`,
+        description: `One vendor advisory in full, by vendor and the vendor's advisory ID (the vendor and vendor_advisory_id of a vendor advisory row, never its advisory_id, EchelonGraph's internal UUID): title, description, severity, cvss_v3_score, cve_ids and known_cve_ids (those with a record in EchelonGraph's CVE feed), affected_products, remediation, references, vendor_modified_at, and withdrawn_at and withdrawn_reason when the vendor withdrew it. remediations lists each remediation the vendor lists, with kind (the vendor's own category, never read from the text: vendor_fix, workaround, mitigation, no_fix_planned, none_available or other), source_category, text, url and the cve_ids and product_ids it covers; each text is the vendor's, verbatim, untested by EchelonGraph. remediation_state is parsed, none_in_source, not_parsed or withdrawn: none_in_source and not_parsed are not a finding that no fix exists. ${DATES_DESCRIPTION} ${REJECTED_CVE_DESCRIPTION} coverage.vendor_window is that vendor's window in what EchelonGraph holds: ${WINDOW_HEAD}; null when the windows could not be read or carry none for that vendor. measured_at is our_first_seen_at. ${ENVELOPE_DESCRIPTION} ${TEXT_BUDGET_DESCRIPTION}`,
         inputSchema: z.object({
             vendor: z.string().describe("the vendor slug, e.g. microsoft, redhat, github"),
-            advisory_id: z.string().describe("the vendor's advisory ID, e.g. RHSA-2024:1234 or GHSA-xxxx-xxxx-xxxx"),
+            advisory_id: z
+                .string()
+                .describe("the vendor's own advisory ID, a row's vendor_advisory_id, e.g. RHSA-2024:1234, GHSA-xxxx-xxxx-xxxx or CVE-2024-3400; not a row's advisory_id, EchelonGraph's internal UUID"),
             full: FULL_ARG,
         }),
         outputSchema: DETAIL_OUTPUT,

package/docs/exposure-radar.md

@@ -43,6 +43,7 @@ maps to a CISA-KEV-listed CVE (see [How `cve_exposure` counts](tools.md#how-cve_
 | `kev_exposure.newest_kev[].cvss_v3_score`, `kev_exposure.newest_kev[].epss_score` | Scores, not counts: the CVE record's CVSS v3 base score and EPSS probability (0 to 1), absent when the record has none. |
 | `kev_exposure.last_run_at` | A timestamp, not a count: when the radar last completed a check, a cycle in which its Shodan search answered at least one query (others may have failed) and its list of services due for a re-check was read. A cycle that skipped the search for want of Shodan query credits, or whose reads failed, does not move it. |
 | `kev_exposure.window.from`, `kev_exposure.window.to` | Timestamps, not counts: when Shodan collected the banners of the oldest and the newest of the service×CVE pairs counted, Shodan's own times, not when EchelonGraph stored or re-checked a pair; a span of observations made at different times. Relayed only when every counted pair has such a time; otherwise the note says how many do not. |
+| `kev_exposure.dated_window.from`, `kev_exposure.dated_window.to`, `kev_exposure.dated_window.undated` | Relayed instead of the window when some counted pairs have no banner time on record (pairs stored before the banner time was captured stay so while the InternetDB re-check keeps them): from and to are the same Shodan banner times over the dated pairs only, and undated counts the pairs with none. The note gives both numbers; the window does not describe the undated pairs. |
 
 A `newest_kev` row's `exposure_state` says whether its count is a measurement:
 
@@ -61,6 +62,7 @@ A `newest_kev` row's `exposure_state` says whether its count is a measurement:
 | `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.dated_window.from`, `exposed_databases.dated_window.to`, `exposed_databases.dated_window.undated` | Relayed instead of the window when some counted services have no such time on record: from and to span the dated services only, and undated counts those with none. |
 | `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`
@@ -72,6 +74,7 @@ A `newest_kev` row's `exposure_state` says whether its count is a measurement:
 | `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.dated_window.from`, `leaked_credentials.dated_window.to`, `leaked_credentials.dated_window.undated` | Relayed instead of the window when some counted pairs have no such time on record: from and to span the dated pairs only, and undated counts those with none. |
 | `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
@@ -90,6 +93,7 @@ labels each one. Only `shadow_ai.confirmed_exposed` counts exposed services.
 | `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. |
+| `confirmed_exposed.dated_window.from`, `confirmed_exposed.dated_window.to`, `confirmed_exposed.dated_window.undated` | Relayed instead of the window when some confirmed-exposed services have no such time on record: from and to span the dated ones only, and undated counts those with none. |
 | `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. |

package/docs/rate-limits.md

@@ -34,7 +34,9 @@ JSON-RPC error (code `-32029`) that names the limit and the seconds to wait. A r
 64 KiB is refused (HTTP 413, code `-32600`), except a `tools/call` of `check_sbom` or
 `scan_manifest`, or a `prompts/get` of `sbom_review`, which may be up to 6 MiB: enough for a
 CycloneDX or SPDX document, or a call's lockfiles, at the tools' 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`). Each
+once; a third waits up to 15 seconds for one to finish (two may wait at once), and is answered
+HTTP 503 with `Retry-After` and a JSON-RPC error (code `-32030`) only when that wait runs out, or at
+once when two are already waiting. Each
 instance serves at most 64 requests at once; the next waits up to 10 seconds for one to finish,
 and is then answered the same way. A `subscriptions/listen` stream, which stays open until its
 client leaves, is not one of the 64.
@@ -46,5 +48,6 @@ server at all (<https://docs.cloud.google.com/run/docs/troubleshooting>). The ho
 speaks HTTP/2 to Cloud Run, where the same page says a disconnect is passed on. Measured on
 2026-10-05, Cloud Run reset the stream of a client that stopped reading its answer 15 s in, and the
 call was logged as a client that closed. Whether a client that aborts mid-call is passed on at once
-has not been observed yet. Until it is, an abandoned `check_sbom` or `scan_manifest` call may run for up to its
-50-second budget and hold its slot that long.
+has not been observed yet: on 2026-10-18 two calls aborted 1.5 s in ran on to their answers. So an
+abandoned `check_sbom` or `scan_manifest` call may run for up to its 50-second budget and hold its
+slot that long, and a retry of it waits for that slot (above) instead of being refused at once.

package/docs/structured-results.md

@@ -10,7 +10,12 @@ Every field comes from what the API sends; where the API does not say, the field
 a note says so. Per tool:
 
 - `cve_summary` is `measured`, and its `measured_at` is `summary.last_updated`, the newest
-  modification time among the active CVE records it counts.
+  modification time among the active CVE records it counts. Its `freshness.nvd_poll` is the
+  fleet's last completed NVD poll, from the answer's `nvd_poll` block: `last_run_at` is
+  `nvd_poll.last_completed_at` as sent, with `scope` `fleet` and the poll's `interval`. It is
+  relayed only as a real RFC 3339 time at most 5 minutes after this server's clock. `freshness` is
+  `null` where the answer carries no `nvd_poll` (an older API, or the API could not read that time)
+  or one without such a time, and the note says which.
 - `search_cves` is `measured`, with `measured_at` `null`: each record carries its own times. Its
   `coverage` repeats the list's `total`, `total_counted`, `total_is_lower_bound`,
   `search_relaxed`, `limit` and `offset`, and adds `returned`, the rows in the page. When
@@ -39,5 +44,12 @@ a note says so. Per tool:
   then `lookup` (`cpe` or `registry`), `match_layer`, `count`, `capped`, `candidates_capped`,
   `excluded_count`, `undetermined_count`, `not_affected_count` and `degraded`.
 
-The CVE feed tools' `freshness` is `null`: the feed's answers carry no time at which its
-pollers last completed a poll for the feed as a whole.
+`search_cves`' and `get_cve`'s `freshness` is `null`: their answers carry no poll-completion
+time. The fleet's last completed NVD poll is `cve_summary`'s `freshness`, as above.
+
+Arguments that break a tool's `inputSchema` (a number outside its range, a value outside its
+`enum`, the wrong JSON type, a required argument left out) are refused before any request is
+made, with the same envelope as every other refusal: `state` `invalid_input`, `error.kind`
+`invalid_input`, `isError` true, and notes that name each argument and the rule it broke (by its
+JSON type, never by a value sent). Through 3.0.2 the MCP SDK answered those itself, with one
+`Input validation error` text block and no `structuredContent` (#3015).

package/docs/tools.md

@@ -2,7 +2,8 @@
 
 Part of the [README](../README.md), whose Tools table says what each tool answers. This page says,
 field by field, how `cve_summary`, `get_cve`, `search_cves`, `cve_exposure` and `check_affected`
-read the API's answer; `exposure_radar` has [a page of its own](exposure-radar.md). It is kept out
+read the API's answer, and how `check_sbom` and `scan_manifest` cut their rows past the
+structured result's budget; `exposure_radar` has [a page of its own](exposure-radar.md). It is kept out
 of the README because npm keeps only the first 65,536 characters of a package's README, and the
 package ships it in `docs/`. Exposure counts are derived from Shodan data. Shodan data is owned by
 Shodan, which holds its copyright (© Shodan).
@@ -34,6 +35,15 @@ outputSchema describes is left out and named in the note, and a `poller` that is
 object nor null is left out whole; `summary` is relayed either way, so a change to that diagnostic
 block never withholds the counts.
 
+`nvd_poll` is when the fleet of API instances last completed an NVD poll: `last_completed_at` (the
+end of the last window fetched and stored without an error), with `scope` `fleet` and the poll's
+`interval`. The API leaves it out when that time is unknown, and never puts the answering
+instance's counters in its place. It is the result's `freshness` (`freshness.nvd_poll`, its time as
+`last_run_at`) where `last_completed_at` is a real RFC 3339 time at most 5 minutes after this
+server's clock and `scope` is `fleet`. Otherwise `freshness` is `null`, and the note says whether
+the answer carries no `nvd_poll` or one without such a time. `poller.last_poll_at` is never the
+feed's freshness.
+
 The tool relays the API's JSON as it was sent, less a `poller` field left out as above. When
 `summary.none`, `summary.nvd_none` or `summary.rejected` is above zero, the note says what it
 counts, with the number from the answer.
@@ -133,9 +143,14 @@ affected, by one of two lookup paths:
   criteria name that product with a version range that includes the version. It matches the
   token across vendors, so each match carries `cpe_vendor` and `vendor_unknown`: a match with
   `vendor_unknown` true is real, but its vendor is not verified to be yours.
-- **Registry path** — `ecosystem` (`npm`, `PyPI`, `Maven`, …), `package` and `version`. Each OSV
-  advisory record EchelonGraph holds for the package is decided against the version as
-  affected (a match), not affected (`not_affected_count`) or undetermined.
+- **Registry path** — `ecosystem` (`npm`, `PyPI`, `Maven`, …), `package` and `version`. Each CVE
+  named by the OSV advisory records EchelonGraph holds for the package is decided against the
+  version once, as affected (one match), not affected (`not_affected_count`) or undetermined
+  (`undetermined_count`). When OSV publishes one CVE for the package in several records (a GHSA
+  and a package repository's own advisory, say), EchelonGraph stores a row for each and decides
+  them together, so the two counts count CVEs, while `advisories_considered` counts the stored
+  rows: a CVE stored as two rows and cleared counts 2 in `advisories_considered` and 1 in
+  `not_affected_count`.
 
 Read `assessed` before `count`. `assessed` false means the lookup did not evaluate the
 component, and `not_assessed_reason` says why: `product_not_in_cpe_corpus`,
@@ -156,8 +171,19 @@ holding interval's fixed bound, moved past any overlapping interval that still h
 and `fixed_in_detail` then names the intervals it moved past (#3074). `fixed_in` is always above
 the version asked about. It is null where no such version is recorded (the walk reaches an
 interval that ends at `last_affected`, or has no end, with none beyond it) or no interval holds
-the version, and `fixed_in_reason` then says which: a null is not a finding that no fix exists. A CPE
-match carries no `fixed_in`, since the end of a CPE version range is not a fix. `check_sbom` and
+the version, and `fixed_in_reason` then says which: a null is not a finding that no fix exists. When
+a CVE is stored as several records (#3137), `fixed_in` is walked over the records that store
+intervals. A record of the same CVE that stores none withholds it only when that record's versions
+or recorded fix may hold it affected. A record that cannot decide it (no version data, a git commit
+range, or one recorded fix that `fixed_in` is at or past) does not, so the same lookup at
+`fixed_in` itself can come back undetermined rather than not affected. A CPE
+match carries no `fixed_in`, since the end of a CPE version range is not a fix. Once
+EchelonGraph's API serves it, a CPE match carries that end in its own field, as NVD states it,
+`cpe_version_end_excluding` (the first version the matched range no longer holds) or
+`cpe_version_end_including` (the last one it holds), absent where the range sets no end. Only the
+first cut level of the text and the first thinned level of `data` keep them, so a CPE answer cut
+past those levels, as typical ones are, carries them only with `full: true`. Another range of the
+same CVE, or a vendor backport, can sit past it, so it is never given as a fixed version. `check_sbom` and
 `scan_manifest` relay the same fields (`interval`, `fixed_in`, `fixed_in_reason` and
 `fixed_in_detail`) on each match.
 
@@ -165,3 +191,110 @@ match carries no `fixed_in`, since the end of a CPE version range is not a fix.
 `X-EG-Ecosystem` and `X-EG-Package` request headers, never in the URL, so request logs and
 trace spans that record URLs do not hold what was looked up. The endpoint reads a CPE vendor
 from the URL only, so this tool takes none.
+
+## The client cut
+
+The server instructions and every tool description are held to 2,048 characters
+(`CLIENT_DESCRIPTION_CUT`, `src/requiredText.ts`), and the sentences a client must not lose sit in
+the first 2,048 characters of each (`REQUIRED_IN_HEAD`). 2,048 is the shortest cut a client is
+known to make:
+
+- Claude Code from v2.1.280 sends the model at most `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH`
+  characters of each description and of the instructions. Its documented default was 2,048 when
+  this budget was set (read 2026-10-05). On 2026-10-18 its documentation gives 4,096, and 16,384
+  for a tool it loads through tool search, and v2.1.302's debug log shows a 4,096 cut ("Tool
+  "exposure_radar" description truncated from 11807 to 4096 chars", from 2.6.8's 11,807-character
+  description). Builds between v2.1.280 and that change still cut at 2,048.
+- Cursor cuts tool descriptions at 6,500 characters. VS Code and Claude Desktop document no cap.
+
+Text that fits 2,048 therefore reaches each of them whole. The tests hold every served text to it
+over stdio (`test/tools.test.mjs`) and over the hosted endpoint (`test/http.test.mjs`), and the
+synthetic writes an `mcp text cut` line per transport and era that an alert reads.
+
+## How `check_sbom` and `scan_manifest` cut their rows
+
+Past 30,000 characters of structured result, and without `full: true`, `check_sbom` and
+`scan_manifest` cut `data` in this order (the note's `DATA CUT` sentences say where each answer
+stopped):
+
+1. `scan_manifest`'s `not_checked`, then `not_sent_purls`, which is kept whole or not at all (the
+   note gives the positions of the purls not sent, so a second call can send them).
+2. Every row is thinned, every row kept: each keeps `index`, `purl`, `verdict`,
+   `not_assessed_reason`, `cve_ids`, `matched_package` and `matched_via` (and an upstream row's
+   `matched_version_from` and `purl_name`), and each match `cve_id`, `kev_listed`, `ransomware`,
+   `epss_score`, `effective_score`, `score_assessed`, `fixed_in` and `fixed_in_reason`: every field
+   a prompt reads from a match.
+3. Before any other row's matches are cut, the `not_affected` and `not_assessed` rows are cut to
+   `index`, `purl`, `verdict`, `not_assessed_reason` and `cve_ids`, and leave, the `not_affected`
+   ones first, as many as must for every other row to keep all its matches. `data.summary` counts
+   every verdict, and the note says how many left (#3269).
+4. Where the other rows' matches must be capped even with all of those rows gone, those rows stay
+   instead, cut so, while every other row fits at its floor: its matches used in ransomware or
+   KEV-listed, and 10 more (#3269's review). Each row's matches are capped at one number, the most
+   that fit, never under 10, and a row whose floor is above that number keeps its floor. A row
+   with more keeps the matches chosen used in ransomware first, then its other KEV-listed ones,
+   then those of highest `effective_score`, listed in the API's order, and carries
+   `matches_truncated`: its total, the number returned, and the KEV-listed and ransomware CVE IDs
+   and `fixed_in` versions of all its matches (#3270). Only where even the floor does not fit with
+   every one of those rows do they leave, as many as must for it to.
+5. Each match is cut to the fields of step 2 less `fixed_in_reason`, still capped as step 4 says:
+   every level that keeps matches keeps every field `workload_triage` ranks by. A null `fixed_in`
+   there without its `fixed_in_reason` is a reason cut for size, and `sbom_review` never calls it
+   no fix: it checks the purl again with `full: true`, or reads the fix from `cve_remediation` or
+   `get_cve`. Kept here, the reason cost the 201-purl probe a row (43 to 42).
+6. Where even that does not fit with all of those rows gone, no row's matches are cut below its
+   floor (#3269's second review): the other rows leave instead, whole, at step 5's level and
+   their floor. The rows kept are chosen those with a KEV-listed or ransomware match first, then
+   the others, each in input order, each one that fits beside those chosen before it, so a row
+   too large to fit beside them leaves and the rows after it can stay. The note names the
+   `affected` and `undetermined` rows that left by `index`, those with a KEV-listed or ransomware
+   match first and apart from the others (the first 100 indices or runs of them in all), and
+   `check_sbom`'s note says how to check them again (#3269's third review): "Re-check these K
+   purls in this order, in calls of 7, 5, 8, 8 and 16, then of at most 17: each such call keeps
+   every row in data." Each of the first five sizes is the most of the rows left, in that order,
+   that the cut's own measure counts as fitting at their floor with `FIRST_FIT_SLACK` (600
+   characters) held back, so a lower bound: a real call of them often keeps more. The last is the
+   most such that any that many of the rest in a row count so. Each is counted for those rows, as
+   the cut would cut such a call, with this call's note longer by what such a call's note names of
+   them (its affected components). A call of fewer of them in a row keeps every row too. A row whose floor alone is
+   past the budget goes in a call of its own. Where not even one row fits at its floor (one row
+   whose KEV-listed matches alone are past the budget), the row chosen first stays alone with the
+   most of its matches that fit, chosen as in step 4, and the note says so; where not one match
+   fits beside it, with none.
+7. Only where no row but the `not_affected` and `not_assessed` ones has a match is each row cut
+   further, to `index`, `purl`, `verdict`, `not_assessed_reason` and `cve_ids`, before rows leave.
+
+Once the cut is settled, the rows kept take back detail in input order while room is left, and
+then the rows steps 3 and 4 sent out come back, cut as step 3 says, as many as the room left
+holds, where every other row stayed.
+
+When rows leave `data`, the note names a page size N: "A call of the first N of these purls, or
+of fewer, keeps every row in data; a call of other purls says in its own note what it leaves
+out." (`scan_manifest`: a call whose files hold the first N of these purls.) N is counted for this
+answer's own rows, as the cut above would cut a call of them, so it can be larger or smaller than
+the number of rows this answer keeps; it is not a page size for the rest of the purls, whose rows
+can be larger: round 2's "To read every row in data, check N or fewer purls per call" read as
+one, and calls of the purls in chunks of N lost rows in 55% of such mixes (#3269's second review).
+Nor is it a size for checking the rows left out again, which are the heavy ones: calls of N of
+them dropped 504 of 2,540 rows on realistic Debian images (#3269's third review); the re-check
+sentence of step 6 gives those sizes. `workload_triage` (its step 6) and `sbom_review` (its step
+1) check again the `affected` and `undetermined` rows the note names, those with a KEV-listed or
+ransomware match first, in calls of the sizes that sentence gives, at most 5 calls, and report the
+rest as unchecked; `workload_triage` takes its counts from `data.summary`, which counts every row
+whatever the cut. `scan_manifest` names its rows left out the same way and gives no re-check sizes:
+its rows are checked again through `check_sbom`, by purls its note does not give.
+
+The first text block, past its own 30,000 characters, keeps the same priority: before any row is
+cut to `index`, `purl`, `verdict`, `not_assessed_reason` and `cve_ids`, the `not_affected` and
+`not_assessed` rows are cut to that and leave the text, as many as must, so an affected row keeps
+its matches while room allows; only where that cannot fit is every row cut so, and then rows
+leave, those two kinds first, and the rows with a KEV-listed or ransomware match last, as `data`
+keeps them (#3284: through 3.1.0's review the text left the rest from the end in input order, so a
+KEV-bearing row `data` kept could leave the text unnamed; on 36 realistic Debian 12 images a client
+reading the text alone missed 95 of 413 such rows). The note names by `index` each of those that
+still leaves ("Of the rows left out of it, 30 have a KEV-listed or ransomware match: at index 511
+to 513, …"). The note says what those rows leave out, and that each string in
+them keeps its first 100 characters where one is longer. The text names no page size (through
+#3269's review it said "check N or fewer purls per call", N the rows it kept, and a call of the
+first N purls kept fewer in 34 of 89 mixes); its note says how many rows it leaves out, of which
+kinds, and that `structuredContent.data` holds them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "echelongraph-mcp",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "mcpName": "io.echelongraph/echelongraph-mcp",
   "description": "MCP server for CVE lookups: EchelonGraph scores, CISA KEV, EPSS, CWE, exploits, version and SBOM checks, vendor advisories, and per-CVE exposure derived from Shodan data. Shodan data is owned by Shodan, which holds its copyright (© Shodan). Keyless.",
   "type": "module",

package/server.json

@@ -17,7 +17,7 @@
       ]
     }
   ],
-  "version": "3.0.2",
+  "version": "3.1.0",
   "remotes": [
     {
       "type": "streamable-http",
@@ -28,7 +28,7 @@
     {
       "registryType": "npm",
       "identifier": "echelongraph-mcp",
-      "version": "3.0.2",
+      "version": "3.1.0",
       "transport": {
         "type": "stdio"
       },