echelongraph-mcp 2.6.2 → 2.6.5

package/dist/prompts.js

@@ -2,6 +2,16 @@ import * as z from "zod";
 import { MAX_COMPONENTS, MAX_PURLS, MAX_SBOM_CHARS } from "./tools/check_sbom.js";
 export const KEV_BRIEF_DEFAULT_DAYS = 7;
 export const KEV_BRIEF_MAX_DAYS = 365;
+// The page the brief reads kev_recent in (#2799). The brief puts kev_vuln_name and kev_due_date on
+// every line, and a model whose client passes only `content` reads them from the first text block,
+// which past 30,000 characters keeps fewer fields a row (src/tools/kev_recent.ts kevText). Through
+// 2.6.3 the brief asked for limit 200: on 2026-10-04 the hosted endpoint's text for 365 days at 200
+// (306 matching) kept cve_id, kev_added_date, kev_vendor, kev_product and kev_ransomware a row, and
+// neither field. A page of 50, kev_recent's default, is sent whole (27,514 characters of production's
+// 50 newest), and its first cut level, which keeps both, fits 85 production-shaped rows in the
+// budget, so at 50 rows three quarters longer than production's still keep them.
+// test/prompt-fields.test.mjs runs the brief's call at this limit.
+export const KEV_BRIEF_LIMIT = 50;
 // The envelope rules every prompt carries, word for word.
 export const ENVELOPE_RULES = [
     "Before you use any figure, read that result's evidence envelope: its structuredContent (where your client shows text blocks alone, the last text block) carries state, measured_at, method, coverage, freshness and notes.",
@@ -14,22 +24,36 @@ export const ENVELOPE_RULES = [
     "Do not add facts the results do not carry: where a result says nothing about a point, write that it does not say.",
 ].join(" ");
 const text = (t) => ({ messages: [{ role: "user", content: { type: "text", text: t } }] });
+// triage_cve reads kev_due_date from get_cve's record (#2799 review). Through 2.6.3 its step 6 read
+// it from kev_recent with since and until set to the CVE's kev_added_date, with no limit and no
+// paging, so on a day CISA added more than a page the CVE's row could be on no page it read: on the
+// hosted endpoint (2.6.3, 2026-10-04) that call for 2021-11-03 answered total 287, 50 rows from
+// CVE-2010-5326 to CVE-2019-0797 and has_more true, without CVE-2021-40444, added that day; get_cve
+// for CVE-2021-40444 carried kev_due_date 2021-11-17T00:00:00Z in its first text block. The record
+// carries kev_due_date wherever CISA gives one (core-backend cve/store.go, omitempty), and get_cve's
+// first text block keeps every field of it.
+//
+// Its Patch line (#2817): cve_intel's fixed_version is one value per (CVE, ecosystem, package), the
+// advisory's last range's (core-backend cve/advisory.go UpsertAffectedPackages), and triage_cve has
+// no installed version to hold it against: for CVE-2021-44228 production's cve_intel gives
+// log4j-core 2.12.2 (2026-10-04, 2.6.3), below an affected 2.14.1. So the line gives it as
+// what cve_intel records for the package, never as the fix for every affected branch, and sends
+// the reader to get_cve's references tagged Vendor Advisory or Patch for a branch's fix.
 export function triageCveText(cve) {
     return [
         `Triage ${cve} using the EchelonGraph MCP tools. Call them in this order, each with cve_id ${cve}:`,
-        "1. get_cve: the record. Read score_assessed before echelongraph_score (false: not yet scored, which is not a score of 0); read severity, cvss_v3_score, epss_score and epss_percentile, and the CISA-KEV fields kev_listed, kev_added_date and kev_ransomware.",
+        "1. get_cve: the record. Read score_assessed before echelongraph_score (false: not yet scored, which is not a score of 0); read severity, cvss_v3_score, epss_score and epss_percentile, and the CISA-KEV fields kev_listed, kev_added_date, kev_due_date and kev_ransomware.",
         "2. cve_intel: weaknesses (cwes), public exploit code (exploits and exploits_total; verified_status is the label stored with each reference, not a guarantee that it works, and an empty list is not evidence that no exploit exists), affected_packages and fixed_versions.",
         "3. vendor_advisories_for_cve: the vendor advisories that name it. Call get_vendor_advisory for one whose remediation you need in full.",
         "4. epss_history: how its EPSS score changed, one point per recorded change (series_kind change_only): before series_starts_at a missing point means not recorded, not unchanged.",
         "5. cve_exposure: internet exposure on record. exposure_state says what the count is; exposed_hosts counts distinct ip:port services, not machines; the result is not_assessed with measured_at null, so present any count as undated and on record, and exposure_state not_assessed as not assessed.",
-        `6. If get_cve says kev_listed is true: kev_recent with since and until both set to the date part (YYYY-MM-DD) of its kev_added_date (for 2024-04-12T00:00:00Z, 2024-04-12), to read kev_due_date from the row for ${cve}.`,
         ENVELOPE_RULES,
         "Then answer with this template, one line each, naming the tool and the measured_at behind every line:",
         "- Exploited? CISA-KEV listing and its date, known ransomware use, and public exploit code on record.",
         "- Likelihood: EPSS score and percentile, and how it has moved.",
         "- Reachable? exposure_state and the count on record, or not assessed.",
-        '- Patch: fixed versions and vendor advisories; where the results hold none, write "none on record", which is not a finding that no fix exists.',
-        "- Deadline: kev_due_date when the CVE is KEV-listed (CISA's due date for US federal civilian agencies); otherwise write that the results give no CISA deadline.",
+        `- Patch: fixed versions and vendor advisories; where the results hold none, write "none on record", which is not a finding that no fix exists. cve_intel keeps one fixed_version per ecosystem and package, its advisory's last range's, which need not be the fix for every affected version of the package: give each as the fixed version cve_intel records for that package, never as the fix for every affected branch or the version every install should move to, and for the fix on a given branch point to get_cve's references tagged Vendor Advisory or Patch, where it has them, and to the vendor advisories.`,
+        "- Deadline: get_cve's kev_due_date when the CVE is KEV-listed (CISA's due date for US federal civilian agencies); otherwise write that the results give no CISA deadline.",
         "- Decision: patch now, schedule, or monitor, with a one-line reason drawn from the lines above.",
     ].join("\n");
 }
@@ -37,7 +61,7 @@ export function kevWeeklyBriefText(days) {
     return [
         `Write a brief of the CVEs CISA added to its Known Exploited Vulnerabilities (KEV) catalog in the last ${days} days, using the EchelonGraph MCP tools.`,
         `1. Compute since: today's date in UTC minus ${days} days, as YYYY-MM-DD. State the since date you used, and today's date.`,
-        "2. Call kev_recent with since set to that date and limit 200. While its coverage.has_more is true, call kev_recent again with the same since and cursor set to the previous answer's next_cursor.",
+        `2. Call kev_recent with since set to that date and limit ${KEV_BRIEF_LIMIT}. While its coverage.has_more is true, call kev_recent again with the same since and limit and cursor set to the previous answer's next_cursor.`,
         ENVELOPE_RULES,
         "Then write the brief:",
         "- Header: the date range, the number of CVEs added (total), and measured_at, EchelonGraph's last successful fetch of CISA's feed, with catalog_version.",
@@ -61,15 +85,41 @@ export function amIAffectedText(a) {
         "Where capped, candidates_capped or degraded is true, say the list may be incomplete and why.",
     ].join("\n");
 }
+// sbom_review (#2799). The purls a call did not send: data.not_sent_purls lists them, and where the
+// first text block cuts that list to its first entries (check_sbom's TEXT CUT says so), the model
+// rebuilds them from the document, from the position check_sbom's note gives, in the order it
+// gives (check_sbom.ts READ_ORDER).
+//
+// Fixed versions (#2799 review, #2817). cve_intel's fixed_version is one value per (CVE, ecosystem,
+// package), the advisory's last range's (core-backend cve/advisory.go UpsertAffectedPackages), so
+// it need not be the fix for the installed version's branch: for CVE-2021-44228, production's
+// cve_intel gives log4j-core 2.12.2 (2026-10-04, 2.6.3), older than an installed 2.14.1, and
+// check_sbom's matches for 2.14.1 say it "is listed verbatim in the advisory's affected versions",
+// which names no fix. So a fixed version is given only where it is strictly greater than the
+// installed version, and otherwise the line says the results give none for the component's branch
+// and points to the advisory. The advisory interval in a match's match_reason, "[A, B)" (core-backend
+// cve/pkgmatch.go evaluateRegistryRow), is preferred where the text keeps it (its first cut level;
+// a Juice Shop SBOM of 50 components is cut past it); B is the interval's fixed bound, or its
+// last_affected one, which the text does not tell apart, so B is given as the interval's end.
+// A cut text keeps index, purl, verdict, not_assessed_reason and cve_ids on a row, not its
+// ecosystem, package or version, so the model reads those from the purl, as core-backend's
+// matcher does (cve/matchbatch.go purlNameVersion, shared/pkg/purlosv): step 2 lists every type
+// purlosv maps (its unversioned table, and deb, apk, alpine and rpm by the distro qualifier, of
+// the three kinds osvDistro reads, Alpine cut to major.minor and Debian to its major), the types
+// purlNameVersion names with their namespace, and says any other is unknown, with no fixed version.
+// test/prompt-fields.test.mjs fromPurl holds the same tables.
 export function sbomReviewText(sbom) {
     return [
         "Review the SBOM below for known vulnerabilities, using the EchelonGraph MCP tools.",
-        `1. Call check_sbom with sbom set to the document below, as given. It reads the document's purls and checks up to ${MAX_PURLS} distinct purls per call, sending them in batches of ${MAX_COMPONENTS}; a document with more is refused, not truncated. If it is refused, say why from the result and do not guess at the components. If coverage.not_sent is above 0, the API's rate limit or the call's time budget stopped it early: say how many purls were not sent and coverage.not_sent_reason, list them as not checked (never as clean), and call check_sbom again with purls set to data.not_sent_purls once, after a minute, merging what it returns.`,
-        "2. For each distinct cve_id on a component whose verdict is affected, call get_cve, to read kev_listed, epss_score, score_assessed, echelongraph_score and cvss_v3_score. If there are more than 30 distinct CVEs, do this for 30 of them and list the rest as not looked up, unranked.",
+        `1. Call check_sbom with sbom set to the document below, as given. It reads the document's purls and checks up to ${MAX_PURLS} distinct purls per call, sending them in batches of ${MAX_COMPONENTS}; a document with more is refused, not truncated. If it is refused, say why from the result and do not guess at the components. If coverage.not_sent is above 0, the API's rate limit or the call's time budget stopped it early: say how many purls were not sent and coverage.not_sent_reason, and that they are not checked (never clean). After a minute, call check_sbom once more with purls set to the purls not sent, and merge what it returns. data.not_sent_purls lists them; where the note says the first text block cuts not_sent_purls to its first entries, rebuild the list from the document instead, as the note says: the document's distinct purls from the position the note gives on, counted in the order it gives.`,
+        "2. Read each component's ecosystem, package and version from its purl, which every row of data.results in the text carries (the leanest cut of the text leaves out the row's own ecosystem, package and version), as check_sbom maps them. A purl is pkg:type/namespace/name@version?qualifiers, each part percent-decoded (%40 is @), its type and distro qualifier in any case. The version is what follows the last @, up to any ? or #. The ecosystem follows from the type: npm is npm, pypi PyPI, maven Maven, golang Go, cargo crates.io, gem RubyGems, nuget NuGet, composer Packagist, hex Hex, pub Pub, swift SwiftURL, hackage Hackage, cran CRAN, bitnami Bitnami, conan ConanCenter and githubact GitHub Actions. For deb, apk, alpine and rpm it is the release the distro qualifier names, which must be one of these three kinds: distro=debian-N is Debian:N, the major release alone (debian-12 and debian-12.5 are Debian:12); distro=ubuntu-V is Ubuntu:V as given (ubuntu-22.04 is Ubuntu:22.04); distro=alpine-X.Y is Alpine:vX.Y, cut to major.minor (alpine-3.20 and alpine-3.20.10 are Alpine:v3.20; alpine-3 names none). For any other type, and a deb, apk, alpine or rpm purl without such a qualifier, the ecosystem is unknown: check_sbom does not check the component (not_assessed, never clean), and the fix list gives no version for it. The package is namespace:name for maven (pkg:maven/org.apache.logging.log4j/log4j-core@2.14.1 is the package org.apache.logging.log4j:log4j-core in Maven, at version 2.14.1), namespace/name for npm, golang, composer, swift and githubact, and the name alone for every other type (pkg:deb/debian/openssl@3.0.15-1~deb12u1?distro=debian-12 is openssl in Debian:12).",
+        "3. For each distinct cve_id on a component whose verdict is affected, call get_cve, to read kev_listed, epss_score, score_assessed, echelongraph_score and cvss_v3_score, and cve_intel, to read fixed_version from its affected_packages and fixed_versions rows for the component's ecosystem and package (package_name). If there are more than 30 distinct CVEs, do this for 30 of them and list the rest as not looked up, unranked.",
         ENVELOPE_RULES,
         "Read each component's verdict: not_affected is the one clean verdict; undetermined and not_assessed are not clean, and not_assessed_reason says why (for example distro_release_unknown: a deb, apk or rpm purl without a distro qualifier, which EchelonGraph does not guess).",
         "Then write a prioritised fix list of the affected components. State the ordering keys, in this order: 1. CISA-KEV listed (kev_listed true) first; 2. then EPSS score, highest first; 3. then echelongraph_score where score_assessed is true, else cvss_v3_score, highest first. A CVE with no value for a key sorts after those with one, and its line says which key was missing.",
-        "For each line give the component (purl), its cve_ids, the key values used, and fixed versions where a result gives them. After the list, give data.summary's counts, and list the undetermined and not_assessed components with their reasons as not checked, never as clean.",
+        "For each line give the component (purl), its cve_ids, the key values used, and for each CVE a fixed version where the results support one, by this rule. Never give a fixed version that is not strictly greater than the component's installed version (the version in its purl), compared in the ecosystem's version order: release numbers part by part, as numbers, not as text (2.9.1 is below 2.12.2, and 2.12.2 is below 2.14.1); where you are not sure of the order (pre-releases, qualifiers and distro revisions have their own rules), say so and do not give it. Prefer the match's match_reason where the text keeps it: \"falls inside the advisory interval [A, B)\" says the advisory's range that holds the installed version ends at B, which match_reason does not say is a fixed version rather than the range's last affected version, so give B as the end of that interval, quoting it (∞: the range has no end on record). Otherwise give cve_intel's fixed_version for the component's ecosystem and package (or the recorded fix a match_reason names, the same value): cve_intel keeps one fixed_version per package, its advisory's last range's, which need not be the fix on the component's branch, so say so beside it. Where no version meets the rule (\"listed verbatim in the advisory's affected versions\" names none), write that the results give no fixed version for the component's branch, which is not a finding that no fix exists, and point to the CVE's advisory for it: get_cve's references tagged Vendor Advisory or Patch, where it has them.",
+        "After the list, give data.summary's counts, and list the undetermined and not_assessed components with their reasons as not checked, never as clean.",
+        "Where the note says that rows of data.results are left out of the first text block, list the components its rows carry, say how many affected components the text leaves out (data.summary.affected, less those listed), and give the undetermined and not_assessed components it leaves out as data.summary's counts, by not_assessed_reason, as not checked, never as clean.",
         "",
         "SBOM:",
         "```json",
@@ -80,7 +130,7 @@ export function sbomReviewText(sbom) {
 export function registerPrompts(server, kit) {
     server.registerPrompt("triage_cve", {
         title: "Triage a CVE",
-        description: "Triage one CVE: get_cve, cve_intel, vendor_advisories_for_cve, epss_history and cve_exposure (and kev_recent for the due date when the CVE is KEV-listed), then a decision template: exploited, likelihood, reachable, patch, deadline. Each line cites its tool and measured_at, and not_assessed is never reported as clean.",
+        description: "Triage one CVE: get_cve (with CISA's due date when the CVE is KEV-listed), cve_intel, vendor_advisories_for_cve, epss_history and cve_exposure, then a decision template: exploited, likelihood, reachable, patch, deadline. Each line cites its tool and measured_at, and not_assessed is never reported as clean.",
         argsSchema: z.object({
             cve_id: z
                 .string()
@@ -125,7 +175,7 @@ export function registerPrompts(server, kit) {
     }, (a) => text(amIAffectedText(a)));
     server.registerPrompt("sbom_review", {
         title: "SBOM review",
-        description: `Review an SBOM (CycloneDX JSON or SPDX JSON text, up to ${MAX_SBOM_CHARS} characters): it is passed to check_sbom, which checks up to ${MAX_PURLS} distinct purls per call in batches of ${MAX_COMPONENTS}, then get_cve for each affected CVE, and a prioritised fix list ordered by CISA-KEV listing, then EPSS, then score, each key stated. undetermined and not_assessed components are listed as not checked, never as clean.`,
+        description: `Review an SBOM (CycloneDX JSON or SPDX JSON text, up to ${MAX_SBOM_CHARS} characters): it is passed to check_sbom, which checks up to ${MAX_PURLS} distinct purls per call in batches of ${MAX_COMPONENTS}, then get_cve and cve_intel for each affected CVE, and a prioritised fix list ordered by CISA-KEV listing, then EPSS, then score, each key stated. undetermined and not_assessed components are listed as not checked, never as clean.`,
         argsSchema: z.object({
             sbom: z
                 .string()

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,6 +25,8 @@ 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. The resource ${CVE_TEMPLATE} cuts its data the same way, and its notes say so (DATA CUT).
+
 ## Envelope fields
 
 | Field | What it holds |
@@ -32,7 +37,7 @@ Every tool result carries an evidence envelope in its structuredContent, and rep
 | 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
@@ -68,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" } })]);
@@ -78,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] : []),
                 ],
             });
         }
@@ -119,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",
@@ -127,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;
@@ -148,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

@@ -0,0 +1,254 @@
+// The text budget (#2783): what a success's first text block may cost, and how an answer larger
+// than that is cut. index.ts's `succeeded` builds every success's first text block with dataText;
+// a tool that returns a list of rows names it with a TextCut. structuredContent.data is never cut.
+// A module of its own, so a tool module can import its types and TEXT_BUDGET_DESCRIPTION without
+// importing index.ts, which starts the stdio server when loaded.
+//
+// What a success costs in the channel a model reads is mostly its first text block, and through
+// 2.6.2 that block was the API's JSON pretty-printed, whatever its size. Measured on production
+// through https://mcp.echelongraph.io/mcp (2.6.2, 2026-10-04): search_cves {search: "openssl"} at
+// its default limit was 133,300 characters of text, get_cve CVE-2021-44228 80,897, check_affected
+// openssl 3.0.0 156,058 and linux_kernel 5.10.0 364,408, kev_recent at limit 200 105,925 and
+// search_vendor_advisories "log4j" at limit 50 103,147, against #2467's ceiling of 60,000
+// (mcp-server/test/text-bound.mjs). Claude Code warns past 10,000 tokens of tool output and past
+// 25,000 saves the result to a file and hands the model its path instead; Anthropic's guidance to
+// tool authors ("Writing effective tools for agents") is pagination, filtering and truncation with
+// sensible defaults, steering the agent when a response is cut. The MCP spec (2025-06-18 and
+// 2025-11-25, Tools, Structured Content) asks a tool that returns structuredContent to return it
+// serialized in a text block too, as a SHOULD, for backwards compatibility, and SEP-1624 proposes
+// content as the model-facing, token-efficient form and structuredContent as the machine-facing one.
+//
+// So structuredContent.data is always the API's JSON whole, and the first text block is that JSON
+// when it fits DATA_TEXT_BUDGET, half the ceiling, and cut when it does not:
+//   1. pretty-printed, as since 1.x, when that fits;
+//   2. else the same JSON with each element of a list on a line of its own, which parses to the
+//      same value, when that fits;
+//   3. else, for a tool that names its list of rows (TextCut), each row cut as the tool's first
+//      level says (the fields it keeps, every string in it to its first `clip` characters, ending
+//      in "…", every list in it to its first `cap` entries); then, for a tool that names the
+//      lists beside its rows (`sides`: check_affected's excluded sample, check_sbom's
+//      not_sent_purls), the same level with those lists cut as it says; then each next level with
+//      them cut; and when no level fits, rows are left out of the text, those the tool names
+//      first, then from the end. A list beside the rows is cut before any row field the first
+//      level keeps, and before any row leaves the text;
+//   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, 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,
+// when, does, have, on and the rest of its PROSE list), so no reviewed entry goes stale.
+export const TEXT_BUDGET_DESCRIPTION = "Past 30,000 characters of JSON, the first text block holds data cut to fit, and the note says what the cut leaves out and where to read it (TEXT CUT); data in the structured result always holds it whole.";
+const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const field = (o, k) => (isPlainObject(o) ? o[k] : undefined);
+const listed = (xs) => (xs.length < 2 ? xs.join("") : `${xs.slice(0, -1).join(", ")} and ${xs[xs.length - 1]}`);
+// The JSON with each element of a list of objects, at the top or one level down, on a line of its
+// own: the same value as JSON.stringify(data), without the indentation of every nested key.
+function lined(v) {
+    const entry = (x) => Array.isArray(x) && x.some((e) => e !== null && typeof e === "object") ? `[\n${x.map((e) => `    ${JSON.stringify(e)}`).join(",\n")}\n  ]` : JSON.stringify(x);
+    return `{\n${Object.entries(v)
+        .map(([k, x]) => `  ${JSON.stringify(k)}: ${entry(x)}`)
+        .join(",\n")}\n}`;
+}
+// A string's first n characters and "…", never splitting a surrogate pair.
+const clipString = (s, n) => {
+    const end = n > 0 && /[\uD800-\uDBFF]/.test(s[n - 1]) ? n - 1 : n;
+    return `${s.slice(0, end)}…`;
+};
+function cutValue(v, clip, cap, s) {
+    if (typeof v === "string") {
+        if (v.length <= clip)
+            return v;
+        s.clipped++;
+        return clipString(v, clip);
+    }
+    if (Array.isArray(v)) {
+        if (v.length > cap)
+            s.capped++;
+        return v.slice(0, cap).map((x) => cutValue(x, clip, cap, s));
+    }
+    if (isPlainObject(v))
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, cutValue(x, clip, cap, s)]));
+    return v;
+}
+function cutRow(row, keep, level, s, prefix = "") {
+    const wanted = new Map(keep.map((k) => (typeof k === "string" ? [k, null] : [k[0], k[1]])));
+    const cap = level.cap ?? Number.POSITIVE_INFINITY;
+    const out = {};
+    for (const [k, v] of Object.entries(row)) {
+        if (!wanted.has(k)) {
+            s.left.add(`${prefix}${k}`);
+            continue;
+        }
+        const sub = wanted.get(k);
+        if (sub && Array.isArray(v)) {
+            if (v.length > cap)
+                s.capped++;
+            out[k] = v.slice(0, cap).map((e) => (isPlainObject(e) ? cutRow(e, sub, level, s, `${prefix}${k}[].`) : cutValue(e, level.clip, cap, s)));
+        }
+        else {
+            out[k] = cutValue(v, level.clip, cap, s);
+        }
+    }
+    return out;
+}
+// Step 4: every list to its first n entries (and, with clip, every string to its first clip
+// characters), recording the longest list cut at each path.
+function capAll(v, n, clip, caps, s, path) {
+    if (Array.isArray(v)) {
+        if (v.length > n)
+            caps.set(path, Math.max(caps.get(path) ?? 0, v.length));
+        return v.slice(0, n).map((x) => capAll(x, n, clip, caps, s, `${path}[]`));
+    }
+    if (isPlainObject(v))
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, capAll(x, n, clip, caps, s, path ? `${path}.${k}` : k)]));
+    return cutValue(v, clip, Number.POSITIVE_INFINITY, s);
+}
+const CAP_LEVELS = [
+    ...[128, 64, 32, 16, 8, 4, 2, 1].map((n) => ({ n, clip: Number.POSITIVE_INFINITY })),
+    { n: 1, clip: 200 },
+    { n: 0, clip: 50 },
+];
+// The sentence for a level of a TextCut: what each row leaves out.
+function levelSaid(rows, n, level, s) {
+    const parts = [];
+    if (s.left.size)
+        parts.push(`each of the ${n} rows of ${rows} in it leaves out ${listed([...s.left])}`);
+    if (s.clipped)
+        parts.push(`every string in a row longer than ${level.clip} characters keeps its first ${level.clip}, ending in "…"`);
+    if (s.capped && level.cap !== undefined)
+        parts.push(`every list in a row longer than ${level.cap} entries keeps its first ${level.cap}`);
+    if (!parts.length)
+        return "";
+    const said = parts.join("; ");
+    return `${said[0].toUpperCase()}${said.slice(1)}.`;
+}
+// The lists beside the rows, each cut as its TextSide says, and the sentences saying how: what its
+// entries leave out, and how many of them the text keeps, then the tool's own sentence.
+function cutSides(data, sides) {
+    const fields = {};
+    const said = [];
+    for (const side of sides) {
+        const v = data[side.list];
+        if (!Array.isArray(v) || v.length === 0)
+            continue;
+        const clip = side.clip ?? Number.POSITIVE_INFINITY;
+        const cap = side.cap ?? v.length;
+        const s = { left: new Set(), clipped: 0, capped: 0 };
+        const level = { keep: side.keep ?? [], clip };
+        const kept = v.slice(0, cap).map((e) => (side.keep && isPlainObject(e) ? cutRow(e, side.keep, level, s) : cutValue(e, clip, Number.POSITIVE_INFINITY, s)));
+        fields[side.list] = kept;
+        const parts = [];
+        if (kept.length < v.length)
+            parts.push(`in it, ${side.list} keeps its first ${kept.length} of ${v.length} entries`);
+        if (s.left.size)
+            parts.push(`each entry of ${side.list} in it leaves out ${listed([...s.left])}`);
+        if (s.clipped)
+            parts.push(`every string in ${side.list} longer than ${clip} characters keeps its first ${clip}, ending in "…"`);
+        if (!parts.length)
+            continue;
+        const one = parts.join("; ");
+        said.push(`${one[0].toUpperCase()}${one.slice(1)}.`);
+        const own = side.said?.(kept.length, v.length, data);
+        if (own)
+            said.push(own);
+    }
+    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, place = FIRST_TEXT_BLOCK) {
+    const pretty = JSON.stringify(data, null, 2);
+    if (pretty.length <= DATA_TEXT_BUDGET)
+        return { text: pretty, said: "" };
+    const layout = (v) => (isPlainObject(v) ? lined(v) : JSON.stringify(v));
+    const all = layout(data);
+    if (all.length <= DATA_TEXT_BUDGET)
+        return { text: all, said: "" };
+    const head = place.opens(pretty.length);
+    const say = (...xs) => [head, ...xs].filter((x) => Boolean(x)).join(" ");
+    let base = data;
+    let rowsSaid = "";
+    let sidesSaid = [];
+    const rows = cut && isPlainObject(data) ? data[cut.rows] : undefined;
+    if (cut && isPlainObject(data) && Array.isArray(rows) && rows.length > 0 && cut.levels.length > 0) {
+        const n = rows.length;
+        // The lists beside the rows, cut once; tried with the first level after it fails with them
+        // whole, and with every later level.
+        const sides = cut.sides?.length ? cutSides(data, cut.sides) : { fields: {}, said: [] };
+        const sided = sides.said.length > 0;
+        const attempts = cut.levels.flatMap((level, i) => (i === 0 && sided ? [{ level, sided: false }, { level, sided: true }] : [{ level, sided }]));
+        let cutRows = [];
+        let beside = data;
+        for (const attempt of attempts) {
+            const { level } = attempt;
+            const s = { left: new Set(), clipped: 0, capped: 0 };
+            const cap = level.cap ?? Number.POSITIVE_INFINITY;
+            cutRows = rows.map((r) => (isPlainObject(r) ? cutRow(r, level.keep, level, s) : cutValue(r, level.clip, cap, s)));
+            rowsSaid = levelSaid(cut.rows, n, level, s);
+            beside = attempt.sided ? { ...data, ...sides.fields } : data;
+            sidesSaid = attempt.sided ? sides.said : [];
+            const shown = lined({ ...beside, [cut.rows]: cutRows });
+            if (shown.length <= DATA_TEXT_BUDGET)
+                return { text: shown, said: say(rowsSaid, ...sidesSaid, cut.whole) };
+        }
+        // No level fits: rows leave the text, those the tool names first (by value, in its order,
+        // each from the end), then the rest from the end, until it fits.
+        const lens = cutRows.map((r) => 4 + JSON.stringify(r).length);
+        const emptyLen = lined({ ...beside, [cut.rows]: [] }).length;
+        const textLen = (kept, sum) => (kept === 0 ? emptyLen : emptyLen + 2 + sum + 2 * kept);
+        const firstOut = cut.leaveOutFirst;
+        const order = [];
+        for (const value of firstOut?.values ?? []) {
+            for (let i = n - 1; i >= 0; i--)
+                if (field(rows[i], firstOut?.field ?? "") === value)
+                    order.push(i);
+        }
+        const queued = new Set(order);
+        for (let i = n - 1; i >= 0; i--)
+            if (!queued.has(i))
+                order.push(i);
+        const out = new Set();
+        let sum = lens.reduce((t, x) => t + x, 0);
+        for (const i of order) {
+            if (textLen(n - out.size, sum) <= DATA_TEXT_BUDGET)
+                break;
+            out.add(i);
+            sum -= lens[i];
+        }
+        const kept = cutRows.filter((_, i) => !out.has(i));
+        const shown = lined({ ...beside, [cut.rows]: kept });
+        if (kept.length > 0 && shown.length <= DATA_TEXT_BUDGET) {
+            const outFirst = firstOut ? [...out].filter((i) => firstOut.values.includes(String(field(rows[i], firstOut.field)))).length : 0;
+            const which = outFirst > 0
+                ? `: the ${outFirst} whose ${firstOut?.field} is ${(firstOut?.values ?? []).join(" or ")} (${firstOut?.why})${out.size > outFirst ? `, and the last ${out.size - outFirst} of the rest` : ""}`
+                : `, the last ${out.size} in order`;
+            const left = `Only ${kept.length} of the ${n} rows of ${cut.rows} are in it; the other ${out.size} are in structuredContent.data only${which}.`;
+            return { text: shown, said: say(rowsSaid, ...sidesSaid, left, cut.whole, cut.page?.(kept.length, n, data)) };
+        }
+        base = { ...beside, [cut.rows]: cutRows };
+    }
+    // Step 4: lists, then strings.
+    let last = { text: all, caps: new Map(), s: { left: new Set(), clipped: 0, capped: 0 }, n: 0, clip: 0 };
+    for (const { n, clip } of CAP_LEVELS) {
+        const caps = new Map();
+        const s = { left: new Set(), clipped: 0, capped: 0 };
+        last = { text: layout(capAll(base, n, clip, caps, s, "")), caps, s, n, clip };
+        if (last.text.length <= DATA_TEXT_BUDGET)
+            break;
+    }
+    const named = [...last.caps].slice(0, 8).map(([p, len]) => `${p || "the answer"} (${len})`);
+    const more = last.caps.size > 8 ? `, and ${last.caps.size - 8} more` : "";
+    const lists = last.caps.size ? `Every list in it keeps at most its first ${last.n} ${last.n === 1 ? "entry" : "entries"}: ${listed(named)}${more}, each named with its full length.` : "";
+    const strings = last.s.clipped ? `Every string in it longer than ${last.clip} characters keeps its first ${last.clip}, ending in "…".` : "";
+    return { text: last.text, said: say(rowsSaid, ...sidesSaid, lists, strings, cut?.whole) };
+}