echelongraph-mcp 2.3.4 → 2.5.0

package/dist/resources.js

@@ -0,0 +1,153 @@
+// MCP resources (#2722): context a client can attach.
+//
+//   echelongraph://methodology  static text: what each evidence-envelope field means, the state
+//                               values, and how each tool measures (from the README's envelope
+//                               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
+//                               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.
+//
+// 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";
+export const METHODOLOGY_URI = "echelongraph://methodology";
+export const SOURCES_URI = "echelongraph://sources";
+export const CVE_TEMPLATE = "cve://{cve_id}";
+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.
+
+## Envelope fields
+
+| Field | What it holds |
+|---|---|
+| state | measured, not_assessed, failed or invalid_input (below). |
+| measured_at | When the underlying observation was made, as the API states it. null when the answer does not say or holds no observation; never the Go zero time. |
+| method | How the numbers were produced. null on a failure. |
+| coverage | What the answer covers, where the tool can say: 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). |
+| error | On a failure: kind, path, status and message. |
+
+## state
+
+| state | What it means |
+|---|---|
+| measured | A measurement of what was asked. An exposure count is measured when the answer says when what it counts was observed and how it was produced; no exposure answer says when today, so neither exposure tool answers measured. |
+| not_assessed | The answer holds no dated measurement of what was asked, so no count in it is presented as one. It can still relay a count, as what the source holds on record, undated; the notes say what each count is. Never clean. |
+| failed | The lookup did not complete: unreachable host, non-2xx, timeout, or a body that is not a JSON object. Not a finding, never zero. |
+| invalid_input | The input was refused, by this server or by the API, so nothing was looked up. Not a finding. |
+
+A count of 0 is a finding of none when the answer measured it. Under assessed: false, or state not_assessed, it is not: report it as not assessed.
+
+## How each tool measures
+
+- cve_summary: measured; measured_at is summary.last_updated, the newest modification time among the active CVE records it counts. freshness is null: the feed serves no poll-completion time for the feed as a whole.
+- search_cves: measured, measured_at null (each record carries its own times); coverage repeats total, total_counted, total_is_lower_bound, search_relaxed, limit and offset.
+- get_cve: measured; measured_at is the record's updated_at, when EchelonGraph last wrote it. score_assessed false means not yet scored, not a score of 0.
+- cve_exposure: not_assessed with measured_at null, every answer: its last_seen is when EchelonGraph last wrote or refreshed a service's row, not an observation time. exposure_state (exposed, measured_zero, not_assessed, tracking_unknown) says what the count is; exposed_hosts counts distinct ip:port services from Shodan data, not machines, and is not an internet-wide census.
+- exposure_radar: not_assessed with measured_at null: no radar's answer gives one time at which what it counts was observed. freshness gives each radar's last_run_at where the API serves one.
+- kev_recent: measured; measured_at is EchelonGraph's last successful fetch of CISA's KEV feed; freshness carries that fetch time, catalog_version and date_released.
+- epss_history: measured_at is current.epss_updated_at, when EchelonGraph last wrote a changed EPSS value; the series is change-only, so a missing point is not recorded, not unchanged.
+- check_affected: measured when the answer says assessed true; not_assessed when it says false or does not say. measured_at and freshness are null.
+- check_sbom: measured when at least one component got a verdict, else not_assessed; measured_at null. not_affected is the one clean verdict; undetermined and not_assessed are not clean.
+- cve_intel: measured_at null: each row carries its own first_seen_at or enriched_at. An empty exploits list is not evidence that no public exploit exists.
+- get_cwe: measured_at null: each row carries its own published date. A total of 0 says no CVE in EchelonGraph's feed is classified under that CWE.
+- vendor_advisories_for_cve, search_vendor_advisories: measured_at null (each row carries vendor_published_at and our_first_seen_at). get_vendor_advisory: measured_at is our_first_seen_at, when EchelonGraph first recorded the advisory.
+
+Every figure is as fresh as the schedule that refreshes it. The resource ${SOURCES_URI} reports what the API itself says about its feeds' polling.
+`;
+const SUMMARY_PATH = "/api/v1/public/cves/summary";
+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).
+const POLLER_FIELDS = ["interval", "last_poll_at", "poll_count", "poll_errors"];
+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" } })]);
+    const nvd = { feed: "NVD CVE records (EchelonGraph's CVE feed poller)", endpoint: SUMMARY_PATH };
+    if (!summary.ok)
+        Object.assign(nvd, failure(summary));
+    else {
+        const poller = obj(obj(summary.data)?.poller);
+        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 {
+            Object.assign(nvd, {
+                state: "reported",
+                reported: pick(poller, POLLER_FIELDS),
+                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.",
+                ],
+            });
+        }
+    }
+    const cisa = { feed: "CISA Known Exploited Vulnerabilities catalog", endpoint: KEV_PATH };
+    if (!kev.ok)
+        Object.assign(cisa, failure(kev));
+    else {
+        const d = obj(kev.data);
+        const catalog = obj(d?.catalog);
+        const method = typeof d?.method === "string" ? d.method : null;
+        Object.assign(cisa, {
+            state: catalog === undefined && method === null ? "not_reported" : "reported",
+            reported: { catalog: catalog === undefined ? null : pick(catalog, CATALOG_FIELDS), method },
+            notes: [
+                "method is the API's own sentence about how it polls CISA's feed, quoted as sent; catalog.last_successful_fetch_at is when CISA last answered that poll.",
+            ],
+        });
+    }
+    return {
+        uri: SOURCES_URI,
+        api_base: kit.shownBase,
+        read_at: new Date().toISOString(),
+        sources: [nvd, cisa],
+        not_reported: [
+            "No public endpoint this server reads reports a poll cadence or a last poll time for the MITRE-CNA pre-NVD records, EPSS, GitHub GHSA, the OSV.dev advisory records, the vendor-advisory feeds, or the exposure radars' sources; this resource states none for them.",
+            "exposure_radar's freshness gives each radar's last_run_at, its last completed check, where the API serves one.",
+        ],
+    };
+}
+const json = (uri, v) => ({ contents: [{ uri, mimeType: "application/json", text: JSON.stringify(v, null, 2) }] });
+export function registerResources(server, kit) {
+    server.registerResource("methodology", METHODOLOGY_URI, {
+        title: "How results are measured",
+        description: "What each evidence-envelope field (state, measured_at, method, coverage, freshness, notes) means, the state values, and how each tool measures.",
+        mimeType: "text/markdown",
+    }, 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.",
+        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.",
+        mimeType: "application/json",
+    }, async (uri, vars) => {
+        const raw = Array.isArray(vars.cve_id) ? vars.cve_id[0] : vars.cve_id;
+        const id = decodeURIComponent(String(raw ?? "")).trim();
+        if (!kit.cveId.test(id)) {
+            throw new ProtocolError(ProtocolErrorCode.InvalidParams, `cve:// takes a CVE ID such as CVE-2024-3400 (${id.length} characters given)`, { uri: uri.href, reason: "invalid_cve_id" });
+        }
+        const r = await kit.getCve(id.toUpperCase());
+        if (r.isError) {
+            const msg = r.content[0]?.text ?? "get_cve failed";
+            const err = obj(r.structuredContent.error);
+            if (err?.status === 404)
+                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);
+    });
+}

