echelongraph-mcp 2.3.4 → 2.5.0

package/dist/index.js

@@ -5,7 +5,8 @@
 // that EchelonGraph's KEV-exposure radar derives from Shodan data. Every figure is as fresh as
 // the schedule that refreshes it, and the tool texts say which schedule that is.
 // stdio transport; no auth required; read-only. It makes no request other than the API call a
-// tool needs to answer.
+// tool needs to answer. The hosted Streamable HTTP endpoint (mcp.echelongraph.io, #2316) is
+// http.ts, which serves this file's createServer — one tool module for both.
 //
 // Result contract (#1874). A tool answers in exactly one of two shapes, and they never blur:
 //   - success: content[0] is the API's JSON verbatim; content[1] is a one-line note saying
@@ -45,6 +46,16 @@ import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/server";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import * as z from "zod";
+import { registerKevRecent } from "./tools/kev_recent.js";
+import { registerEPSSHistory } from "./tools/epss_history.js";
+import { registerCheckAffected } from "./tools/check_affected.js";
+import { registerCheckSbom } from "./tools/check_sbom.js";
+import { registerCveIntel } from "./tools/cve_intel.js";
+import { registerGetCwe } from "./tools/get_cwe.js";
+import { isHttpEntrypoint, upstreamHeaders } from "./runtime.js";
+import { registerVendorAdvisoryTools } from "./tools/vendor_advisories.js";
+import { registerPrompts } from "./prompts.js";
+import { registerResources } from "./resources.js";
 // The package actually running, read from the package.json that ships beside dist/. The MCP
 // handshake (serverInfo) and the User-Agent both carry its name and version, so the API's
 // access log can count adoption per version without a code change per release.
@@ -64,14 +75,30 @@ const pkgField = (k, fallback) => {
 const NAME = pkgField("name", "echelongraph-mcp");
 const VERSION = pkgField("version", "unknown");
 const BASE = (process.env.ECHELONGRAPH_API_BASE || "https://app.echelongraph.io").replace(/\/+$/, "");
-const UA = `${NAME}/${VERSION} (+https://echelongraph.io/pulse/mcp)`;
+// ECHELONGRAPH_MCP_UA (#2724): one product token, such as echelongraph-mcp-synthetic/1.0, put
+// AHEAD of the package's own User-Agent. The API's access log reads the family from the leading
+// token, so a caller that is not a user (our production synthetic) is filed under its own family
+// and never counted as MCP adoption, while the package and version stay readable after it.
+// Unset by default. A value that is not a single token (spaces, control characters, a name over 64
+// or a version over 32 characters) is ignored, with one line on stderr naming its length, not its text.
+const UA_TOKEN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}(?:\/[A-Za-z0-9][A-Za-z0-9._-]{0,31})?$/;
+const UA_PREFIX = (() => {
+    const v = process.env.ECHELONGRAPH_MCP_UA;
+    if (v === undefined || v === "")
+        return "";
+    if (UA_TOKEN.test(v))
+        return `${v} `;
+    process.stderr.write(`echelongraph-mcp: ECHELONGRAPH_MCP_UA ignored: not a single product token (${v.length} characters)\n`);
+    return "";
+})();
+const UA = `${UA_PREFIX}${NAME}/${VERSION} (+https://echelongraph.io/pulse/mcp)`;
 const DEFAULT_TIMEOUT_MS = 15_000;
 const TIMEOUT_MS = (() => {
     const n = Number(process.env.ECHELONGRAPH_API_TIMEOUT_MS);
     return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_TIMEOUT_MS;
 })();
 // The base as quoted in tool results. A proxy credential in the URL's userinfo is dropped.
