echelongraph-mcp 2.3.4 → 2.4.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,14 @@ 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";
 // 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 +73,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 +152,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 +210,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 +237,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 +275,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 +316,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 +324,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 +397,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 +583,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 +615,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 +644,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 +1689,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 +1698,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 +1723,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 +1749,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 +1939,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,9 +1956,12 @@ 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() {
+export function createServer() {
     const server = new McpServer({ name: NAME, version: VERSION }, { instructions: INSTRUCTIONS, capabilities: { tools: { listChanged: false } } });
     server.registerTool("cve_summary", {
         title: "CVE feed summary",
@@ -1930,7 +1984,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 +2002,26 @@ 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 });
     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/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 };
+}