package/dist/runtime.js

@@ -0,0 +1,65 @@
+// Which entrypoint is running, and — for the hosted HTTP entrypoint only — the end client a
+// request is being answered for (#2316).
+//
+// One tool module (index.ts) serves two entrypoints: the npm package's stdio bin (index.ts
+// itself) and the hosted remote endpoint at mcp.echelongraph.io (http.ts). http.ts marks itself
+// here BEFORE it loads index.ts, which is how index.ts knows not to start the stdio transport.
+// The default is stdio: an entrypoint that forgets to mark itself gets the npm behaviour,
+// which is the published package's, unchanged.
+//
+// The npm package sends nothing extra, ever: upstreamHeaders() is empty unless the HTTP
+// entrypoint is running (the no-telemetry promise, #2304).
+import { AsyncLocalStorage } from "node:async_hooks";
+let httpEntrypoint = false;
+/** Called by http.ts before it imports index.ts. */
+export function markHttpEntrypoint() {
+    httpEntrypoint = true;
+}
+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) {
+    return clientStore.run({ clientIp }, fn);
+}
+/** The header that carries the forward token, and the one that names the client (core-backend waf/mcpforward.go). */
+export const FORWARD_TOKEN_HEADER = "X-EG-MCP-Forward";
+export const CLIENT_IP_HEADER = "X-EG-Client-IP";
+/** The token, trimmed: a Secret Manager value can carry a trailing newline. */
+export function forwardToken() {
+    return (process.env.ECHELONGRAPH_FORWARD_TOKEN ?? "").trim();
+}
+// The hosts the token may be sent to: core-backend's public host, plus one exact hostname an
+// operator (or a test's stub) names. Host-exact, never a suffix, for the reason marketing-site's
+// internalApiHeaders gives: nothing look-alike may coax the token out, even if
+// ECHELONGRAPH_API_BASE is ever pointed somewhere else.
+function tokenMayGoTo(url) {
+    let host;
+    try {
+        host = new URL(url).hostname;
+    }
+    catch {
+        return false;
+    }
+    const extra = (process.env.ECHELONGRAPH_FORWARD_HOST ?? "").trim();
+    return host === "app.echelongraph.io" || (extra !== "" && host === extra);
+}
+/**
+ * The extra request headers for one API call to `url`: on the HTTP entrypoint, with a token
+ * configured, a client known and the URL on the allowlist, the token and the client's address;
+ * otherwise nothing. Why the API believes them, and under what rule, is core-backend's
+ * waf.MCPForwardedClient: without them every remote user would be keyed on this service's
+ * one address and share one budget (#2212).
+ */
+export function upstreamHeaders(url) {
+    if (!httpEntrypoint)
+        return {};
+    const token = forwardToken();
+    const clientIp = clientStore.getStore()?.clientIp;
+    if (!token || !clientIp || !tokenMayGoTo(url))
+        return {};
+    return { [FORWARD_TOKEN_HEADER]: token, [CLIENT_IP_HEADER]: clientIp };
+}

