echelongraph-mcp 3.0.2 → 3.1.1

package/dist/requiredText.js

@@ -5,8 +5,8 @@
 // dropped, a head naming Shodan without SHODAN_OWNERSHIP, or a tool registered with no entry here
 // fails it. A tool added later adds its entry here.
 //
-// The cut. Claude Code sends each MCP tool description and each server's instructions to the model
-// cut at 2,048 characters, with "… [truncated]" appended:
+// The cut. Claude Code from v2.1.280 sent each MCP tool description and each server's instructions
+// to the model cut at 2,048 characters, with "… [truncated]" appended:
 //   - Claude Code docs, environment variables (code.claude.com/docs/en/env-vars, read 2026-10-05):
 //     CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH, "Maximum length in characters of each MCP tool
 //     description and each MCP server's instructions that Claude Code sends to the model (default:
@@ -14,10 +14,15 @@
 //   - anthropics/claude-code#87650 (closed, not planned): the minified constant Tpe=2048 gates the
 //     cut in v2.1.234; /mcp shows the whole text while the model receives the cut one, and only the
 //     instructions' cut is logged ("Server instructions truncated from X to 2048 chars").
+//   - Re-read 2026-10-18: the same page now gives default limits of 4,096, and 16,384 for a tool
+//     Claude Code loads through tool search, and v2.1.302's --debug log shows "Tool
+//     "exposure_radar" description truncated from 11807 to 4096 chars" (2.6.8's description). The
+//     budget stays 2,048: builds from v2.1.280 until that change cut there, and they are in use.
 // The other clients looked at cut later or not at all: Cursor cuts tool descriptions at 6,500
 // characters (Cursor staff, forum.cursor.com/t/147465); VS Code and Claude Desktop document no
 // description cap (VS Code caps a tool's name at 64 characters and a request at 128 tools). So
-// Claude Code's default is the budget: text that fits it reaches every one of them whole.
+// the shortest cut a client is known to make is the budget: text that fits it reaches every one of
+// them whole. docs/tools.md ("The client cut") says the same for readers.
 //
 // Kept under src/ so marketing-site lib/mcpToolClaims.test.ts's resolver can fold the two Shodan
 // sentences, which the descriptions and notes take from here.