-const SHOWN_BASE = (() => {
+export const SHOWN_BASE = (() => {
     try {
         const u = new URL(BASE);
         if (!u.username && !u.password)
@@ -127,47 +154,54 @@ function apiMessage(body) {
     }
     return snippet(body);
 }
-// One GET against the API. Never throws: every way the call can fail comes back as a typed
-// Failure so the tool renders it as an error result. A 2xx whose body is not a JSON object
-// (an SPA shell, an edge challenge page, a literal null) is a failure too — it is not data.
-async function api(path) {
+// One request against the API, a GET unless init says otherwise. Never throws: every way the call
+// can fail comes back as a typed Failure so the tool renders it as an error result. A 2xx whose
+// body is not a JSON object (an SPA shell, an edge challenge page, a literal null) is a failure
+// too — it is not data. init.headers carries what a caller typed (#1983: X-EG-* headers, never
+// the URL); the User-Agent and Accept are this server's and are not overridden.
+export async function api(path, init) {
     const ctrl = new AbortController();
     let timedOut = false;
     const timer = setTimeout(() => {
         timedOut = true;
         ctrl.abort();
     }, TIMEOUT_MS);
-    const timeout = () => ({ ok: false, kind: "timeout", path, detail: `no response within ${TIMEOUT_MS} ms` });
+    const m = init?.method && init.method.toUpperCase() !== "GET" ? { method: init.method.toUpperCase() } : {};
+    const timeout = () => ({ ok: false, kind: "timeout", path, ...m, detail: `no response within ${TIMEOUT_MS} ms` });
     try {
         let res;
         try {
             res = await fetch(`${BASE}${path}`, {
-                headers: { "User-Agent": UA, Accept: "application/json" },
+                method: init?.method,
+                body: init?.body,
+                // upstreamHeaders: empty on stdio; on the hosted endpoint, the forward token and the
+                // end client's address (runtime.ts, #2316).
+                headers: { ...upstreamHeaders(`${BASE}${path}`), ...(init?.headers ?? {}), "User-Agent": UA, Accept: "application/json" },
                 signal: ctrl.signal,
             });
         }
         catch (e) {
-            return timedOut ? timeout() : { ok: false, kind: "network", path, detail: describeError(e) };
+            return timedOut ? timeout() : { ok: false, kind: "network", path, ...m, detail: describeError(e) };
         }
         let body;
         try {
             body = await res.text();
         }
         catch (e) {
-            return timedOut ? timeout() : { ok: false, kind: "network", path, detail: `reading the body failed: ${describeError(e)}` };
+            return timedOut ? timeout() : { ok: false, kind: "network", path, ...m, detail: `reading the body failed: ${describeError(e)}` };
         }
         if (!res.ok)
-            return { ok: false, kind: "http", path, status: res.status, detail: apiMessage(body) };
+            return { ok: false, kind: "http", path, ...m, status: res.status, detail: apiMessage(body) };
         let data;
         try {
             data = JSON.parse(body);
         }
         catch {
             const ctype = res.headers.get("content-type") ?? "no content-type";
-            return { ok: false, kind: "not_json", path, status: res.status, detail: `${ctype}; body starts: ${snippet(body)}` };
+            return { ok: false, kind: "not_json", path, ...m, status: res.status, detail: `${ctype}; body starts: ${snippet(body)}` };
         }
         if (data === null || typeof data !== "object") {
-            return { ok: false, kind: "not_object", path, status: res.status, detail: `body was ${snippet(body)}` };
+            return { ok: false, kind: "not_object", path, ...m, status: res.status, detail: `body was ${snippet(body)}` };
         }
         return { ok: true, status: res.status, data };
     }
@@ -178,21 +212,22 @@ async function api(path) {
 const text = (t) => ({ type: "text", text: t });
 // A note, one sentence per entry. Sentences end in ".", "!" or "?" before whitespace, so a URL,
 // a version or a field path (observed.total, crt.sh) does not split one.
-const sentences = (t) => t
+export const sentences = (t) => t
     .replace(/\s+/g, " ")
     .trim()
     .split(/(?<=[.!?])\s+/)
     .filter(Boolean);
 // A timestamp worth relaying as one: see realInstant below.
-const instantOrNull = (s) => (realInstant(s) ? s : null);
+export const instantOrNull = (s) => (realInstant(s) ? s : null);
 // One sentence per failure kind: where we looked, for what, and what came back.
 function describeFailure(f) {
-    const where = `from ${SHOWN_BASE} for GET ${f.path}`;
+    const verb = f.method ?? "GET";
+    const where = `from ${SHOWN_BASE} for ${verb} ${f.path}`;
     switch (f.kind) {
         case "network":
-            return `EchelonGraph at ${SHOWN_BASE} could not be reached for GET ${f.path}: ${f.detail}.`;
+            return `EchelonGraph at ${SHOWN_BASE} could not be reached for ${verb} ${f.path}: ${f.detail}.`;
         case "timeout":
-            return `EchelonGraph at ${SHOWN_BASE} did not answer GET ${f.path} within ${TIMEOUT_MS} ms.`;
+            return `EchelonGraph at ${SHOWN_BASE} did not answer ${verb} ${f.path} within ${TIMEOUT_MS} ms.`;
         case "http":
             return `EchelonGraph answered HTTP ${f.status} ${where} — the API said: ${f.detail}.`;
         case "not_json":
@@ -204,7 +239,7 @@ function describeFailure(f) {
     }
 }
 // What a model must not conclude from a failure.
-const NOT_A_FINDING = "The lookup did not complete, so this is not a finding: do not report it as zero, none found, absent, or unexposed. Retry later or check ECHELONGRAPH_API_BASE.";
+export const NOT_A_FINDING = "The lookup did not complete, so this is not a finding: do not report it as zero, none found, absent, or unexposed. Retry later or check ECHELONGRAPH_API_BASE.";
 // A 404 is the one non-2xx that carries an answer of its own — the API's not-found message,
 // quoted in the sentence before it — so it is worded as "no record", not as an outage.
 const NO_RECORD = "The API returned no record for this request; the quoted message is the API's own explanation. This says nothing about internet exposure.";
@@ -242,25 +277,25 @@ const envelopeText = (structured, said, own) => {
 // structuredContent and again as the last text block. The error quotes only what
 // describeFailure already quotes (a redacted cause, the API's own message). Every note is a
 // sentence of the message, so the text envelope carries none.
-const failure = (state, message, error, coverage = null) => {
+export const failure = (state, message, error, coverage = null) => {
     const structuredContent = { state, measured_at: null, method: null, coverage, freshness: null, notes: sentences(message), error };
     return { content: [text(message), envelopeText(structuredContent, message, [])], structuredContent, isError: true };
 };
 const errorOf = (f) => ({ kind: f.kind, path: f.path, status: f.status ?? null, message: f.detail });
-const failed = (tool, f) => {
+export const failed = (tool, f) => {
     if (f.kind === "http" && f.status === 400) {
         return failure("invalid_input", `${tool} FAILED ${INVALID_INPUT}: ${describeFailure(f)} ${REJECTED_INPUT}`, errorOf(f));
     }
     return failure("failed", `${tool} FAILED: ${describeFailure(f)} ${f.kind === "http" && f.status === 404 ? NO_RECORD : NOT_A_FINDING}`, errorOf(f));
 };
-const badInput = (tool, why) => failure("invalid_input", `${tool} FAILED ${INVALID_INPUT}: ${why}. Nothing was looked up, so this is not a finding.`, {
+export const badInput = (tool, why) => failure("invalid_input", `${tool} FAILED ${INVALID_INPUT}: ${why}. Nothing was looked up, so this is not a finding.`, {
     kind: "invalid_input",
     path: null,
     status: null,
     message: why,
 });
 // A bug in this server is still not a finding — it must never surface as an empty success.
-const crashed = (tool, e) => failure("failed", `${tool} FAILED inside the MCP server while querying ${SHOWN_BASE}: ${describeError(e)}. ${NOT_A_FINDING}`, {
+export const crashed = (tool, e) => failure("failed", `${tool} FAILED inside the MCP server while querying ${SHOWN_BASE}: ${describeError(e)}. ${NOT_A_FINDING}`, {
     kind: "internal",
     path: null,
     status: null,
@@ -283,7 +318,7 @@ function unexpectedShape(tool, error) {
     });
 }
 // Every success is checked against the tool's own outputSchema before it is returned.
-const checked = (tool, schema, r) => {
+export const checked = (tool, schema, r) => {
     if (r.isError)
         return r;
     const p = schema.safeParse(r.structuredContent);
@@ -291,35 +326,35 @@ const checked = (tool, schema, r) => {
 };
 // A success: content[0] is the data, content[1] the note, content[2] the envelope less both;
 // the envelope carries both, the note as sentences after any the envelope adds about itself.
-const succeeded = (data, note, env) => {
+export const succeeded = (data, note, env) => {
     const own = env.notes ?? [];
     const structuredContent = { ...env, notes: [...own, ...sentences(note)], data };
     return { content: [text(JSON.stringify(data, null, 2)), text(note), envelopeText(structuredContent, note, own)], structuredContent };
 };
-const okHead = (tool, status) => `${tool} OK: EchelonGraph answered${status === undefined ? "" : ` HTTP ${status}`} from ${SHOWN_BASE}.`;
+export const okHead = (tool, status) => `${tool} OK: EchelonGraph answered${status === undefined ? "" : ` HTTP ${status}`} from ${SHOWN_BASE}.`;
 // Tolerant readers for the note: a missing or renamed field degrades the sentence, never
 // the result — content[0] still carries whatever the API sent.
-const field = (o, ...keys) => keys.reduce((v, k) => (v !== null && typeof v === "object" ? v[k] : undefined), o);
-const numAt = (o, ...keys) => {
+export const field = (o, ...keys) => keys.reduce((v, k) => (v !== null && typeof v === "object" ? v[k] : undefined), o);
+export const numAt = (o, ...keys) => {
     const v = field(o, ...keys);
     return typeof v === "number" && Number.isFinite(v) ? v : undefined;
 };
-const strAt = (o, ...keys) => {
+export const strAt = (o, ...keys) => {
     const v = field(o, ...keys);
     return typeof v === "string" && v ? v : undefined;
 };
-const lenAt = (o, ...keys) => {
+export const lenAt = (o, ...keys) => {
     const v = field(o, ...keys);
     return Array.isArray(v) ? v.length : undefined;
 };
-const boolAt = (o, ...keys) => {
+export const boolAt = (o, ...keys) => {
     const v = field(o, ...keys);
     return typeof v === "boolean" ? v : undefined;
 };
 // A timestamp worth repeating as prose. The API has been seen answering the Go zero time
 // (0001-01-01T00:00:00Z) where it had no instant to give; that is not a time, so it is never
 // presented as one.
-const realInstant = (s) => s !== undefined && Date.parse(s) > 0;
+export const realInstant = (s) => s !== undefined && Date.parse(s) > 0;
 // ── The CVE feed tools: cve_summary, search_cves, get_cve ──
 //
 // Their numbers are CVE records and scores, not exposure counts, so a success is measured.
@@ -364,7 +399,7 @@ function cveScoreNote(cve, rec) {
 }
 // search_cves' sentences about its rows' scores, naming each row a sentence is about, each
 // starting with a space; none when every row says it is scored.
-function rowsScoreNote(d) {
+export function rowsScoreNote(d) {
     const rows = field(d, "cves");
     if (!Array.isArray(rows) || rows.length === 0)
         return "";
@@ -550,6 +585,16 @@ async function searchCVEs(a) {
         return crashed(tool, e);
     }
 }
+// #2720: cpe_configurations is NVD's configuration tree, stored since migration 152 and filled
+// as the NVD poller next writes each CVE, so an answer without it is "not stored", never "no
+// product affected". Said in the envelope's own notes, so the note in content[1] is unchanged.
+function cpeConfigurationsNote(rec) {
+    const cfg = field(rec, "cpe_configurations");
+    if (Array.isArray(cfg)) {
+        return `cpe_configurations is NVD's configurations array as sent (${cfg.length}): a cpeMatch with vulnerable false in an AND configuration is a platform, not an affected product.`;
+    }
+    return "No cpe_configurations in the answer: EchelonGraph holds no stored NVD configuration tree for this CVE, which does not mean no product is affected; cpe_match lists its CPE criteria flattened, without the AND/OR operators.";
+}
 async function getCVE(cve_id) {
     const tool = "get_cve";
     const id = cve_id.trim();
@@ -572,6 +617,7 @@ async function getCVE(cve_id) {
                     ? "measured_at is the record's updated_at: when EchelonGraph last wrote this record."
                     : "measured_at is null: the record carries no real updated_at.",
                 NO_FEED_FRESHNESS,
+                cpeConfigurationsNote(r.data),
             ],
         });
     }
@@ -600,7 +646,7 @@ async function getCVE(cve_id) {
 // stored.
 // Every text calls last_seen a write or refresh time, never a sighting ("last seen listening",
 // "re-seen", "most recently seen"), and it is never measured_at (see observedAt).
-const CVE_ID = /^CVE-\d{4}-\d{4,}$/i;
+export const CVE_ID = /^CVE-\d{4}-\d{4,}$/i;
 // Quoted when the API does not send its own `method` string.
 const EXPOSURE_METHOD = "Shodan banner match on the radar's tracked products; up to 100 ip:port services per product query; searched every 12 h when Shodan query credits allow";
 const SHODAN_ATTRIBUTION = "Exposure counts are derived from Shodan data.";
@@ -1645,7 +1691,7 @@ const ErrorSchema = z.strictObject({
     status: z.number().int().nullable().describe("The HTTP status, when the API answered one."),
     message: z.string().describe("The cause: the API's own message, or what went wrong."),
 });
-const NOTES = z.array(z.string()).describe("Caveats, one sentence each.");
+export const NOTES = z.array(z.string()).describe("Caveats, one sentence each.");
 // The success states (#2465). 2.1.0 described not_assessed as no dated measurement whose numbers
 // were all denied the status of findings, on the same schema as a cve_exposure answer relaying
 // services on record for a CISA-KEV CVE, which is not_assessed because its count is undated
@@ -1654,7 +1700,7 @@ const NOTES = z.array(z.string()).describe("Caveats, one sentence each.");
 // says both, and leaves what each count is to the notes and exposure_state, which say it per
 // answer; it makes no blanket claim about the numbers, in either direction.
 const SUCCESS_STATE = "measured: a measurement of what was asked; an exposure count is measured only with measured_at and method. 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, and its notes (and exposure_state, where the result carries it) say what each count is.";
-function envelopeSchema(o) {
+export function envelopeSchema(o) {
     const coverage = o.coverage ? o.coverage.nullable() : z.null();
     return z.discriminatedUnion("state", [
         z.strictObject({
@@ -1679,7 +1725,11 @@ function envelopeSchema(o) {
     ]);
 }
 // A field of the API's JSON: optional, and null where the Go type can marshal null.
-const opt = (t) => t.nullable().optional();
+export const opt = (t) => t.nullable().optional();
+// #2720: what cpe_match and cpe_configurations are, one constant string each (the site's
+// tool-claims check folds only constant strings).
+const CPE_MATCH_DESCRIPTION = "The record's CPE match criteria as one flat list, every configuration's cpeMatch entries together: the AND/OR operator and negate of each configuration and node, versionStartExcluding and matchCriteriaId are not in it, so a CPE that is only a platform a product runs on reads as one more entry.";
+const CPE_CONFIGURATIONS_DESCRIPTION = "NVD's configurations array as NVD sent it: each configuration and node with its operator (AND, OR) and negate, and each cpeMatch with criteria, vulnerable, versionStartIncluding, versionStartExcluding, versionEndIncluding, versionEndExcluding and matchCriteriaId. A cpeMatch with vulnerable false inside an AND configuration is the platform the vulnerable product runs on, not an affected product. Absent: EchelonGraph holds no stored NVD configuration for the CVE, which is not a finding that no product is affected.";
 const CVERecord = z.looseObject({
     cve_id: opt(z.string()),
     description: opt(z.string()),
@@ -1701,6 +1751,9 @@ const CVERecord = z.looseObject({
     kev_added_date: opt(z.string()),
     ghsa_id: opt(z.string()),
     references: z.unknown().optional(),
+    // #2720: NVD's configurations, losslessly, beside the flat list (see cpeConfigurationsNote).
+    cpe_match: z.unknown().optional().describe(CPE_MATCH_DESCRIPTION),
+    cpe_configurations: opt(z.array(z.unknown())).describe(CPE_CONFIGURATIONS_DESCRIPTION),
     published: opt(z.string()),
     modified: opt(z.string()),
     updated_at: opt(z.string()),
@@ -1888,7 +1941,7 @@ const INSTRUCTIONS = [
     `${SHODAN_ATTRIBUTION} ${SHODAN_OWNERSHIP}`,
     "exposure_radar's mcp_servers counts use no Shodan data: their hostnames come from EchelonGraph's own Certificate Transparency feed.",
 ].join(" ");
-const ANNOTATIONS = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
+export const ANNOTATIONS = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
 const CVE_ID_ARG = z.string().describe("a CVE ID, e.g. CVE-2023-44487");
 // What each description says about its structured result, naming only fields its schema holds.
 const FEED_ENVELOPE = "Its structured result carries state (measured), measured_at, method, coverage, freshness (null: the feed serves no poll-completion time) and notes, with data equal to the API's JSON; the result's last text block repeats it without data (the first text block) and without the note's sentences (the text block before it), with which notes ends.";
@@ -1905,10 +1958,13 @@ const SUMMARY_REJECTED_DESCRIPTION = "summary.rejected counts the CVE records re
 // #2535: what search_cves and get_cve say about score_assessed, one constant string, since the
 // site's tool-claims check (marketing-site lib/mcpToolClaims.test.ts) folds only constant strings.
 const SCORE_ASSESSED_DESCRIPTION = "echelongraph_score, echelongraph_severity and echelongraph_risk are EchelonGraph's score only when score_assessed is true. With score_assessed false the CVE is NOT YET SCORED, not scored 0: any of those three it carries (0, NONE, 0) is a placeholder, not a rating, and does not mean the CVE is harmless; the API may leave them out instead, score_confidence is NONE, and score_unassessed_reason says why (a rejected record, withdrawn by its numbering authority, is never scored, and the note says NOT SCORED). The note labels each such CVE NOT YET SCORED: report it that way, never as a score of 0. An answer with no score_assessed (an API older than that field) does not say whether the CVE was scored, the note says so, and a 0 there is not a rating either.";
-// One server, built per connection by serveStdio for whichever era the client opens with.
+// The shared helpers a tool in src/tools/ is handed (#2718), so its file holds its own logic.
+const TOOL_KIT = { api, succeeded, failed, badInput, crashed, checked, okHead, envelopeSchema, annotations: ANNOTATIONS, cveIdArg: CVE_ID_ARG, instant: Instant };
+// One server, built per connection by serveStdio for whichever era the client opens with, and
+// per request by the hosted HTTP entrypoint (http.ts, #2316): one tool module for both.
 // tools/list answers in registration order, which is the order below.
-function createServer() {
-    const server = new McpServer({ name: NAME, version: VERSION }, { instructions: INSTRUCTIONS, capabilities: { tools: { listChanged: false } } });
+export function createServer() {
+    const server = new McpServer({ name: NAME, version: VERSION }, { instructions: INSTRUCTIONS, capabilities: { tools: { listChanged: false }, prompts: { listChanged: false }, resources: { listChanged: false } } });
     server.registerTool("cve_summary", {
         title: "CVE feed summary",
         description: `Summary of EchelonGraph's CVE Pulse feed: summary.total active CVEs, their counts by severity band (summary.critical, summary.high, summary.medium, summary.low), the count with no band (summary.none), and summary.last_updated, the newest modification time among those records. ${SUMMARY_NONE_DESCRIPTION} ${SUMMARY_NVD_DESCRIPTION} ${SUMMARY_REJECTED_DESCRIPTION} The feed is polled from its sources on a schedule, so this is the state as of that update. ${FEED_ENVELOPE}`,
@@ -1930,7 +1986,7 @@ function createServer() {
     }, async (a) => checked("search_cves", SEARCH_CVES_OUTPUT, await searchCVEs(a)));
     server.registerTool("get_cve", {
         title: "CVE detail",
-        description: `Full record for one CVE: description, severity, cvss_v3_score, cvss_v4_score and cvss_v4_severity (when the record has a CVSS v4 score), echelongraph_score and echelongraph_severity with score_confidence (EchelonGraph's multi-source score) and score_assessed (whether EchelonGraph has scored it), epss_score and epss_percentile, CISA-KEV status (kev_listed, kev_added_date, and kev_ransomware for known ransomware-campaign use), ghsa_id (GitHub GHSA), references, published, modified and updated_at; each field only where the record has it. Pass a CVE ID like CVE-2023-44487. ${SCORE_ASSESSED_DESCRIPTION} ${FEED_ENVELOPE}`,
+        description: `Full record for one CVE: description, severity, cvss_v3_score, cvss_v4_score and cvss_v4_severity (when the record has a CVSS v4 score), echelongraph_score and echelongraph_severity with score_confidence (EchelonGraph's multi-source score) and score_assessed (whether EchelonGraph has scored it), epss_score and epss_percentile, CISA-KEV status (kev_listed, kev_added_date, and kev_ransomware for known ransomware-campaign use), ghsa_id (GitHub GHSA), references, cpe_match (the CPE criteria as one flat list) and cpe_configurations (NVD's configurations as NVD sent them, with each AND/OR operator, negate, versionStartExcluding and matchCriteriaId; absent where EchelonGraph has stored none, which is not a finding that no product is affected), published, modified and updated_at; each field only where the record has it. Pass a CVE ID like CVE-2023-44487. ${SCORE_ASSESSED_DESCRIPTION} ${FEED_ENVELOPE}`,
         inputSchema: z.object({ cve_id: CVE_ID_ARG }),
         outputSchema: GET_CVE_OUTPUT,
         annotations: ANNOTATIONS,
@@ -1948,9 +2004,30 @@ function createServer() {
         outputSchema: EXPOSURE_RADAR_OUTPUT,
         annotations: ANNOTATIONS,
     }, async () => checked("exposure_radar", EXPOSURE_RADAR_OUTPUT, await exposureRadar()));
+    registerKevRecent(server, { api, succeeded, failed, badInput, crashed, checked, envelopeSchema, okHead, annotations: ANNOTATIONS });
+    registerEPSSHistory(server, TOOL_KIT);
+    // #2716: its logic, schemas and description live in tools/check_affected.ts.
+    registerCheckAffected(server, { api, succeeded, failed, badInput, crashed, checked, okHead, envelopeSchema, annotations: ANNOTATIONS });
+    // #2721: tools/check_sbom.ts, on this file's api(), envelope and failure contract.
+    registerCheckSbom(server, { api, failed, badInput, crashed, checked, succeeded, okHead, envelopeSchema, annotations: ANNOTATIONS });
+    registerCveIntel(server);
+    registerGetCwe(server);
+    // #2719: vendor_advisories_for_cve, get_vendor_advisory, search_vendor_advisories.
+    registerVendorAdvisoryTools(server, { api, failed, badInput, crashed, succeeded, checked, okHead, envelopeSchema, annotations: ANNOTATIONS });
+    // #2722: prompts and resources, in prompts.ts and resources.ts. Both lists are fixed per
+    // connection, so listChanged is false above.
+    registerPrompts(server, { cveId: CVE_ID });
+    registerResources(server, { api, cveId: CVE_ID, shownBase: SHOWN_BASE, getCve: async (id) => checked("get_cve", GET_CVE_OUTPUT, await getCVE(id)) });
     return server;
 }
+// The package identity and API settings, for the hosted HTTP entrypoint's health answer and
+// start-up line (http.ts).
+export { NAME, VERSION, TIMEOUT_MS }; // SHOWN_BASE is exported where it is declared.
 // Both eras on stdio: a 2026-07-28 client's server/discover, and a 2025-era client's initialize.
-serveStdio(createServer, { legacy: "serve" });
-// MCP uses stdout for the protocol — diagnostics go to stderr.
-console.error(`EchelonGraph CVE MCP server ${NAME}@${VERSION} running (API: ${SHOWN_BASE}, timeout ${TIMEOUT_MS} ms)`);
+// Not when the hosted HTTP entrypoint loaded this module (runtime.ts): it serves createServer
+// itself, and a stdio transport there would read the container's stdin.
+if (!isHttpEntrypoint()) {
+    serveStdio(createServer, { legacy: "serve" });
+    // MCP uses stdout for the protocol — diagnostics go to stderr.
+    console.error(`EchelonGraph CVE MCP server ${NAME}@${VERSION} running (API: ${SHOWN_BASE}, timeout ${TIMEOUT_MS} ms)`);
+}

package/dist/prompts.js

@@ -0,0 +1,137 @@
+import * as z from "zod";
+import { MAX_COMPONENTS, MAX_SBOM_CHARS } from "./tools/check_sbom.js";
+export const KEV_BRIEF_DEFAULT_DAYS = 7;
+export const KEV_BRIEF_MAX_DAYS = 365;
+// 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.",
+    "state is measured, not_assessed, failed or invalid_input.",
+    "Report not_assessed as not assessed: never as clean, safe, unaffected or none found.",
+    'A count of 0 in a result whose coverage says assessed: false is not a finding of "not affected": say the lookup did not evaluate it, and give its not_assessed_reason.',
+    "failed and invalid_input mean nothing was looked up: say the lookup did not complete, never zero, none found or unexposed.",
+    "Cite the measured_at date behind each figure you report, and say so where measured_at is null.",
+    "Quote the notes that qualify a figure, and keep each field's meaning as the result's notes give it.",
+    "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 } }] });
+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.",
+        "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 its kev_added_date, 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.",
+        "- Decision: patch now, schedule, or monitor, with a one-line reason drawn from the lines above.",
+    ].join("\n");
+}
+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.",
+        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.",
+        "- One section per kev_vendor, vendors in alphabetical order. Under each, one line per CVE: cve_id, kev_product, kev_vuln_name, kev_added_date, kev_due_date, and RANSOMWARE where kev_ransomware is true.",
+        "- A closing section listing again the CVEs with kev_ransomware true, and every kev_due_date in the range, earliest first.",
+        "- If total is 0, write that no CVE was added in that range in the catalog copy fetched at measured_at. If kev_recent failed, write that the catalog could not be read: never that nothing was added.",
+    ].join("\n");
+}
+export function amIAffectedText(a) {
+    const subject = a.product ? `the product ${JSON.stringify(a.product)} (an NVD CPE product token)` : `the package ${JSON.stringify(a.package)} in the ${JSON.stringify(a.ecosystem)} ecosystem`;
+    const args = a.product ? { product: a.product, version: a.version } : { ecosystem: a.ecosystem, package: a.package, version: a.version };
+    return [
+        `Check whether ${subject} at version ${JSON.stringify(a.version)} is affected by known CVEs, using the EchelonGraph MCP tools.`,
+        `1. Call check_affected with these arguments: ${JSON.stringify(args)}.`,
+        ENVELOPE_RULES,
+        "Read coverage.assessed before count, and answer with the case that applies:",
+        "- assessed true and count above 0: affected. List each match's cve_id with kev_listed, ransomware, epss_score and effective_score (score_assessed false: not yet scored, not a score of 0), CISA-KEV-listed CVEs first.",
+        "- assessed true and count 0: no matching CVE in EchelonGraph's data at this version. Give undetermined_count too: an advisory that could not be decided at this version is not safe.",
+        "- assessed false: NOT ASSESSED. Write that the lookup did not evaluate this version, give not_assessed_reason, and never report it as not affected or clean.",
+        "- failed or invalid_input: the check did not run. Say why, from the result.",
+        "Where capped, candidates_capped or degraded is true, say the list may be incomplete and why.",
+    ].join("\n");
+}
+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_COMPONENTS} distinct purls per call; a document with more is refused, not truncated. If it is refused, say why from the result and do not guess at the components.`,
+        "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.",
+        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.",
+        "",
+        "SBOM:",
+        "```json",
+        sbom,
+        "```",
+    ].join("\n");
+}
+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.",
+        argsSchema: z.object({
+            cve_id: z
+                .string()
+                .trim()
+                .regex(kit.cveId, "cve_id must be a CVE ID such as CVE-2024-3400")
+                .describe("a CVE ID, e.g. CVE-2024-3400"),
+        }),
+    }, ({ cve_id }) => text(triageCveText(cve_id.toUpperCase())));
+    server.registerPrompt("kev_weekly_brief", {
+        title: "CISA KEV brief",
+        description: "A brief of the CVEs CISA added to its KEV catalog in the last N days (default 7): kev_recent from a since date the model computes from days, grouped by vendor, with ransomware flags and due dates, dated by EchelonGraph's last successful fetch of CISA's feed.",
+        // A client may send no arguments at all for a prompt whose arguments are all optional.
+        argsSchema: z.preprocess((v) => v ?? {}, z.object({
+            days: z
+                .string()
+                .trim()
+                .regex(/^\d{1,3}$/, `days must be a whole number from 1 to ${KEV_BRIEF_MAX_DAYS}`)
+                .refine((v) => Number(v) >= 1 && Number(v) <= KEV_BRIEF_MAX_DAYS, `days must be a whole number from 1 to ${KEV_BRIEF_MAX_DAYS}`)
+                .optional()
+                .describe(`how many days back to cover, 1 to ${KEV_BRIEF_MAX_DAYS} (default ${KEV_BRIEF_DEFAULT_DAYS})`),
+        })),
+    }, ({ days }) => text(kevWeeklyBriefText(days === undefined || days === "" ? KEV_BRIEF_DEFAULT_DAYS : Number(days))));
+    server.registerPrompt("am_i_affected", {
+        title: "Am I affected?",
+        description: "Whether a product (its NVD CPE product token) or a registry package (ecosystem and package) at a version is affected by known CVEs: check_affected, read assessed before count, with the not-assessed wording: a count of 0 under assessed false is never reported as not affected.",
+        argsSchema: z
+            .object({
+            product: z.string().trim().min(1).optional().describe("CPE path: the NVD CPE product token, such as openssl or nginx. Leave out for the registry path."),
+            ecosystem: z.string().trim().min(1).optional().describe("Registry path: the package's ecosystem, such as npm, PyPI or Maven. Give with package."),
+            package: z.string().trim().min(1).optional().describe("Registry path: the package name, such as lodash. Give with ecosystem."),
+            version: z.string().trim().min(1).describe("The version to check, such as 3.0.0."),
+        })
+            .superRefine((a, ctx) => {
+            const registry = a.ecosystem !== undefined || a.package !== undefined;
+            if (a.product !== undefined && registry) {
+                ctx.addIssue({ code: "custom", message: "give product, or ecosystem and package, not both" });
+            }
+            else if (a.product === undefined && (a.ecosystem === undefined || a.package === undefined)) {
+                ctx.addIssue({ code: "custom", message: "give product, or both ecosystem and package" });
+            }
+        }),
+    }, (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_COMPONENTS} distinct purls per call, 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.`,
+        argsSchema: z.object({
+            sbom: z
+                .string()
+                .min(1, "sbom is required")
+                .max(MAX_SBOM_CHARS, `sbom is longer than ${MAX_SBOM_CHARS} characters, check_sbom's cap`)
+                .describe(`a CycloneDX JSON or SPDX JSON document, as JSON text, up to ${MAX_SBOM_CHARS} characters; it is passed to check_sbom`),
+        }),
+    }, ({ sbom }) => text(sbomReviewText(sbom)));
+}