echelongraph-mcp 2.3.4 → 2.5.0

package/dist/http.js

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+// The hosted, keyless remote MCP endpoint: https://mcp.echelongraph.io/mcp (#2316).
+//
+// Streamable HTTP on @modelcontextprotocol/server 2.x's createMcpHandler, serving the SAME tool
+// module as the npm package (index.ts's createServer), in both protocol eras: a 2026-07-28
+// client's per-request envelope (server/discover first), and a 2025-era client's initialize,
+// answered statelessly by the SDK's legacy fallback. Nothing is kept between requests: each one
+// gets a fresh server from the factory.
+//
+//   POST /mcp     the MCP endpoint (GET and DELETE are the 2025 session operations; stateless,
+//                 the SDK answers them 405)
+//   OPTIONS /mcp  CORS preflight, for a browser client on an https Origin
+//   GET /health   liveness. Not /healthz: Cloud Run's front end reserves paths ending in "z"
+//                 and answers them itself, so a /healthz would never reach this process.
+//
+// No auth: the endpoint serves only public data (MCP makes authorization optional), and the
+// server's instructions say what it is. The edge rules — Origin policy, per-client limit, body
+// cap, what is logged — are in httpPolicy.ts, each with its reasoning.
+//
+// The API sees every remote user as the client it is, not as this service: each call carries the
+// client's address and a forward token core-backend checks (runtime.ts; core-backend
+// waf/mcpforward.go, #2212). MCP_REQUIRE_FORWARD_TOKEN=1 (set by deploy-all.sh) makes a missing
+// token fatal at start-up, because without it every remote user would share one API budget.
+import http from "node:http";
+import { createMcpHandler } from "@modelcontextprotocol/server";
+import { forwardToken, markHttpEntrypoint, withClient } from "./runtime.js";
+import { BODY_TOO_LARGE_CODE, DEFAULT_RATE_LIMIT_PER_MIN, FixedWindowLimiter, ORIGIN_REFUSED_CODE, RATE_LIMITED_CODE, bodyFacts, originVerdict, resolveClient, revisionLabel, rpcError, uaFamily, } from "./httpPolicy.js";
+// Must run before index.ts is evaluated: it is how index.ts knows not to start stdio.
+markHttpEntrypoint();
+const { createServer, NAME, VERSION, SHOWN_BASE, TIMEOUT_MS } = await import("./index.js");
+const positiveInt = (v, fallback) => {
+    const n = Number(v);
+    return Number.isInteger(n) && n > 0 ? n : fallback;
+};
+const PORT = (() => {
+    const n = Number(process.env.PORT);
+    return Number.isInteger(n) && n >= 0 && n < 65536 && process.env.PORT !== "" && process.env.PORT !== undefined ? n : 8080;
+})();
+const RATE_LIMIT_PER_MIN = positiveInt(process.env.MCP_RATE_LIMIT_PER_MIN, DEFAULT_RATE_LIMIT_PER_MIN);
+// Tool arguments are a CVE ID or a short search; 64 KiB is far above any real request and far
+// below the SDK's 4 MiB default.
+const MAX_BODY_BYTES = positiveInt(process.env.MCP_MAX_BODY_BYTES, 64 * 1024);
+const MCP_PATH = "/mcp";
+const HEALTH_PATH = "/health";
+// One JSON object per line on stdout: Cloud Logging reads `severity` and `message`.
+function log(severity, message, fields = {}) {
+    process.stdout.write(`${JSON.stringify({ severity, message, ...fields })}\n`);
+}
+if (process.env.MCP_REQUIRE_FORWARD_TOKEN === "1" && !forwardToken()) {
+    log("ERROR", "mcp_remote_refusing_to_start", {
+        reason: "MCP_REQUIRE_FORWARD_TOKEN=1 but ECHELONGRAPH_FORWARD_TOKEN is empty: the API would count every remote user as this one service (#2212)",
+    });
+    process.exit(1);
+}
+const handler = createMcpHandler(createServer, {
+    legacy: "stateless",
+    // responseMode stays the SDK default, "auto": a modern request is answered with one JSON body
+    // unless a handler emits something before its result (none of these tools does). The legacy
+    // leg answers over SSE, as a 2025-era streamable HTTP server does.
+    maxRequestBodySize: MAX_BODY_BYTES,
+    // Names only: an SDK error message can quote what the client sent.
+    onerror: (e) => log("WARNING", "mcp_handler_error", { error_name: e.name }),
+});
+const limiter = new FixedWindowLimiter(RATE_LIMIT_PER_MIN);
+// CORS for a browser client on an https Origin (the Origin policy has already admitted it).
+// A wildcard is safe here because nothing is credentialed: no cookies, no auth.
+const CORS_HEADERS = {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Expose-Headers": "Mcp-Session-Id, MCP-Protocol-Version, Retry-After",
+};
+const PREFLIGHT_HEADERS = {
+    ...CORS_HEADERS,
+    "Access-Control-Allow-Methods": "POST, GET, DELETE, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Accept, MCP-Protocol-Version, Mcp-Method, Mcp-Name, Mcp-Session-Id, Last-Event-ID",
+    "Access-Control-Max-Age": "600",
+};
+const HOP_BY_HOP = new Set(["host", "connection", "content-length", "transfer-encoding", "keep-alive", "upgrade", "expect"]);
+function send(res, status, body, headers = {}) {
+    res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store", ...headers });
+    res.end(body);
+}
+// Reads the body up to MAX_BODY_BYTES. Over the cap: "too_large", and the rest is discarded
+// unread (the response closes the connection).
+function readBody(req) {
+    const declared = Number(req.headers["content-length"]);
+    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+        req.resume();
+        return Promise.resolve("too_large");
+    }
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        let done = false;
+        req.on("data", (chunk) => {
+            if (done)
+                return;
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                done = true;
+                resolve("too_large");
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            if (!done)
+                resolve(Buffer.concat(chunks));
+        });
+        req.on("error", (e) => {
+            if (!done)
+                reject(e);
+        });
+    });
+}
+async function serveMcp(req, res, pathname) {
+    const method = req.method ?? "GET";
+    const origin = req.headers.origin;
+    const verdict = originVerdict(Array.isArray(origin) ? origin.join(", ") : origin);
+    if (!verdict.ok) {
+        send(res, 403, rpcError(ORIGIN_REFUSED_CODE, `Origin refused: ${verdict.reason}. This endpoint serves requests with no Origin or an https Origin.`));
+        return { status: 403, refused: "origin" };
+    }
+    const cors = origin === undefined ? {} : CORS_HEADERS;
+    if (method === "OPTIONS") {
+        res.writeHead(204, PREFLIGHT_HEADERS);
+        res.end();
+        return { status: 204 };
+    }
+    const xff = req.headers["x-forwarded-for"];
+    const client = resolveClient(Array.isArray(xff) ? xff.join(",") : xff, req.socket.remoteAddress);
+    const hit = limiter.hit(client.key);
+    if (!hit.allowed) {
+        send(res, 429, rpcError(RATE_LIMITED_CODE, `Rate limit exceeded: at most ${RATE_LIMIT_PER_MIN} requests per minute per client address. Retry after ${hit.retryAfterSec} s.`, { limit: RATE_LIMIT_PER_MIN, window_seconds: 60, retry_after_seconds: hit.retryAfterSec }), { ...cors, "Retry-After": String(hit.retryAfterSec) });
+        log("WARNING", "mcp_rate_limited", { client: client.key, limit: RATE_LIMIT_PER_MIN });
+        return { status: 429, throttled: true };
+    }
+    let body;
+    if (method === "POST") {
+        const read = await readBody(req);
+        if (read === "too_large") {
+            send(res, 413, rpcError(BODY_TOO_LARGE_CODE, `Request body too large: at most ${MAX_BODY_BYTES} bytes.`), { ...cors, Connection: "close" });
+            return { status: 413, refused: "body_size" };
+        }
+        body = read;
+    }
+    const headers = new Headers();
+    for (const [k, v] of Object.entries(req.headers)) {
+        if (v === undefined || HOP_BY_HOP.has(k))
+            continue;
+        for (const one of Array.isArray(v) ? v : [v])
+            headers.append(k, one);
+    }
+    const abort = new AbortController();
+    res.on("close", () => abort.abort());
+    const request = new Request(`http://localhost${pathname}`, {
+        method,
+        headers,
+        body: body && body.length > 0 ? new Uint8Array(body) : undefined,
+        signal: abort.signal,
+    });
+    const response = await withClient(client.forwardAddress, () => handler.fetch(request));
+    const out = { ...cors };
+    response.headers.forEach((v, k) => {
+        out[k] = v;
+    });
+    res.writeHead(response.status, out);
+    if (response.body) {
+        for await (const chunk of response.body)
+            res.write(chunk);
+    }
+    res.end();
+    return { status: response.status, body };
+}
+const server = http.createServer((req, res) => {
+    const start = process.hrtime.bigint();
+    // The path only: a query string is never read, kept or logged.
+    let pathname = "/";
+    try {
+        pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+    }
+    catch {
+        pathname = "(unparseable)";
+    }
+    const method = req.method ?? "GET";
+    const finish = (o) => {
+        const facts = o.body ? bodyFacts(o.body) : { rpc_method: "(none)" };
+        log("INFO", "mcp_request", {
+            method,
+            path: pathname === MCP_PATH || pathname === HEALTH_PATH ? pathname : "(other)",
+            status: o.status,
+            duration_ms: Number((process.hrtime.bigint() - start) / 1000000n),
+            ...facts,
+            protocol_version: revisionLabel(req.headers["mcp-protocol-version"]),
+            origin_present: req.headers.origin !== undefined,
+            body_bytes: o.body?.length ?? 0,
+            throttled: o.throttled === true,
+            refused: o.refused ?? "",
+            ua_family: uaFamily(req.headers["user-agent"]),
+        });
+    };
+    if (pathname === HEALTH_PATH) {
+        if (method !== "GET" && method !== "HEAD") {
+            send(res, 405, JSON.stringify({ error: "method not allowed" }), { Allow: "GET, HEAD" });
+            return finish({ status: 405 });
+        }
+        send(res, 200, JSON.stringify({ status: "ok", name: NAME, version: VERSION }));
+        return finish({ status: 200 });
+    }
+    if (pathname !== MCP_PATH) {
+        send(res, 404, JSON.stringify({ error: "not found", mcp_endpoint: MCP_PATH }));
+        return finish({ status: 404 });
+    }
+    serveMcp(req, res, pathname).then(finish, (e) => {
+        log("ERROR", "mcp_request_failed", { error_name: e instanceof Error ? e.name : typeof e });
+        if (!res.headersSent)
+            send(res, 500, rpcError(-32603, "Internal error"));
+        else
+            res.end();
+        finish({ status: 500 });
+    });
+});
+server.listen(PORT, () => {
+    const addr = server.address();
+    log("INFO", "mcp_remote_listening", {
+        port: typeof addr === "object" && addr ? addr.port : PORT,
+        name: NAME,
+        version: VERSION,
+        api_base: SHOWN_BASE,
+        api_timeout_ms: TIMEOUT_MS,
+        forward_token_configured: forwardToken() !== "",
+        rate_limit_per_min: RATE_LIMIT_PER_MIN,
+        max_body_bytes: MAX_BODY_BYTES,
+    });
+});
+const shutdown = () => {
+    server.close();
+    void handler.close();
+};
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);

