querysub 0.443.0 → 0.447.0

package/src/diagnostics/debugger/mcp-server.ts

@@ -0,0 +1,775 @@
+/**
+ * Node.js debugger MCP server.
+ *
+ * Exposes the V8 inspector / Chrome DevTools Protocol as MCP tools:
+ *
+ *   attach       - connect to a debug target, keep the connection open, and
+ *                  return a short sessionId used by every other tool.
+ *   detach       - close a session.
+ *   listScripts  - list scripts loaded in the target.
+ *   getSource    - get a script's source (optionally a line range).
+ *   evaluate     - run a JavaScript expression in the target.
+ *   logpoint     - install a logpoint and collect its hits.
+ *
+ * Speaks MCP over Streamable HTTP (JSON-RPC 2.0): the client POSTs requests to
+ * /mcp and receives a JSON response. Diagnostics go to stderr.
+ *
+ * Launch:  yarn mcp2   (this project)         — start before Claude connects
+ *          yarn mc2    (the qs-cyoa project, via --cwd)
+ * Config:  point Claude at http://127.0.0.1:<port>/mcp (see .mcp.json)
+ *
+ * Copied from https://github.com/sliftist/debug
+ */
+module.hotreload = false;
+
+import * as http from "http";
+import * as path from "path";
+import * as dns from "dns";
+
+// Allow callers to point this process at a different project root (so we use
+// the right keys/certs/local data, and the default debugger-port.json is
+// looked up there) before any other imports run.
+{
+    let argv = process.argv;
+    let cwdIdx = argv.indexOf("--cwd");
+    if (cwdIdx >= 0 && argv[cwdIdx + 1]) {
+        process.chdir(argv[cwdIdx + 1]);
+        argv.splice(cwdIdx, 2);
+    }
+}
+
+import "../../inject";
+
+import { DebuggerRemote } from "./debugger-remote";
+import { Querysub } from "../../4-querysub/QuerysubController";
+import { getAllNodeIds } from "../../-f-node-discovery/NodeDiscovery";
+import { NodeCapabilitiesController } from "../../-g-core-values/NodeCapabilities";
+import { timeoutToUndefinedSilent } from "../../errors";
+import { getExternalIP } from "../../misc/networking";
+import { getNodeIdDomain } from "socket-function/src/nodeCache";
+
+const DEFAULT_MCP_PORT = 3001;
+const DEFAULT_PORT_FILE = path.join(process.cwd(), "debugger-port.json");
+const PROTOCOL_VERSION = "2025-06-18";
+// Per-node budget for the getEntryPoint / getInspectURL probes in listNodes;
+// a node that doesn't answer in time is reported with those fields undefined.
+const NODE_INFO_TIMEOUT_MS = 5000;
+
+/** Diagnostics go to stderr — stdout is reserved for the JSON-RPC stream. */
+function log(...args: unknown[]): void {
+    console.error("[mcp]", ...args);
+}
+
+/** Read a numeric `--flag value` from argv, falling back to a default. */
+function getPortArg(flag: string, fallback: number): number {
+    let idx = process.argv.indexOf(flag);
+    if (idx >= 0 && process.argv[idx + 1]) {
+        let value = Number(process.argv[idx + 1]);
+        if (Number.isFinite(value)) return value;
+    }
+    return fallback;
+}
+
+// --------------------------------------------------------------------------
+// Session state
+// --------------------------------------------------------------------------
+interface ScriptParsed {
+    scriptId: string;
+    url: string;
+}
+
+interface Session {
+    id: string;
+    remote: DebuggerRemote;
+    scripts: ScriptParsed[];
+}
+
+const sessions = new Map<string, Session>();
+
+function newSessionId(): string {
+    let id: string;
+    do {
+        id = Math.random().toString(36).slice(2, 8);
+    } while (sessions.has(id));
+    return id;
+}
+
+function getSession(id: unknown): Session {
+    if (typeof id !== "string" || !sessions.has(id)) {
+        throw new Error(`Unknown sessionId "${id}". Call "attach" first.`);
+    }
+    return sessions.get(id)!;
+}
+
+const normUrl = (u: string): string => u.replace(/\\/g, "/");
+
+/** A script that belongs to the user's app (not a node internal / dependency). */
+function isUserScript(url: string): boolean {
+    return (
+        (url.startsWith("file://") || url.startsWith("/")) &&
+        !url.includes("node_modules") &&
+        !url.startsWith("node:")
+    );
+}
+
+/** Resolve a script by exact scriptId or by URL substring. */
+function resolveScript(session: Session, query: string): ScriptParsed {
+    const byId = session.scripts.find((s) => s.scriptId === query);
+    if (byId) return byId;
+    const matches = session.scripts.filter((s) => normUrl(s.url).includes(query));
+    if (matches.length === 0) {
+        throw new Error(`No script matches "${query}". Use "listScripts" to see options.`);
+    }
+    return matches.find((s) => normUrl(s.url).endsWith(query)) ?? matches[0];
+}
+
+/**
+ * Open a debugger session on an already-constructed DebuggerRemote: enable the
+ * Runtime + Debugger domains, capture the script list, and register it so the
+ * other tools can find it by sessionId.
+ */
+async function openSession(remote: DebuggerRemote): Promise<Session> {
+    const session: Session = { id: newSessionId(), remote, scripts: [] };
+    // Register before enabling so we capture the initial script dump.
+    remote.on("Debugger.scriptParsed", (p: ScriptParsed) =>
+        session.scripts.push({ scriptId: p.scriptId, url: p.url }),
+    );
+    await remote.send("Runtime.enable");
+    await remote.send("Debugger.enable");
+    sessions.set(session.id, session);
+    return session;
+}
+
+/** Human-readable "Attached. sessionId=… + user scripts" summary for a session. */
+function describeSession(session: Session): string {
+    const userScripts = session.scripts.filter((s) => isUserScript(s.url));
+    return (
+        `Attached. sessionId=${session.id}\n` +
+        `${session.scripts.length} scripts loaded; user scripts:\n` +
+        (userScripts.length
+            ? userScripts.map((s) => `  ${s.scriptId}  ${s.url}`).join("\n")
+            : "  (none)")
+    );
+}
+
+// --------------------------------------------------------------------------
+// Querysub node discovery
+// --------------------------------------------------------------------------
+interface NodeInfo {
+    nodeId: string;
+    /** The node's process entry point (process.argv[1]); undefined if it did not answer. */
+    entryPoint?: string;
+    /** The node's V8 inspector / devtools URL; undefined if it did not answer. */
+    inspectUrl?: string;
+}
+
+/** Discover every node in the Querysub cluster and probe each for debug info. */
+async function getNodeInfos(): Promise<NodeInfo[]> {
+    const nodes = await getAllNodeIds();
+    return Promise.all(
+        nodes.map(async (nodeId): Promise<NodeInfo> => {
+            const [entryPoint, inspectUrl] = await Promise.all([
+                timeoutToUndefinedSilent(
+                    NODE_INFO_TIMEOUT_MS,
+                    NodeCapabilitiesController.nodes[nodeId].getEntryPoint(),
+                ),
+                timeoutToUndefinedSilent(
+                    NODE_INFO_TIMEOUT_MS,
+                    NodeCapabilitiesController.nodes[nodeId].getInspectURL(),
+                ),
+            ]);
+            return { nodeId, entryPoint, inspectUrl };
+        }),
+    );
+}
+
+/**
+ * Pull the CDP WebSocket coordinates out of a devtools inspect URL — the kind
+ * returned by getInspectURL() / exposeExternalDebugPortOnce(), which embed the
+ * inspector endpoint as a `ws=host:port/<uuid>` query parameter.
+ */
+function parseInspectWs(inspectUrl: string): { host: string; port: number; uuidPath: string } {
+    const wsParam = new URL(inspectUrl).searchParams.get("ws");
+    if (!wsParam) {
+        throw new Error(`Inspect URL has no "ws" parameter: ${inspectUrl}`);
+    }
+    const inner = new URL(`ws://${wsParam}`);
+    return { host: inner.hostname, port: Number(inner.port), uuidPath: inner.pathname };
+}
+
+interface AttachNodeResult {
+    session: Session;
+    mode: "local" | "remote";
+    detail: string;
+}
+
+/**
+ * Attach to a Querysub cluster node by nodeId, returning a normal debugger
+ * session usable by every other tool.
+ *
+ * The node's domain is DNS-resolved and compared to our own external IP:
+ *  - same IP  -> the node is on this machine; attach straight to its V8
+ *                inspector on 127.0.0.1, no external exposure needed.
+ *  - other IP -> the node is remote; ask it to open a one-time external debug
+ *                port locked to our IP (exposeExternalDebugPortOnce) and attach
+ *                through that forwarded port.
+ */
+async function attachToNode(nodeId: string): Promise<AttachNodeResult> {
+    const nodeDomain = getNodeIdDomain(nodeId);
+    const [nodeLookup, ourIPRaw] = await Promise.all([
+        dns.promises.lookup(nodeDomain),
+        getExternalIP(),
+    ]);
+    const nodeIP = nodeLookup.address;
+    const ourIP = ourIPRaw.trim();
+
+    let wsUrl: string;
+    let mode: "local" | "remote";
+    let detail: string;
+
+    if (nodeIP === ourIP) {
+        // Same machine — the inspector is reachable directly on localhost.
+        mode = "local";
+        const inspectUrl = await NodeCapabilitiesController.nodes[nodeId].getInspectURL();
+        const { host, port, uuidPath } = parseInspectWs(inspectUrl);
+        wsUrl = `ws://${host}:${port}${uuidPath}`;
+        detail =
+            `${nodeId}\nlocal node (${nodeDomain} -> ${nodeIP}, our IP); ` +
+            `attaching directly to inspector ${host}:${port}`;
+    } else {
+        // Remote machine — have the node forward its inspector port to a
+        // one-time external port locked to our IP.
+        mode = "remote";
+        const { externalPort, internalPort, internalInspectURL } =
+            await NodeCapabilitiesController.nodes[nodeId].exposeExternalDebugPortOnce(ourIP);
+        const { uuidPath } = parseInspectWs(internalInspectURL);
+        wsUrl = `ws://${nodeIP}:${externalPort}${uuidPath}`;
+        detail =
+            `${nodeId}\nremote node (${nodeDomain} -> ${nodeIP}); ` +
+            `forwarded ${nodeIP}:${externalPort} -> 127.0.0.1:${internalPort} for our IP ${ourIP}`;
+    }
+
+    const session = await openSession(new DebuggerRemote({ wsUrl }));
+    return { session, mode, detail };
+}
+
+// --------------------------------------------------------------------------
+// Tools
+// --------------------------------------------------------------------------
+interface ToolDef {
+    description: string;
+    inputSchema: object;
+    handler: (args: any) => Promise<string>;
+}
+
+const tools: Record<string, ToolDef> = {
+    listNodes: {
+        description:
+            "List every node in the Querysub cluster, with each node's process " +
+            "entry point and V8 inspector (devtools) URL. Returns an array of " +
+            "{ nodeId, entryPoint, inspectUrl }. A node that does not answer in " +
+            "time has entryPoint / inspectUrl left undefined. Use a node's " +
+            "inspectUrl to point the `attach` tool at it for debugging.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+        handler: async () => {
+            const infos = await getNodeInfos();
+            return JSON.stringify(infos, null, 2);
+        },
+    },
+
+    attachNode: {
+        description:
+            "Attach to a Querysub cluster node by its nodeId (from listNodes) " +
+            "and return a sessionId usable by every other tool. Works out " +
+            "whether the node is on this machine or remote — a local node is " +
+            "debugged directly; a remote node is reached by asking it to open a " +
+            "one-time external debug port locked to this machine's IP. Prefer " +
+            "this over `attach` when working with cluster nodes.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                nodeId: {
+                    type: "string",
+                    description: "A cluster nodeId, e.g. one returned by the listNodes tool.",
+                },
+            },
+            required: ["nodeId"],
+        },
+        handler: async (args) => {
+            if (typeof args.nodeId !== "string" || !args.nodeId.trim()) {
+                throw new Error("nodeId must be a non-empty string.");
+            }
+            const { session, mode, detail } = await attachToNode(args.nodeId);
+            log(`attachNode ${args.nodeId} -> session ${session.id} (${mode})`);
+            return `${detail}\n\n${describeSession(session)}`;
+        },
+    },
+
+    attach: {
+        description:
+            "Attach to a running Node.js process over its V8 inspector (debugger) " +
+            "port. Keeps the connection open and returns a short sessionId for use " +
+            "by every other tool. Provide one of portFile / port / wsUrl; defaults " +
+            "to the ./debugger-port.json written by test.ts. Retries for ~10s if " +
+            "the target is not listening yet.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                portFile: {
+                    type: "string",
+                    description: "Path to a debugger-port.json file. Default: ./debugger-port.json",
+                },
+                port: { type: "number", description: "Inspector HTTP port (alternative to portFile)." },
+                wsUrl: { type: "string", description: "Direct CDP WebSocket URL (alternative to portFile/port)." },
+            },
+        },
+        handler: async (args) => {
+            let remote: DebuggerRemote;
+            if (typeof args.wsUrl === "string") {
+                remote = new DebuggerRemote({ wsUrl: args.wsUrl });
+            } else if (typeof args.port === "number") {
+                remote = new DebuggerRemote({ port: args.port });
+            } else {
+                remote = new DebuggerRemote({ portFile: args.portFile ?? DEFAULT_PORT_FILE });
+            }
+            const session = await openSession(remote);
+            log(`attached session ${session.id} (${session.scripts.length} scripts)`);
+            return describeSession(session);
+        },
+    },
+
+    detach: {
+        description: "Close a debugger session and disconnect from the target.",
+        inputSchema: {
+            type: "object",
+            properties: { sessionId: { type: "string" } },
+            required: ["sessionId"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            session.remote.close();
+            sessions.delete(session.id);
+            log(`detached session ${session.id}`);
+            return `Detached session ${session.id}.`;
+        },
+    },
+
+    listScripts: {
+        description:
+            "List scripts loaded in the target process. By default only user " +
+            "scripts are shown; pass includeInternal=true for node internals and " +
+            "dependencies. Optionally filter by a URL substring.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sessionId: { type: "string" },
+                filter: { type: "string", description: "Only show scripts whose URL contains this substring." },
+                includeInternal: {
+                    type: "boolean",
+                    description: "Include node_modules / node: internal scripts. Default false.",
+                },
+            },
+            required: ["sessionId"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            let list = session.scripts;
+            if (!args.includeInternal) list = list.filter((s) => isUserScript(s.url));
+            if (typeof args.filter === "string") {
+                list = list.filter((s) => normUrl(s.url).includes(args.filter));
+            }
+            if (!list.length) return "(no matching scripts)";
+            return list.map((s) => `${s.scriptId}\t${s.url}`).join("\n");
+        },
+    },
+
+    getSource: {
+        description:
+            "Get the source of a script in the target — the exact source V8 is " +
+            "running. Optionally restrict to a 1-based inclusive line range. The " +
+            "line numbers shown here are the ones the logpoint tool expects.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sessionId: { type: "string" },
+                script: {
+                    type: "string",
+                    description: "A scriptId, or a substring of the script URL (e.g. \"test.ts\").",
+                },
+                startLine: { type: "number", description: "First line, 1-based inclusive. Default 1." },
+                endLine: { type: "number", description: "Last line, 1-based inclusive. Default: end of file." },
+            },
+            required: ["sessionId", "script"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            const script = resolveScript(session, String(args.script));
+            const res = await session.remote.send("Debugger.getScriptSource", {
+                scriptId: script.scriptId,
+            });
+            const lines = String(res.scriptSource).split("\n");
+            const start = Math.max(1, Math.floor(args.startLine ?? 1));
+            const end = Math.min(lines.length, Math.floor(args.endLine ?? lines.length));
+            const body = lines
+                .slice(start - 1, end)
+                .map((line, i) => `${start + i}\t${line}`)
+                .join("\n");
+            return `${script.url}\nlines ${start}-${end} of ${lines.length}:\n${body}`;
+        },
+    },
+
+    evaluate: {
+        description:
+            "Evaluate a JavaScript expression inside the target process and return " +
+            "the result. Runs in the global context and awaits promises. Tip: " +
+            "`process.exit(0)` cleanly terminates the target.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sessionId: { type: "string" },
+                expression: { type: "string", description: "JavaScript expression to evaluate." },
+            },
+            required: ["sessionId", "expression"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            if (typeof args.expression !== "string") {
+                throw new Error("expression must be a string");
+            }
+            const value = await session.remote.evaluate(args.expression);
+            return value === undefined
+                ? "undefined (or non-serializable result)"
+                : JSON.stringify(value, null, 2);
+        },
+    },
+
+    logpoint: {
+        description:
+            "Install a logpoint: a breakpoint that logs but never pauses the " +
+            "target. Specify the script, a 1-based lineNumber (matching getSource " +
+            "output), and logExpression — JS expression(s) to log when the line is " +
+            "hit, e.g. \"state.iterations\" or \"'iter', state.iterations\". Pass an " +
+            "optional condition — a JS boolean expression — to make it a " +
+            "conditional logpoint: it logs (and counts a hit) only when condition " +
+            "is truthy, e.g. \"String(state.iterations).endsWith('11')\". The " +
+            "server injects a unique id to track this logpoint's hits. Returns " +
+            "after hitLimit hits OR timeoutMs, whichever comes first, then removes " +
+            "the breakpoint.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sessionId: { type: "string" },
+                script: { type: "string", description: "scriptId or URL substring." },
+                lineNumber: {
+                    type: "number",
+                    description: "1-based line to set the logpoint on (matches getSource output).",
+                },
+                logExpression: {
+                    type: "string",
+                    description: "JS expression(s) to log when the line is hit.",
+                },
+                condition: {
+                    type: "string",
+                    description:
+                        "Optional JS boolean expression; the logpoint only logs / counts a hit " +
+                        "when it is truthy. Omit to log on every hit.",
+                },
+                hitLimit: { type: "number", description: "Return after this many hits. Default 5." },
+                timeoutMs: {
+                    type: "number",
+                    description: "Return after this many ms even if hitLimit is not reached. Default 10000.",
+                },
+            },
+            required: ["sessionId", "script", "lineNumber", "logExpression"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            const remote = session.remote;
+            const script = resolveScript(session, String(args.script));
+
+            const lineNumber = Math.floor(args.lineNumber);
+            if (!(lineNumber >= 1)) {
+                throw new Error("lineNumber must be a positive integer (1-based).");
+            }
+            if (typeof args.logExpression !== "string" || !args.logExpression.trim()) {
+                throw new Error("logExpression must be a non-empty string.");
+            }
+            const hitLimit = Math.max(1, Math.floor(args.hitLimit ?? 5));
+            const timeoutMs = Math.max(1, Math.floor(args.timeoutMs ?? 60_000));
+
+            // Unique id injected as the first logged argument, so we can tell
+            // this logpoint's output apart from all other console activity.
+            if (args.condition !== undefined && typeof args.condition !== "string") {
+                throw new Error("condition must be a string if provided.");
+            }
+            // Optional guard: only log (and only count a hit) when this user
+            // expression is truthy — i.e. a conditional logpoint.
+            const guard =
+                typeof args.condition === "string" && args.condition.trim()
+                    ? `(${args.condition})`
+                    : "true";
+
+            const uid = "lp_" + Math.random().toString(36).slice(2, 10);
+            const idLit = JSON.stringify(uid);
+            // An IIFE that always returns false: the breakpoint logs but never
+            // pauses, and a throwing condition/logExpression is reported, not fatal.
+            const condition =
+                `(function(){try{if(${guard}){console.log(${idLit},${args.logExpression})}}` +
+                `catch(e){console.log(${idLit},"<<error>>",String(e))}return false})()`;
+
+            const hits: unknown[][] = [];
+            let resolveWait: () => void = () => { };
+            const waiter = new Promise<void>((resolve) => {
+                resolveWait = resolve;
+            });
+            const off = remote.on("Runtime.consoleAPICalled", (p: any) => {
+                const callArgs = p.args ?? [];
+                if (callArgs[0]?.value !== uid) return; // not this logpoint
+                hits.push(callArgs.slice(1).map((a: any) => a.value));
+                if (hits.length >= hitLimit) resolveWait();
+            });
+
+            const setRes = await remote.send("Debugger.setBreakpointByUrl", {
+                url: script.url,
+                lineNumber: lineNumber - 1,
+                condition,
+            });
+            const locations: any[] = setRes.locations ?? [];
+            const bound = locations.length > 0;
+
+            let timedOut = false;
+            if (bound) {
+                const timer = setTimeout(() => {
+                    timedOut = true;
+                    resolveWait();
+                }, timeoutMs);
+                await waiter;
+                clearTimeout(timer);
+            }
+            off();
+            await remote
+                .send("Debugger.removeBreakpoint", { breakpointId: setRes.breakpointId })
+                .catch(() => { });
+
+            if (!bound) {
+                return (
+                    `Logpoint did NOT bind: line ${lineNumber} of ${script.url} has ` +
+                    `no executable code. Pick a line with a statement (see getSource).`
+                );
+            }
+
+            const actualLine = locations[0].lineNumber + 1;
+            const header =
+                `Logpoint id=${uid} on ${script.url}:${actualLine}` +
+                (actualLine !== lineNumber ? ` (requested ${lineNumber})` : "") +
+                `\n${hits.length} hit(s) — ` +
+                (timedOut
+                    ? `timed out after ${timeoutMs}ms (limit ${hitLimit})`
+                    : `reached limit ${hitLimit}`) +
+                ":";
+            const body = hits.length
+                ? hits
+                    .map((h, i) => `  #${i + 1}  ${h.map((v) => JSON.stringify(v)).join(", ")}`)
+                    .join("\n")
+                : "  (no hits)";
+            return `${header}\n${body}`;
+        },
+    },
+};
+
+// --------------------------------------------------------------------------
+// MCP / JSON-RPC over Streamable HTTP
+// --------------------------------------------------------------------------
+const PORT = getPortArg("--mcp-port", DEFAULT_MCP_PORT);
+
+/** Handle one JSON-RPC message; return the response, or null for a notification. */
+async function handleMessage(msg: any): Promise<object | null> {
+    const id = msg?.id;
+    const method = msg?.method;
+    const isRequest = id !== undefined && id !== null;
+
+    try {
+        if (method === "initialize") {
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: {
+                    protocolVersion:
+                        typeof msg.params?.protocolVersion === "string"
+                            ? msg.params.protocolVersion
+                            : PROTOCOL_VERSION,
+                    capabilities: { tools: {} },
+                    serverInfo: { name: "node-debugger", version: "1.0.0" },
+                },
+            };
+        }
+        if (method === "ping") {
+            return { jsonrpc: "2.0", id, result: {} };
+        }
+        if (method === "tools/list") {
+            return {
+                jsonrpc: "2.0",
+                id,
+                result: {
+                    tools: Object.entries(tools).map(([name, t]) => ({
+                        name,
+                        description: t.description,
+                        inputSchema: t.inputSchema,
+                    })),
+                },
+            };
+        }
+        if (method === "tools/call") {
+            const name = msg.params?.name;
+            const tool = tools[name];
+            if (!tool) {
+                log(`call "${name}" rejected — unknown tool`);
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        content: [{ type: "text", text: `Unknown tool "${name}"` }],
+                        isError: true,
+                    },
+                };
+            }
+            const args = msg.params?.arguments ?? {};
+            const startedAt = Date.now();
+            log(`call "${name}" start`, JSON.stringify(args));
+            try {
+                const text = await tool.handler(args);
+                log(`call "${name}" finish — ok (${Date.now() - startedAt}ms)`);
+                return { jsonrpc: "2.0", id, result: { content: [{ type: "text", text }] } };
+            } catch (err: any) {
+                log(`call "${name}" finish — error (${Date.now() - startedAt}ms):`, err?.stack ?? err);
+                return {
+                    jsonrpc: "2.0",
+                    id,
+                    result: {
+                        content: [{ type: "text", text: `Error: ${err?.message ?? err}` }],
+                        isError: true,
+                    },
+                };
+            }
+        }
+        if (isRequest) {
+            // A request we don't implement.
+            return {
+                jsonrpc: "2.0",
+                id,
+                error: { code: -32601, message: `Method not found: ${method}` },
+            };
+        }
+        // A notification (e.g. notifications/initialized) — no response.
+        return null;
+    } catch (err: any) {
+        if (isRequest) {
+            return {
+                jsonrpc: "2.0",
+                id,
+                error: { code: -32603, message: String(err?.message ?? err) },
+            };
+        }
+        return null;
+    }
+}
+
+function readBody(req: http.IncomingMessage): Promise<string> {
+    return new Promise((resolve, reject) => {
+        let body = "";
+        req.setEncoding("utf8");
+        req.on("data", (chunk) => (body += chunk));
+        req.on("end", () => resolve(body));
+        req.on("error", reject);
+    });
+}
+
+const httpServer = http.createServer(async (req, res) => {
+    const url = (req.url ?? "").split("?")[0];
+
+    // The single MCP endpoint. A GET would open a server->client SSE stream;
+    // this server never initiates messages, so only POST is supported.
+    if (req.method === "POST" && (url === "/mcp" || url === "/")) {
+        let parsed: any;
+        try {
+            parsed = JSON.parse(await readBody(req));
+        } catch {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(
+                JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: null,
+                    error: { code: -32700, message: "Parse error" },
+                }),
+            );
+            return;
+        }
+
+        const batch = Array.isArray(parsed);
+        const messages = batch ? parsed : [parsed];
+        const responses: object[] = [];
+        for (const m of messages) {
+            const response = await handleMessage(m);
+            if (response) responses.push(response);
+        }
+
+        // Only notifications were sent — nothing to return.
+        if (responses.length === 0) {
+            res.writeHead(202);
+            res.end();
+            return;
+        }
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(batch ? responses : responses[0]));
+        return;
+    }
+
+    if ((req.method === "GET" || req.method === "DELETE") && (url === "/mcp" || url === "/")) {
+        res.writeHead(405, { Allow: "POST", "Content-Type": "text/plain" });
+        res.end("Method Not Allowed — POST JSON-RPC to /mcp");
+        return;
+    }
+
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Not Found");
+});
+
+function shutdown(code: number): void {
+    for (const session of sessions.values()) {
+        try {
+            session.remote.close();
+        } catch {
+            // ignore
+        }
+    }
+    httpServer.close();
+    process.exit(code);
+}
+
+process.on("SIGINT", () => shutdown(0));
+process.on("SIGTERM", () => shutdown(0));
+
+async function main(): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+        httpServer.once("error", reject);
+        httpServer.listen(PORT, "127.0.0.1", () => {
+            log(`node-debugger MCP server listening on http://127.0.0.1:${PORT}/mcp`);
+            log("cwd:", process.cwd());
+            log("tools:", Object.keys(tools).join(", "));
+            resolve();
+        });
+    });
+
+    // Join the Querysub cluster so the listNodes tool can discover peers and
+    // probe them via NodeCapabilitiesController.
+    await Querysub.hostService("MCPDebugger");
+    log("joined Querysub cluster as MCPDebugger");
+}
+
+main().catch((err) => {
+    log("fatal:", (err as Error)?.stack ?? err);
+    process.exit(1);
+});