package/dist/tools/check_affected.js

@@ -0,0 +1,269 @@
+// check_affected (#2716): "am I affected by product X at version Y?", answered by the same
+// endpoint as echelongraph.io/am-i-affected, GET /api/v1/public/cves/match (core-backend
+// internal/cve/handler.go MatchByProductPublic). Two lookup paths, chosen by the input:
+//
+//   cpe       {product, version}: the CPE matcher (matchByProductPublic). CVEs whose NVD CPE
+//             product field is this token and whose version range includes this version. It
+//             matches the product token across vendors; each match names the vendor NVD asserts
+//             (cpe_vendor) and whether that vendor was verified (vendor_unknown).
+//   registry  {ecosystem, package, version}: the registry matcher (matchByPackage). The OSV
+//             advisory records EchelonGraph holds for this package, each decided against this
+//             version as affected, not affected, or undetermined.
+//
+// #1983: every typed value travels in a request header (X-EG-Product, X-EG-Version,
+// X-EG-Ecosystem, X-EG-Package; handler.go MatchProductHeader..MatchPackageHeader), percent-
+// encoded as the backend's publicMatchParam decodes it, and never in the URL: Cloud Run's request
+// log and its trace spans record the URL and no request header. The backend answers a
+// header-carried lookup with Cache-Control: private, no-store and varies on the four headers. The
+// endpoint reads the CPE vendor from the query string only (handler.go matchByProductPublic), so
+// this tool takes no vendor: sending one would put a typed value in the URL.
+//
+// The verdict is `assessed`, read BEFORE `count` (the endpoint's own contract): assessed false
+// means the lookup did not evaluate this component, and count 0 then asserts nothing. So the
+// envelope's state is measured only when the answer says assessed true; assessed false, or an
+// answer without assessed, is not_assessed, and the note's first sentence after the head says so,
+// with the reason. A 500/503 (advisory_lookup_failed) is a failure like any other non-2xx.
+//
+// The JSON is relayed verbatim as data (#1874): every match keeps kev_listed, ransomware,
+// epss_score, effective_score, effective_severity and score_assessed as the API sent them.
+import * as z from "zod";
+const TOOL = "check_affected";
+export const MATCH_PATH = "/api/v1/public/cves/match";
+// handler.go, the four request headers the endpoint reads before the query string.
+export const MATCH_HEADERS = { product: "X-EG-Product", version: "X-EG-Version", ecosystem: "X-EG-Ecosystem", package: "X-EG-Package" };
+const CPE_METHOD = "EchelonGraph's CPE matcher over its CVE corpus, the matcher behind echelongraph.io/am-i-affected and EchelonGraph's scanner: CVEs whose NVD CPE match criteria name this product token and whose version range includes this version.";
+const REGISTRY_METHOD = "EchelonGraph's registry matcher, the matcher behind echelongraph.io/am-i-affected for a registry package: the OSV advisory records EchelonGraph holds for this package in this ecosystem, each decided against this version as affected, not affected, or undetermined.";
+const NO_TIME = "measured_at is null: a match answer carries no observation time, and each matched CVE is a record of the CVE feed, polled from its sources on a schedule.";
+const NO_FRESHNESS = "freshness is null: the match answer carries no time at which the feed's pollers last completed.";
+// Why an answer says assessed false (core-backend cve/cpematch.go, cve/pkgmatch.go). One sentence
+// each, worded so that none reads as a clean result.
+const REASONS = {
+    product_not_in_cpe_corpus: "no CVE in the CPE corpus has this token as its CPE product, so the component was not located, not cleared; the CPE product token can differ from a package name (spring_boot, not spring-boot), and a registry package can be looked up by ecosystem and package instead.",
+    package_not_cpe_nameable: "the CVEs the CPE corpus holds for this token describe it in a way the CPE lookup cannot decide for this asset (an npm package NVD records only for target_sw node.js is the common case), so a registry lookup by ecosystem and package is the one to use.",
+    candidate_load_pending: "the product's candidate CVEs were still loading when this request's time ran out (degraded), so nothing was compared; the same lookup can be retried shortly.",
+    candidate_window_truncated: "the product has more candidate CVEs than one lookup loads (candidates_capped), so the CVEs below the cut were never examined.",
+    package_not_in_advisory_corpus: "EchelonGraph holds no advisory record for this package in this ecosystem, so the package was not located, not cleared; the ecosystem and package name are worth checking.",
+    no_decidable_advisory: "EchelonGraph holds advisories for this package, but not one of them could be decided either way at this version (see undetermined).",
+    advisory_lookup_failed: "the advisory lookup failed.",
+};
+// The reasons this version describes, and any other string, which the note names as one it does not.
+const REASON = z.union([z.enum(Object.keys(REASONS)), z.string()]).describe("Why assessed is false; empty or absent when it is true.");
+const opt = (t) => t.nullable().optional();
+const Match = z.looseObject({
+    cve_id: opt(z.string()),
+    description: opt(z.string()),
+    severity: opt(z.string()).describe("NVD's own CVSS v3 band, as provenance: it can be NONE for a CVE NVD rated only under CVSS v2. Rank and display on effective_severity."),
+    cvss_v3_score: opt(z.number()),
+    cvss_v2_score: opt(z.number()),
+    cvss_v4_score: opt(z.number()),
+    kev_listed: opt(z.boolean()).describe("Listed in CISA-KEV: known to be exploited."),
+    ransomware: opt(z.boolean()).describe("CISA-KEV records known use in ransomware campaigns."),
+    epss_score: opt(z.number()).describe("EPSS exploitation probability, 0 to 1."),
+    echelongraph_score: opt(z.number()).describe("EchelonGraph's 0-10 score: present only when score_assessed is true."),
+    echelongraph_severity: opt(z.string()),
+    effective_score: opt(z.number()).describe("The best real score held for the CVE (EchelonGraph's, else CVSS), the number the matches are ranked by."),
+    effective_severity: opt(z.string()).describe("The band of effective_score; absent or empty when the CVE has no band at all (unrated, not harmless)."),
+    score_assessed: opt(z.boolean()).describe("Whether EchelonGraph has scored the CVE. false: NOT YET SCORED, and echelongraph_score is withheld."),
+    score_unassessed_reason: opt(z.string()),
+    vendor_severity: opt(z.string()),
+    matched_criteria: opt(z.string()),
+    match_method: opt(z.string()),
+    match_confidence: opt(z.number()),
+    cpe_vendor: opt(z.string()).describe("The vendor NVD's CPE asserts for this match."),
+    vendor_unknown: opt(z.boolean()).describe("true: the vendor was not verified, so the match is real but its attribution to your vendor is not."),
+    match_reason: opt(z.string()),
+    version_evidence: opt(z.string()),
+});
+const Undetermined = z.looseObject({
+    cve_id: opt(z.string()),
+    package: opt(z.string()),
+    ecosystem: opt(z.string()),
+    reason: opt(z.string()),
+    detail: opt(z.string()),
+});
+const DATA = z.looseObject({
+    product: opt(z.string()),
+    version: opt(z.string()),
+    vendor: opt(z.string()),
+    ecosystem: opt(z.string()),
+    ecosystem_recognised: opt(z.boolean()),
+    package: opt(z.string()),
+    assessed: opt(z.boolean()).describe("Read first. true: the lookup evaluated this component. false: it did not, and count 0 says nothing about whether this version is affected."),
+    not_assessed_reason: opt(REASON),
+    match_layer: opt(z.string()),
+    cve_ids: opt(z.array(z.string())),
+    matches: opt(z.array(Match)),
+    count: opt(z.number()),
+    capped: opt(z.boolean()),
+    candidates_capped: opt(z.boolean()),
+    candidate_count: opt(z.number()),
+    advisories_considered: opt(z.number()),
+    excluded_count: opt(z.number()),
+    excluded: z.unknown().optional(),
+    undetermined_count: opt(z.number()),
+    undetermined: opt(z.array(Undetermined)),
+    not_affected_count: opt(z.number()),
+    degraded: opt(z.boolean()),
+    undecidable_excluded_count: opt(z.number()),
+    undecided_candidate_count: opt(z.number()),
+    product_named_count: opt(z.number()),
+    vendor_advisory_count: opt(z.number()),
+});
+const COVERAGE = z.strictObject({
+    assessed: z.boolean().nullable().describe("The answer's assessed, first: null when the answer does not say."),
+    not_assessed_reason: REASON.nullable(),
+    lookup: z.enum(["cpe", "registry"]).describe("Which lookup path this call asked for."),
+    match_layer: z.string().nullable(),
+    count: z.number().nullable(),
+    capped: z.boolean().nullable(),
+    candidates_capped: z.boolean().nullable(),
+    excluded_count: z.number().nullable(),
+    undetermined_count: z.number().nullable(),
+    not_affected_count: z.number().nullable(),
+    degraded: z.boolean().nullable(),
+});
+// Constant strings, so marketing-site lib/mcpToolClaims.test.ts can fold them should it read
+// this file.
+export const CHECK_AFFECTED_TITLE = "Am I affected? (product or package at a version)";
+export const CHECK_AFFECTED_DESCRIPTION = "Whether a product or package at a given version is affected by known CVEs, from the same matcher as echelongraph.io/am-i-affected. Two lookup paths. The CPE path takes product (the NVD CPE product token, such as openssl or nginx) and version, and returns the CVEs whose NVD CPE match criteria name that product with a version range that includes the version; it matches the token across vendors, so each match names the vendor NVD asserts (cpe_vendor) and whether that vendor was verified (vendor_unknown). The registry path takes ecosystem (npm, PyPI, Maven and other OSV ecosystem names), package and version, and decides each OSV advisory record EchelonGraph holds for that package as affected, not affected or undetermined. Read assessed before count: assessed false means the lookup did not evaluate this component, not_assessed_reason says why (product_not_in_cpe_corpus, package_not_cpe_nameable, candidate_load_pending, candidate_window_truncated, package_not_in_advisory_corpus, no_decidable_advisory), the structured result's state is not_assessed, and a count of 0 there must never be reported as not affected. An advisory whose version range cannot be decided at this version is reported as undetermined (undetermined_count, and up to 50 of them in undetermined), never as safe. The answer also carries match_layer (which path answered), capped (the match list stopped at its cap), candidates_capped (not every candidate CVE was loaded), excluded_count (CPE candidates suppressed by the vendor or platform gate), not_affected_count (advisories decided in your favour) and degraded (the lookup ran out of time). Each match carries cve_id, kev_listed, ransomware, epss_score, effective_score, effective_severity and score_assessed (false: EchelonGraph has not scored the CVE yet, so its echelongraph_score is withheld). Product, version, ecosystem and package travel in request headers, never in the URL. Its structured result carries state (measured only when the answer says assessed true), measured_at (null), method (which matcher answered), coverage (assessed and not_assessed_reason first, then the lookup path and the counts above), freshness (null) and notes, with data equal to the API's JSON.";
+export const CHECK_AFFECTED_INPUT = z.object({
+    product: z.string().optional().describe("CPE path: the NVD CPE product token, such as openssl, nginx or linux_kernel. Leave out for the registry path."),
+    ecosystem: z.string().optional().describe("Registry path: the package's ecosystem, such as npm, PyPI or Maven. Give with package, not with product."),
+    package: z.string().optional().describe("Registry path: the package name in that ecosystem, such as lodash."),
+    version: z.string().describe("The version to check, such as 3.0.0."),
+});
+const field = (o, k) => (o !== null && typeof o === "object" ? o[k] : undefined);
+const num = (o, k) => {
+    const v = field(o, k);
+    return typeof v === "number" && Number.isFinite(v) ? v : null;
+};
+const bool = (o, k) => {
+    const v = field(o, k);
+    return typeof v === "boolean" ? v : null;
+};
+const str = (o, k) => {
+    const v = field(o, k);
+    return typeof v === "string" && v ? v : null;
+};
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+// The sentences about the matches themselves: how many are KEV-listed, and which are not scored.
+function matchesNote(matches) {
+    const kev = matches.filter((m) => field(m, "kev_listed") === true).length;
+    const ransomware = matches.filter((m) => field(m, "ransomware") === true).length;
+    const unscored = matches.filter((m) => field(m, "score_assessed") === false).map((m, i) => str(m, "cve_id") ?? `matches[${i}]`);
+    const unverified = matches.filter((m) => field(m, "vendor_unknown") === true).length;
+    let out = "";
+    if (unverified > 0) {
+        out += ` ${unverified === matches.length ? "Every match has" : `${plural(unverified, "match has", "matches have")}`} vendor_unknown true: matched on the product name, so the vendor NVD asserts (cpe_vendor) is not verified to be the one you run.`;
+    }
+    if (kev > 0)
+        out += ` ${plural(kev, "of them is", "of them are")} listed in CISA-KEV (kev_listed)${ransomware > 0 ? `, ${ransomware} with known ransomware use` : ""}.`;
+    if (unscored.length > 0) {
+        const shown = unscored.slice(0, 10).join(", ");
+        out += ` NOT YET SCORED (score_assessed: false): ${shown}${unscored.length > 10 ? ` and ${unscored.length - 10} more` : ""}; EchelonGraph has not scored ${unscored.length === 1 ? "it" : "them"}, so an effective_score of zero or an empty effective_severity there means unrated, not harmless.`;
+    }
+    return out;
+}
+async function checkAffected(kit, a) {
+    const product = (a.product ?? "").trim();
+    const ecosystem = (a.ecosystem ?? "").trim();
+    const pkg = (a.package ?? "").trim();
+    const version = (a.version ?? "").trim();
+    if (product && (ecosystem || pkg))
+        return kit.badInput(TOOL, "give product (the CPE path) or ecosystem and package (the registry path), not both");
+    if (!product && !ecosystem && !pkg)
+        return kit.badInput(TOOL, "product, or ecosystem and package, is required");
+    if (!product && !ecosystem)
+        return kit.badInput(TOOL, "ecosystem is required with package");
+    if (!product && !pkg)
+        return kit.badInput(TOOL, "package is required with ecosystem");
+    if (!version)
+        return kit.badInput(TOOL, "version is required");
+    const lookup = product ? "cpe" : "registry";
+    // #1983: percent-encoded, as the backend's publicMatchParam decodes it (url.PathUnescape), so
+    // any value is a legal header and a literal + survives.
+    const enc = encodeURIComponent;
+    const headers = lookup === "cpe"
+        ? { [MATCH_HEADERS.product]: enc(product), [MATCH_HEADERS.version]: enc(version) }
+        : { [MATCH_HEADERS.ecosystem]: enc(ecosystem), [MATCH_HEADERS.package]: enc(pkg), [MATCH_HEADERS.version]: enc(version) };
+    try {
+        const r = await kit.api(MATCH_PATH, { headers });
+        if (!r.ok)
+            return kit.failed(TOOL, r);
+        const d = r.data;
+        const assessed = bool(d, "assessed");
+        const reason = str(d, "not_assessed_reason");
+        const matches = Array.isArray(field(d, "matches")) ? field(d, "matches") : [];
+        const count = num(d, "count") ?? (Array.isArray(field(d, "matches")) ? matches.length : null);
+        const capped = bool(d, "capped");
+        const candidatesCapped = bool(d, "candidates_capped");
+        const undetermined = num(d, "undetermined_count");
+        const notAffected = num(d, "not_affected_count");
+        const excluded = num(d, "excluded_count");
+        const degraded = bool(d, "degraded");
+        const layer = str(d, "match_layer");
+        const what = lookup === "cpe" ? `product ${product} at version ${version}` : `${ecosystem} package ${pkg} at version ${version}`;
+        // assessed, first.
+        let note = kit.okHead(TOOL, r.status);
+        if (assessed === true) {
+            note += ` (state: measured) assessed: true, so the lookup evaluated ${what}.`;
+        }
+        else if (assessed === false) {
+            const why = reason === null ? "the answer gives no not_assessed_reason." : (REASONS[reason] ?? `the answer gives not_assessed_reason ${reason}, which this version of the server does not describe.`);
+            note += ` (state: not_assessed) NOT ASSESSED: assessed is false for ${what}${reason === null ? "" : ` (not_assessed_reason ${reason})`}: ${why} A count of 0 here does not mean this version is not affected: do not report it as unaffected or clean.`;
+        }
+        else {
+            note += ` (state: not_assessed) The answer carries no assessed field (an API older than it sends none), so it does not say whether ${what} was evaluated, and a count of 0 here does not mean this version is not affected.`;
+        }
+        if (count !== null && count > 0) {
+            note += ` AFFECTED: ${plural(count, "CVE matches", "CVEs match")} this version${capped === true ? " (capped: true, so the list stopped at its cap and more may match)" : ""}.${matchesNote(matches)}`;
+        }
+        else if (count === 0 && assessed === true) {
+            note += ` 0 CVEs match this version, a measured result (we looked and found nothing that matches), not a lookup failure.`;
+            if (lookup === "registry" && notAffected !== null)
+                note += ` ${plural(notAffected, "advisory was", "advisories were")} decided not to affect this version (not_affected_count), and only those are cleared.`;
+        }
+        if (undetermined !== null && undetermined > 0) {
+            note += ` UNDETERMINED: ${plural(undetermined, "advisory names", "advisories name")} this package with a version range that could not be decided at this version (undetermined_count, listed in undetermined): report ${undetermined === 1 ? "it" : "them"} as undetermined, never as safe.`;
+        }
+        if (candidatesCapped === true && reason !== "candidate_window_truncated")
+            note += " candidates_capped is true: not every candidate CVE was loaded, so more CVEs may match than the answer lists.";
+        if (excluded !== null && excluded > 0)
+            note += ` ${plural(excluded, "candidate CVE was", "candidate CVEs were")} suppressed by the vendor or platform gate (excluded_count, listed in excluded).`;
+        if (degraded === true)
+            note += " degraded is true: the lookup ran out of time before it finished, so this answer is incomplete.";
+        return kit.succeeded(d, note, {
+            state: assessed === true ? "measured" : "not_assessed",
+            measured_at: null,
+            method: (layer ?? lookup) === "registry" ? REGISTRY_METHOD : CPE_METHOD,
+            coverage: {
+                assessed,
+                not_assessed_reason: reason,
+                lookup,
+                match_layer: layer,
+                count,
+                capped,
+                candidates_capped: candidatesCapped,
+                excluded_count: excluded,
+                undetermined_count: undetermined,
+                not_affected_count: notAffected,
+                degraded,
+            },
+            freshness: null,
+            notes: [NO_TIME, NO_FRESHNESS],
+        });
+    }
+    catch (e) {
+        return kit.crashed(TOOL, e);
+    }
+}
+export function registerCheckAffected(server, kit) {
+    const output = kit.envelopeSchema({ data: DATA, coverage: COVERAGE, freshness: null });
+    server.registerTool(TOOL, {
+        title: CHECK_AFFECTED_TITLE,
+        description: CHECK_AFFECTED_DESCRIPTION,
+        inputSchema: CHECK_AFFECTED_INPUT,
+        outputSchema: output,
+        annotations: kit.annotations,
+    }, async (a) => kit.checked(TOOL, output, await checkAffected(kit, a)));
+}