@@ -127,7 +132,22 @@ export const REQUIRED_IN_HEAD = {
 // none. The sentence says what that pair means and which field is the current reading; it names a
 // field, not a tool (test/description-policy.test.mjs: no schema text names another tool).
 export const PATCH_AVAILABLE_WITHDRAWN = "true beside an empty patch_evidence means evidence of a fix once held has since been withdrawn (patch_available is never set back to false), and fix_status (remediation.fix_status in the CVE's record) is the current reading, not patch_available.";
+// #3016: cve_exposure's three KEV flags. kev_listed is core-backend's deprecated alias of
+// kev_seen_in_observations (kevexposure/store.go CVEExposure.KEVListed): bool_or over the radar's
+// observation rows, so it is false for a CISA-KEV CVE the radar holds no service for, whatever the
+// catalog says. Through 3.0.2 the outputSchema gave all three as booleans with no text, and hosted
+// cve_exposure CVE-2024-3400 (PAN-OS, CISA-KEV) served kev_listed false beside kev_catalog_listed
+// true (2026-10-10), so a client reading data alone could report a KEV CVE as not on KEV. The
+// field stays (dropping it would break a reader, a major version); its text says what it is.
+export const KEV_LISTED_DEPRECATED = "Deprecated: the same value as kev_seen_in_observations, kept for compatibility.";
+export const KEV_OBSERVATION_FLAG = "It is the radar's observation flag, not CISA-KEV catalog status";
+export const KEV_CATALOG_FLAG = "The CISA-KEV catalog flag:";
 export const REQUIRED_IN_OUTPUT_SCHEMA = {
     get_cve: { "data.patch_available": [PATCH_AVAILABLE_WITHDRAWN] },
     search_cves: { "data.cves[].patch_available": [PATCH_AVAILABLE_WITHDRAWN] },
+    cve_exposure: {
+        "data.kev_listed": [KEV_LISTED_DEPRECATED, KEV_OBSERVATION_FLAG],
+        "data.kev_seen_in_observations": [KEV_OBSERVATION_FLAG],
+        "data.kev_catalog_listed": [KEV_CATALOG_FLAG],
+    },
 };

package/dist/resources.js

@@ -55,15 +55,15 @@ A count of 0 is a finding of none when the answer measured it. Under assessed: f
 
 ## 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.
+- cve_summary: measured; measured_at is summary.last_updated, the newest modification time among the active CVE records it counts. freshness.nvd_poll is the fleet's last completed NVD poll: last_run_at is the answer's nvd_poll.last_completed_at, with scope fleet and the poll's interval. freshness is null where the answer carries no nvd_poll block (an older API, or one holding no fleet NVD poll it could read) or one without a real RFC 3339 time, and the note says which.
 - 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.
+- 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. A registry match carries fixed_in, the lowest version above the one asked about that no affected interval of its record holds, or null with fixed_in_reason, which is not a finding that no fix exists. A CPE match carries no fixed_in: the end of the NVD range it matched, cpe_version_end_excluding or cpe_version_end_including, is not a fix.
+- 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. Each match carries fixed_in, or null with fixed_in_reason, as check_affected's registry matches do. A deb, apk or alpine purl with an upstream qualifier (upstream=name, or upstream=name@version) is checked as the source package it names, which is how Debian and Alpine file advisories: its row says matched_via upstream, with that name as matched_package. Any other row the lookup ran for says matched_via purl_name; a refused row has neither. A binary package such as libssl3 sent without the qualifier is looked up by its own name, which the advisories do not use, and comes back not_assessed (package_not_in_advisory_corpus), never clean.
 - scan_manifest: as check_sbom, on the purls this server reads from the lockfiles passed; not_assessed, with no API call, when no entry pins one registry version. Each entry not sent (a range, an unresolved version, a local path, a VCS checkout or a line not read) is listed in data.not_checked with its reason and is not clean; a refused file (package.json, go.sum and the other manifests of ranges) is named in the note, and nothing in it is checked.
 - cve_intel: measured_at null: each row carries its own dates. An exploits row carries source_published_at, the source's own date for the reference, null when the source publishes none (EchelonGraph does not supply one), and eg_first_seen_at, when EchelonGraph recorded the reference; first_seen_at is deprecated and holds the same value as source_published_at. A timeline row carries enriched_at. An empty exploits list is not evidence that no public exploit exists.
 - cve_remediation: measured with measured_at null, or not_assessed for a CVE record rejected by its numbering authority. Every text is its source's, verbatim and untested by EchelonGraph; each vendor item's kind is the vendor's own category. remediation_state none_in_source or not_parsed, and an empty list, are not a finding that no fix exists.

package/dist/runtime.js

@@ -20,7 +20,72 @@ export function isHttpEntrypoint() {
 }
 const clientStore = new AsyncLocalStorage();
 export function withClient(clientIp, fn, opts = {}) {
-    return clientStore.run({ clientIp, synthetic: opts.synthetic === true, signal: opts.signal, work: opts.work }, fn);
+    return clientStore.run({ clientIp, synthetic: opts.synthetic === true, signal: opts.signal, work: opts.work, rpcMethod: opts.rpcMethod, tool: opts.tool, protocolVersion: opts.protocolVersion }, fn);
+}
+/** #2923: the fixed labels of the request being served, for a line the SDK's onerror writes (it is handed only the
+ *  error): the JSON-RPC method (MCP_METHODS or "(other)") and the protocol-version label; "(none)" outside a request. */
+export function requestLabels() {
+    const scope = clientStore.getStore();
+    return { rpcMethod: scope?.rpcMethod ?? "(none)", protocolVersion: scope?.protocolVersion ?? "(none)" };
+}
+let upstreamSink;
+/** http.ts only: where each failed API call is reported. */
+export function onUpstreamFailure(sink) {
+    upstreamSink = sink;
+}
+/** Reports one failed API call: on the hosted endpoint to http.ts's line; on stdio, nowhere. */
+export function upstreamFailed(f) {
+    if (!httpEntrypoint || !upstreamSink)
+        return;
+    const scope = clientStore.getStore();
+    try {
+        upstreamSink({ ...f, tool: scope?.tool ?? "(none)", rpcMethod: scope?.rpcMethod ?? "(none)", synthetic: scope?.synthetic === true });
+    }
+    catch {
+        // A log line never fails the call it describes.
+    }
+}
+const DNS_CODES = new Set(["ENOTFOUND", "EAI_AGAIN", "EAI_FAIL", "EAI_NONAME", "EAI_NODATA"]);
+const RESET_CODES = new Set(["ECONNRESET", "EPIPE", "ECONNABORTED", "UND_ERR_SOCKET"]);
+const CONNECT_TIMEOUT_CODES = new Set(["UND_ERR_CONNECT_TIMEOUT", "ETIMEDOUT"]);
+const TIMEOUT_CODES = new Set(["UND_ERR_HEADERS_TIMEOUT", "UND_ERR_BODY_TIMEOUT"]);
+const UNREACHABLE_CODES = new Set(["EHOSTUNREACH", "ENETUNREACH", "EHOSTDOWN", "ENETDOWN"]);
+const TLS_CODE = /^(?:ERR_TLS_|ERR_SSL_|ERR_OSSL_|CERT_|UNABLE_TO_|DEPTH_ZERO_SELF_SIGNED_CERT$|SELF_SIGNED_CERT_IN_CHAIN$|HOSTNAME_MISMATCH$)/;
+/** The class of a fetch that threw: from the first code in its cause chain this knows, else network. Codes only, never a message. */
+export function networkFailureClass(e) {
+    const codes = [];
+    let c = e;
+    for (let depth = 0; c instanceof Error && depth < 5; depth++) {
+        const x = c;
+        if (typeof x.code === "string")
+            codes.push(x.code);
+        // A connection tried on several addresses fails as an AggregateError of each one's error.
+        if (Array.isArray(x.errors)) {
+            for (const y of x.errors) {
+                const code = y?.code;
+                if (typeof code === "string")
+                    codes.push(code);
+            }
+        }
+        c = x.cause;
+    }
+    for (const code of codes) {
+        if (DNS_CODES.has(code))
+            return "dns";
+        if (code === "ECONNREFUSED")
+            return "refused";
+        if (RESET_CODES.has(code))
+            return "reset";
+        if (CONNECT_TIMEOUT_CODES.has(code))
+            return "connect_timeout";
+        if (TIMEOUT_CODES.has(code))
+            return "timeout";
+        if (UNREACHABLE_CODES.has(code))
+            return "unreachable";
+        if (TLS_CODE.test(code))
+            return "tls";
+    }
+    return "network";
 }
 // #2775: a hosted client can go before its answer is ready (its own timeout, a closed tab, a
 // retry). Nobody will read that answer, so the request's API calls are cancelled (index.ts api()

package/dist/schemaRefusal.js

@@ -0,0 +1,147 @@
+const REFUSED = Symbol("echelongraph-mcp.schema-refused");
+const isRefused = (v) => typeof v === "object" && v !== null && REFUSED in v;
+// How many issues the note names one by one; the rest are counted.
+const ISSUES_NAMED = 5;
+const keyOf = (p) => (typeof p === "object" && p !== null ? p.key : p);
+// files[0].filename, as a model reads an argument path.
+function pathText(path) {
+    let out = "";
+    for (const p of path ?? []) {
+        const k = keyOf(p);
+        out += typeof k === "number" ? `[${k}]` : out === "" ? String(k) : `.${String(k)}`;
+    }
+    return out;
+}
+// The value the caller sent at a path, to name its JSON type (never the value itself).
+function valueAt(input, path) {
+    let v = input;
+    for (const p of path ?? []) {
+        if (v === null || typeof v !== "object")
+            return undefined;
+        v = v[keyOf(p)];
+    }
+    return v;
+}
+function jsonType(v) {
+    if (v === null)
+        return "null";
+    if (Array.isArray(v))
+        return "an array";
+    if (typeof v === "number")
+        return Number.isInteger(v) ? "an integer" : "a number";
+    if (typeof v === "object")
+        return "an object";
+    return typeof v === "string" ? "a string" : typeof v === "boolean" ? "a boolean" : typeof v;
+}
+const TYPE_NAMES = {
+    string: "a string",
+    number: "a number",
+    int: "an integer",
+    boolean: "a boolean",
+    array: "an array",
+    object: "an object",
+    record: "an object",
+    bigint: "an integer",
+};
+const listOf = (items) => (items.length < 2 ? items.join("") : `${items.slice(0, -1).join(", ")} or ${items[items.length - 1]}`);
+const bound = (n) => (typeof n === "bigint" ? n.toString() : typeof n === "number" ? String(n) : "?");
+// One issue as "<argument> <rule>": the argument named by its path in the arguments, the rule in the
+// inputSchema's terms. An issue this does not know is given in the schema library's own words.
+export function issueText(issue, input) {
+    const at = pathText(issue.path);
+    const name = at === "" ? "the arguments" : at;
+    const sent = valueAt(input, issue.path);
+    switch (issue.code) {
+        case "invalid_type": {
+            const want = TYPE_NAMES[issue.expected ?? ""] ?? issue.expected ?? "another type";
+            if (sent === undefined)
+                return `${name} is required (${want})`;
+            if (issue.expected === "int" && typeof sent === "number")
+                return `${name} must be an integer`;
+            return `${name} must be ${want}, not ${jsonType(sent)}`;
+        }
+        case "too_big":
+        case "too_small": {
+            const big = issue.code === "too_big";
+            const n = bound(big ? issue.maximum : issue.minimum);
+            const cmp = issue.inclusive === false ? (big ? "less than" : "more than") : big ? "at most" : "at least";
+            if (issue.origin === "string")
+                return `${name} must be ${cmp} ${n} ${n === "1" ? "character" : "characters"} long`;
+            if (issue.origin === "array" || issue.origin === "set")
+                return `${name} must hold ${cmp} ${n} ${n === "1" ? "entry" : "entries"}`;
+            // #3345: a record's bound (inputBounds.ts boundedRecord), counted in its own members.
+            if (issue.origin === "object" || issue.origin === "record")
+                return `${name} must hold ${cmp} ${n} ${n === "1" ? "member" : "members"}`;
+            return `${name} must be ${cmp} ${n}`;
+        }
+        case "invalid_value":
+            return Array.isArray(issue.values) && issue.values.length
+                ? `${name} must be ${issue.values.length === 1 ? "" : "one of "}${listOf(issue.values.map((v) => JSON.stringify(v)))}`
+                : `${name}: ${issue.message}`;
+        case "unrecognized_keys": {
+            const keys = (issue.keys ?? []).map((k) => (at === "" ? k : `${at}.${k}`));
+            return keys.length ? `${listOf(keys)} ${keys.length === 1 ? "is not an argument" : "are not arguments"} this tool takes` : `${name}: ${issue.message}`;
+        }
+        case "invalid_format":
+            return `${name} must be ${issue.format ? `a valid ${issue.format}` : "in the format the inputSchema gives"}`;
+        case "invalid_union": {
+            // #3345: the value is of the type one branch takes and broke that branch's rule (an sbom
+            // object past its bound): name that branch's issues, at the union's path.
+            const ofType = (b) => b.length === 1 && b[0].code === "invalid_type" && !b[0].path?.length;
+            const matched = (issue.errors ?? []).filter((b) => b.length > 0 && !ofType(b));
+            if (matched.length === 1)
+                return matched[0].map((i) => issueText({ ...i, path: [...(issue.path ?? []), ...(i.path ?? [])] }, input)).join("; ");
+            // Each branch refused only the value's type: name the types the branches take.
+            const types = (issue.errors ?? []).map((b) => (ofType(b) ? TYPE_NAMES[b[0].expected ?? ""] : undefined));
+            const named = types.length > 0 && types.every((t) => t !== undefined) ? [...new Set(types)] : undefined;
+            return named ? `${name} must be ${listOf(named)}, not ${jsonType(sent)}` : `${name} must take one of the forms the inputSchema allows, not ${jsonType(sent)}`;
+        }
+        default:
+            return `${name}: ${issue.message}`;
+    }
+}
+// The reason a refusal gives, as one clause: each issue in turn, then how many more there are.
+export function refusalReason(issues, input) {
+    const named = issues.slice(0, ISSUES_NAMED).map((i) => issueText(i, input));
+    const more = issues.length - named.length;
+    return `the arguments do not fit this tool's inputSchema (tools/list): ${named.join("; ")}${more > 0 ? `; and ${more} more ${more === 1 ? "issue" : "issues"}` : ""}`;
+}
+// The inputSchema a tool is registered with: `schema` itself for tools/list (its own jsonSchema,
+// so the published JSON is the original's), and a validate that answers what `schema` answers for
+// arguments it accepts, and a Refused marker, not the issues, for arguments it refuses.
+export function lenientSchema(schema) {
+    const std = schema["~standard"];
+    const settle = (value, r) => (r.issues && r.issues.length ? { value: { [REFUSED]: { issues: r.issues, input: value } } } : r);
+    return {
+        "~standard": {
+            version: std.version,
+            vendor: std.vendor,
+            jsonSchema: std.jsonSchema,
+            validate: (value) => {
+                const r = std.validate(value);
+                return r instanceof Promise ? r.then((x) => settle(value, x)) : settle(value, r);
+            },
+        },
+    };
+}
+const isStandardSchema = (s) => typeof s === "object" && s !== null && typeof s["~standard"]?.validate === "function";
+/**
+ * Makes every tool `server` registers from now on answer arguments that break its inputSchema with
+ * `refuse(tool, reason)` (index.ts badInput: the invalid_input envelope), not the SDK's bare error.
+ * Call it before the first registerTool. tools/list is unchanged.
+ */
+export function withSchemaRefusal(server, refuse) {
+    const register = server.registerTool.bind(server);
+    const wrapped = (name, config, cb) => {
+        if (!isStandardSchema(config.inputSchema))
+            return register(name, config, cb);
+        return register(name, { ...config, inputSchema: lenientSchema(config.inputSchema) }, (args, ctx) => {
+            if (!isRefused(args))
+                return cb(args, ctx);
+            const { issues, input } = args[REFUSED];
+            return refuse(name, refusalReason(issues, input));
+        });
+    };
+    server.registerTool = wrapped;
+    return server;
+}