package/dist/httpPolicy.js

@@ -0,0 +1,244 @@
+// The hosted endpoint's edge rules (#2316), kept apart from the server wiring so each can be
+// tested on its own: who the client is, which Origins are served, the per-client limit, and the
+// JSON-RPC error bodies the edge answers with.
+import { isIP } from "node:net";
+// ── JSON-RPC errors from the edge ──
+//
+// Every refusal at the edge is a JSON-RPC error object, never an HTML page and never a bare
+// status: an MCP client parses the body, and a model shown an HTML error page has nothing to say
+// to its user. id is null because the edge answers before it has read (or trusted) the body.
+export const ORIGIN_REFUSED_CODE = -32000; // the SDK's own code for an Origin refusal (originValidationResponse)
+export const RATE_LIMITED_CODE = -32029; // implementation-defined server error range (-32000..-32099); "429"
+export const BODY_TOO_LARGE_CODE = -32600; // Invalid Request
+export function rpcError(code, message, data) {
+    return JSON.stringify({ jsonrpc: "2.0", id: null, error: { code, message, ...(data ? { data } : {}) } });
+}
+export function originVerdict(origin) {
+    if (origin === undefined)
+        return { ok: true };
+    const o = origin.trim();
+    if (o === "")
+        return { ok: false, reason: "an empty Origin header" };
+    if (o.toLowerCase() === "null")
+        return { ok: false, reason: 'the opaque Origin "null"' };
+    if (/[\s,]/.test(o))
+        return { ok: false, reason: "a malformed Origin header (not a single origin)" };
+    let url;
+    try {
+        url = new URL(o);
+    }
+    catch {
+        return { ok: false, reason: "a malformed Origin header" };
+    }
+    if (url.protocol !== "https:")
+        return { ok: false, reason: "a non-https Origin" };
+    // A serialized origin is scheme://host[:port] and nothing else.
+    if (url.username || url.password || `${url.protocol}//${url.host}` !== o.toLowerCase()) {
+        return { ok: false, reason: "a malformed Origin header (not a bare origin)" };
+    }
+    return { ok: true };
+}
+// The eight 16-bit words of an IPv6 literal that net.isIP has already accepted.
+function expandIPv6(s) {
+    // A dotted IPv4 tail ("::ffff:203.0.113.7") is rewritten as its two words first.
+    const lastColon = s.lastIndexOf(":");
+    const v4 = s.slice(lastColon + 1);
+    if (v4.includes(".")) {
+        const o = v4.split(".").map(Number);
+        if (o.length !== 4 || o.some((n) => !Number.isInteger(n) || n < 0 || n > 255))
+            return undefined;
+        s = `${s.slice(0, lastColon + 1)}${((o[0] << 8) | o[1]).toString(16)}:${((o[2] << 8) | o[3]).toString(16)}`;
+    }
+    const parts = s.split("::");
+    if (parts.length > 2)
+        return undefined;
+    const head = parts[0] ? parts[0].split(":") : [];
+    const rest = parts.length === 2 && parts[1] ? parts[1].split(":") : [];
+    const fill = parts.length === 2 ? 8 - head.length - rest.length : 0;
+    if (fill < 0 || (parts.length === 1 && head.length !== 8))
+        return undefined;
+    const words = [...head, ...Array(fill).fill("0"), ...rest].map((h) => parseInt(h, 16));
+    if (words.length !== 8 || words.some((w) => !Number.isInteger(w) || w < 0 || w > 0xffff))
+        return undefined;
+    return words;
+}
+/** One forwarded hop or socket address, parsed with a forwarded hop's tolerances; undefined if it is not an address. */
+export function parseAddress(raw) {
+    if (!raw)
+        return undefined;
+    let s = raw.trim();
+    if (!s)
+        return undefined;
+    // "[2001:db8::1]:443" / "[2001:db8::1]" → the literal; "203.0.113.7:51234" → the address.
+    const bracketed = /^\[([^\]]+)\](?::\d+)?$/.exec(s);
+    if (bracketed)
+        s = bracketed[1];
+    else if (/^[\d.]+:\d+$/.test(s))
+        s = s.slice(0, s.lastIndexOf(":"));
+    const zone = s.indexOf("%");
+    if (zone >= 0)
+        s = s.slice(0, zone);
+    const fam = isIP(s);
+    if (fam === 4)
+        return { family: 4, octets: s.split(".").map(Number), text: s };
+    if (fam !== 6)
+        return undefined;
+    const h = expandIPv6(s.toLowerCase());
+    if (!h)
+        return undefined;
+    // IPv4-mapped (::ffff:a.b.c.d) is the IPv4 address.
+    if (h.slice(0, 5).every((w) => w === 0) && h[5] === 0xffff) {
+        const octets = [h[6] >> 8, h[6] & 0xff, h[7] >> 8, h[7] & 0xff];
+        return { family: 4, octets, text: octets.join(".") };
+    }
+    return { family: 6, hextets: h, text: s.toLowerCase() };
+}
+/** Whether a parsed address is one a client on the public internet could have arrived from (core-backend's publicUnicast). */
+export function isPublic(a) {
+    if (a.family === 4) {
+        const [o0, o1] = a.octets;
+        if (o0 === 0 || o0 === 10 || o0 === 127 || o0 >= 224)
+            return false; // this-network, private, loopback, multicast/reserved/broadcast
+        if (o0 === 169 && o1 === 254)
+            return false; // link-local (the platform's front end)
+        if (o0 === 172 && o1 >= 16 && o1 <= 31)
+            return false;
+        if (o0 === 192 && o1 === 168)
+            return false;
+        return true;
+    }
+    const h = a.hextets;
+    if (h.every((w) => w === 0))
+        return false; // ::
+    if (h.slice(0, 7).every((w) => w === 0) && h[7] === 1)
+        return false; // ::1
+    if ((h[0] & 0xffc0) === 0xfe80)
+        return false; // fe80::/10 link-local
+    if ((h[0] & 0xff00) === 0xff00)
+        return false; // ff00::/8 multicast
+    if ((h[0] & 0xfe00) === 0xfc00)
+        return false; // fc00::/7 unique local
+    return true;
+}
+function keyOf(a) {
+    if (a.family === 4)
+        return a.octets.join(".");
+    return `${a.hextets.slice(0, 4).map((w) => w.toString(16)).join(":")}::/64`;
+}
+/** The client of one request: see the section comment. */
+export function resolveClient(xff, socketAddress) {
+    if (xff) {
+        const hops = xff.split(",");
+        for (let i = hops.length - 1; i >= 0; i--) {
+            const a = parseAddress(hops[i]);
+            if (a && isPublic(a))
+                return { forwardAddress: a.text, key: keyOf(a) };
+        }
+    }
+    const peer = parseAddress(socketAddress);
+    if (!peer)
+        return { key: socketAddress || "(unknown)" };
+    return { forwardAddress: isPublic(peer) ? peer.text : undefined, key: isPublic(peer) ? keyOf(peer) : peer.text };
+}
+// ── Per-client limit ──
+//
+// A fixed one-minute window per client key, in this instance's memory. The default is derived
+// from the public API's own per-client ceiling, not invented: core-backend's WAF admits 600
+// requests a minute per client address on the API's base paths (waf.DefaultTierConfigs
+// ["default"], 10 a second), and the costliest tool here, exposure_radar, makes up to five API
+// calls per MCP request. 600 / 5 = 120 MCP requests a minute keeps one client's heaviest use
+// inside the ceiling the API applies to it (core-backend keys this service's calls on the
+// forwarded client, #2212), so a client meets THIS limit — a JSON-RPC error it can read — before
+// the API's. It is not a tier: it grants nothing the API does not already grant one address.
+//
+// Counted per instance: with Cloud Run's max-instances at N, one client spread over every
+// instance could make N times this many requests a minute here; the API's own ceiling, which
+// is counted fleet-wide, still binds behind it.
+export const DEFAULT_RATE_LIMIT_PER_MIN = 120;
+export class FixedWindowLimiter {
+    max;
+    windowMs;
+    now;
+    maxKeys;
+    windows = new Map();
+    constructor(max, windowMs = 60_000, now = Date.now, maxKeys = 50_000) {
+        this.max = max;
+        this.windowMs = windowMs;
+        this.now = now;
+        this.maxKeys = maxKeys;
+    }
+    hit(key) {
+        const t = this.now();
+        let w = this.windows.get(key);
+        if (!w || t - w.start >= this.windowMs) {
+            if (!w && this.windows.size >= this.maxKeys)
+                this.sweep(t);
+            w = { start: t, count: 0 };
+            this.windows.set(key, w);
+        }
+        if (w.count >= this.max) {
+            return { allowed: false, retryAfterSec: Math.max(1, Math.ceil((w.start + this.windowMs - t) / 1000)) };
+        }
+        w.count++;
+        return { allowed: true, remaining: this.max - w.count };
+    }
+    // Drop expired windows; if every key is live (a flood of distinct addresses), drop the oldest
+    // half rather than grow without bound. Forgetting a key early can only admit, never refuse.
+    sweep(t) {
+        for (const [k, w] of this.windows)
+            if (t - w.start >= this.windowMs)
+                this.windows.delete(k);
+        if (this.windows.size < this.maxKeys)
+            return;
+        let drop = Math.floor(this.windows.size / 2);
+        for (const k of this.windows.keys()) {
+            if (drop-- <= 0)
+                break;
+            this.windows.delete(k);
+        }
+    }
+}
+// ── Bounded access-log fields ──
+//
+// The access line carries no body, no query string, no argument and no client address: only
+// values from small closed sets or shapes, so nothing a client types reaches the log (#1983).
+const RPC_METHOD = /^[a-z][a-z/_]{0,39}$/i;
+const TOOL_NAME = /^[a-z][a-z0-9_]{0,39}$/;
+const REVISION = /^\d{4}-\d{2}-\d{2}$/;
+const UA_FAMILY = /^[A-Za-z0-9._-]{1,40}$/;
+/** The JSON-RPC method and, for tools/call, the tool name, shape-checked; never anything else from the body. */
+export function bodyFacts(body) {
+    if (!body || body.length === 0)
+        return { rpc_method: "(none)" };
+    let parsed;
+    try {
+        parsed = JSON.parse(body.toString("utf8"));
+    }
+    catch {
+        return { rpc_method: "(unparseable)" };
+    }
+    if (Array.isArray(parsed))
+        return { rpc_method: "(batch)" };
+    if (parsed === null || typeof parsed !== "object")
+        return { rpc_method: "(other)" };
+    const m = parsed.method;
+    if (typeof m !== "string")
+        return { rpc_method: "(response)" };
+    if (!RPC_METHOD.test(m))
+        return { rpc_method: "(other)" };
+    if (m !== "tools/call")
+        return { rpc_method: m };
+    const name = parsed.params?.name;
+    return { rpc_method: m, tool: typeof name === "string" && TOOL_NAME.test(name) ? name : "(other)" };
+}
+export function revisionLabel(v) {
+    if (v === undefined)
+        return "(none)";
+    return REVISION.test(v.trim()) ? v.trim() : "(other)";
+}
+export function uaFamily(ua) {
+    if (!ua)
+        return "(none)";
+    const fam = ua.split(/[/\s]/, 1)[0];
+    return UA_FAMILY.test(fam) ? fam : "(other)";
+}