@beeeeen/mcp-probe 0.1.0

package/dist/client/stdio.d.ts

@@ -0,0 +1,55 @@
+import type { Transport } from './transport.js';
+import { type JsonRpcResponse } from './jsonrpc.js';
+export interface StdioOptions {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+}
+/**
+ * Newline-delimited JSON-RPC over a child process's stdio.
+ *
+ * Deliberately hand-rolled rather than built on the official SDK: the SDK
+ * discards anything it cannot parse, and the unparseable bytes are exactly
+ * what we are here to find. A single stray `console.log` in a server puts a
+ * non-JSON line on stdout, which corrupts the stream for every client that
+ * connects to it -- and the server author never sees an error.
+ */
+export declare class StdioTransport implements Transport {
+    private opts;
+    readonly kind = "stdio";
+    readonly target: string;
+    private child;
+    private buffer;
+    private nextId;
+    private pending;
+    private exited;
+    /** stdout lines that were not valid JSON. Almost always a logging bug. */
+    readonly stdoutNoise: string[];
+    readonly stderr: string[];
+    /** Pipe faults (EPIPE and friends) seen after the child went away. */
+    readonly pipeErrors: string[];
+    /** Notifications the server pushed at us, kept for later assertions. */
+    readonly serverNotifications: JsonRpcResponse[];
+    constructor(opts: StdioOptions);
+    start(): Promise<void>;
+    private onStdout;
+    private consumeLine;
+    request(method: string, params?: unknown, timeoutMs?: number): Promise<JsonRpcResponse>;
+    /** Send a request with a caller-chosen id/shape, for malformed-input probes. */
+    requestRaw(payload: Record<string, unknown>, id: number | string, method: string, timeoutMs?: number): Promise<JsonRpcResponse>;
+    private send;
+    notify(method: string, params?: unknown): void;
+    /**
+     * Write bytes verbatim. Used to test how the server handles garbage, and the
+     * single choke point for every unsolicited write, so a dead pipe is handled
+     * in exactly one place.
+     */
+    writeRaw(text: string): void;
+    isAlive(): boolean;
+    exitInfo(): {
+        code: number | null;
+        signal: string | null;
+    } | null;
+    close(): Promise<void>;
+}

package/dist/client/stdio.js

@@ -0,0 +1,213 @@
+import { spawn } from 'node:child_process';
+import { TimeoutError, TransportClosedError } from './jsonrpc.js';
+/**
+ * Newline-delimited JSON-RPC over a child process's stdio.
+ *
+ * Deliberately hand-rolled rather than built on the official SDK: the SDK
+ * discards anything it cannot parse, and the unparseable bytes are exactly
+ * what we are here to find. A single stray `console.log` in a server puts a
+ * non-JSON line on stdout, which corrupts the stream for every client that
+ * connects to it -- and the server author never sees an error.
+ */
+export class StdioTransport {
+    opts;
+    kind = 'stdio';
+    target;
+    child = null;
+    buffer = '';
+    nextId = 1;
+    pending = new Map();
+    exited = null;
+    /** stdout lines that were not valid JSON. Almost always a logging bug. */
+    stdoutNoise = [];
+    stderr = [];
+    /** Pipe faults (EPIPE and friends) seen after the child went away. */
+    pipeErrors = [];
+    /** Notifications the server pushed at us, kept for later assertions. */
+    serverNotifications = [];
+    constructor(opts) {
+        this.opts = opts;
+        this.target = [opts.command, ...opts.args].join(' ');
+    }
+    async start() {
+        // On Windows, a bare command name often resolves to a .cmd shim -- npx,
+        // pnpm, yarn all do -- and CreateProcess cannot execute those directly, so
+        // they need a shell. A path to a real executable must NOT go through the
+        // shell, because cmd.exe splits it on spaces and
+        // "C:\Program Files\nodejs\node.exe" becomes "C:\Program".
+        const isWin = process.platform === 'win32';
+        const hasPathSeparator = /[\\/]/.test(this.opts.command);
+        const isExe = /\.(exe|com)$/i.test(this.opts.command);
+        const useShell = isWin && !hasPathSeparator && !isExe;
+        // When the shell is in play it re-parses the whole line, so anything
+        // containing whitespace has to carry its own quotes.
+        const quote = (s) => (useShell && /[\s"^&|<>]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s);
+        const child = spawn(quote(this.opts.command), this.opts.args.map(quote), {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: { ...process.env, ...this.opts.env },
+            cwd: this.opts.cwd,
+            shell: useShell,
+            windowsVerbatimArguments: useShell,
+        });
+        this.child = child;
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => this.onStdout(chunk));
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => {
+            for (const line of chunk.split('\n'))
+                if (line.trim())
+                    this.stderr.push(line);
+        });
+        // Writing to a pipe whose far end has gone emits EPIPE on the stream. With
+        // no listener Node promotes that to an uncaught exception, which would
+        // crash mcp-probe instead of reporting the dead server -- and the whole
+        // contract here is that a broken server produces a report, not a crash.
+        // Whether the write or the exit lands first is a race, so this shows up
+        // on some platforms and not others.
+        const swallow = (e) => {
+            this.pipeErrors.push(e.message);
+        };
+        child.stdin.on('error', swallow);
+        child.stdout.on('error', swallow);
+        child.stderr.on('error', swallow);
+        child.on('exit', (code, signal) => {
+            this.exited = { code, signal };
+            const err = new TransportClosedError(`Server exited (code ${code ?? 'null'}${signal ? `, signal ${signal}` : ''}) with ${this.pending.size} request(s) in flight`, code, this.stderr.slice(-20).join('\n'));
+            for (const [, p] of this.pending) {
+                clearTimeout(p.timer);
+                p.reject(err);
+            }
+            this.pending.clear();
+        });
+        await new Promise((resolve, reject) => {
+            const onError = (e) => reject(new TransportClosedError(`Failed to spawn \`${this.target}\`: ${e.message}`));
+            child.once('error', onError);
+            // Give spawn a tick to fail loudly; a server that dies later is caught
+            // by the in-flight rejection above.
+            setTimeout(() => {
+                child.off('error', onError);
+                resolve();
+            }, 50);
+        });
+    }
+    onStdout(chunk) {
+        this.buffer += chunk;
+        let idx;
+        while ((idx = this.buffer.indexOf('\n')) !== -1) {
+            const line = this.buffer.slice(0, idx).replace(/\r$/, '');
+            this.buffer = this.buffer.slice(idx + 1);
+            if (!line.trim())
+                continue;
+            this.consumeLine(line);
+        }
+    }
+    consumeLine(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            // Not JSON. Record it and keep going -- we want the full list, not just
+            // the first one, so the report can show the author every offending line.
+            if (this.stdoutNoise.length < 50)
+                this.stdoutNoise.push(line);
+            return;
+        }
+        if (msg && typeof msg === 'object' && msg.id !== undefined && msg.id !== null) {
+            const waiter = this.pending.get(msg.id);
+            if (waiter) {
+                clearTimeout(waiter.timer);
+                this.pending.delete(msg.id);
+                waiter.resolve(msg);
+                return;
+            }
+        }
+        // No id, or an id nobody is waiting on: a notification or a stray reply.
+        this.serverNotifications.push(msg);
+    }
+    request(method, params, timeoutMs = 10_000) {
+        const id = this.nextId++;
+        return this.send({ jsonrpc: '2.0', id, method, ...(params !== undefined ? { params } : {}) }, id, method, timeoutMs);
+    }
+    /** Send a request with a caller-chosen id/shape, for malformed-input probes. */
+    requestRaw(payload, id, method, timeoutMs = 10_000) {
+        return this.send(payload, id, method, timeoutMs);
+    }
+    send(payload, id, method, timeoutMs) {
+        if (!this.child || this.exited) {
+            return Promise.reject(new TransportClosedError(`Server is not running (exit code ${this.exited?.code ?? 'unknown'})`, this.exited?.code ?? null, this.stderr.slice(-20).join('\n')));
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new TimeoutError(method, timeoutMs));
+            }, timeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+            const failWrite = (message) => {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                reject(new TransportClosedError(`Write to stdin failed: ${message}`));
+            };
+            // write() reports asynchronously through the callback, but it can also
+            // throw synchronously once the stream is destroyed.
+            try {
+                this.child.stdin.write(JSON.stringify(payload) + '\n', (err) => {
+                    if (err)
+                        failWrite(err.message);
+                });
+            }
+            catch (e) {
+                failWrite(e.message);
+            }
+        });
+    }
+    notify(method, params) {
+        this.writeRaw(JSON.stringify({ jsonrpc: '2.0', method, ...(params !== undefined ? { params } : {}) }) + '\n');
+    }
+    /**
+     * Write bytes verbatim. Used to test how the server handles garbage, and the
+     * single choke point for every unsolicited write, so a dead pipe is handled
+     * in exactly one place.
+     */
+    writeRaw(text) {
+        if (!this.child || this.exited || !this.child.stdin.writable)
+            return;
+        try {
+            this.child.stdin.write(text);
+        }
+        catch (e) {
+            // The child can exit between the liveness check and the write landing.
+            this.pipeErrors.push(e.message);
+        }
+    }
+    isAlive() {
+        return this.child !== null && this.exited === null;
+    }
+    exitInfo() {
+        return this.exited;
+    }
+    async close() {
+        for (const [, p] of this.pending)
+            clearTimeout(p.timer);
+        this.pending.clear();
+        const child = this.child;
+        if (!child || this.exited)
+            return;
+        try {
+            child.stdin.end();
+        }
+        catch {
+            /* Pipe already torn down; there is nothing left to close. */
+        }
+        await new Promise((resolve) => {
+            const t = setTimeout(() => {
+                child.kill('SIGKILL');
+                resolve();
+            }, 1500);
+            child.once('exit', () => {
+                clearTimeout(t);
+                resolve();
+            });
+        });
+    }
+}

package/dist/client/transport.d.ts

@@ -0,0 +1,21 @@
+import type { JsonRpcResponse } from './jsonrpc.js';
+/** The surface the checks are written against, so they work over stdio or HTTP. */
+export interface Transport {
+    readonly kind: 'stdio' | 'http';
+    readonly target: string;
+    /** stdout lines that were not valid JSON (stdio only; empty for HTTP). */
+    readonly stdoutNoise: string[];
+    readonly stderr: string[];
+    readonly serverNotifications: JsonRpcResponse[];
+    start(): Promise<void>;
+    request(method: string, params?: unknown, timeoutMs?: number): Promise<JsonRpcResponse>;
+    requestRaw(payload: Record<string, unknown>, id: number | string, method: string, timeoutMs?: number): Promise<JsonRpcResponse>;
+    notify(method: string, params?: unknown): void;
+    writeRaw(text: string): void;
+    isAlive(): boolean;
+    exitInfo(): {
+        code: number | null;
+        signal: string | null;
+    } | null;
+    close(): Promise<void>;
+}

package/dist/client/transport.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { run, exitCodeFor, DEFAULT_OPTIONS, type TargetSpec } from './run.js';
+export { renderTerminal } from './report/terminal.js';
+export { renderJUnit } from './report/junit.js';
+export { allChecks, selectChecks, protocolChecks, schemaChecks, robustnessChecks, hygieneChecks } from './checks/index.js';
+export { McpClient, StdioTransport, HttpTransport, SUPPORTED_PROTOCOL_VERSIONS } from './client/index.js';
+export type { Transport } from './client/transport.js';
+export type { Check, CheckContext, CheckResult, JsonSchema, RunOptions, RunReport, Severity, Status, ToolDef, } from './types.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { run, exitCodeFor, DEFAULT_OPTIONS } from './run.js';
+export { renderTerminal } from './report/terminal.js';
+export { renderJUnit } from './report/junit.js';
+export { allChecks, selectChecks, protocolChecks, schemaChecks, robustnessChecks, hygieneChecks } from './checks/index.js';
+export { McpClient, StdioTransport, HttpTransport, SUPPORTED_PROTOCOL_VERSIONS } from './client/index.js';

package/dist/report/junit.d.ts

@@ -0,0 +1,7 @@
+import type { RunReport } from '../types.js';
+/**
+ * JUnit XML, which every CI provider can render as a test report.
+ * Warnings are emitted as passing cases carrying a `system-out` note so they
+ * are visible without turning the build red.
+ */
+export declare function renderJUnit(report: RunReport): string;

package/dist/report/junit.js

@@ -0,0 +1,60 @@
+function esc(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        // Control characters are illegal in XML 1.0 and make parsers reject the
+        // whole file -- and server output is exactly where they show up.
+        .replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '');
+}
+/**
+ * JUnit XML, which every CI provider can render as a test report.
+ * Warnings are emitted as passing cases carrying a `system-out` note so they
+ * are visible without turning the build red.
+ */
+export function renderJUnit(report) {
+    const { results, summary, server } = report;
+    const name = server.name ? `mcp-probe/${server.name}` : 'mcp-probe';
+    const lines = [];
+    lines.push('<?xml version="1.0" encoding="UTF-8"?>');
+    lines.push(`<testsuites name="${esc(name)}" tests="${results.length}" failures="${summary.fail}" skipped="${summary.skip}" time="${(report.durationMs / 1000).toFixed(3)}">`);
+    lines.push(`  <testsuite name="${esc(name)}" tests="${results.length}" failures="${summary.fail}" skipped="${summary.skip}" time="${(report.durationMs / 1000).toFixed(3)}">`);
+    lines.push(`    <properties>`);
+    lines.push(`      <property name="target" value="${esc(server.target)}"/>`);
+    if (server.protocolVersion)
+        lines.push(`      <property name="protocolVersion" value="${esc(server.protocolVersion)}"/>`);
+    if (server.version)
+        lines.push(`      <property name="serverVersion" value="${esc(server.version)}"/>`);
+    lines.push(`    </properties>`);
+    for (const r of results) {
+        const cls = r.id.split('.')[0] ?? 'mcp-probe';
+        const caseName = r.target ? `${r.title} (${r.target})` : r.title;
+        const attrs = `classname="${esc(cls)}" name="${esc(caseName)}"${r.ms !== undefined ? ` time="${(r.ms / 1000).toFixed(3)}"` : ''}`;
+        const body = [r.message, r.detail].filter(Boolean).join('\n\n');
+        if (r.status === 'fail') {
+            lines.push(`    <testcase ${attrs}>`);
+            lines.push(`      <failure message="${esc(r.message ?? r.title)}" type="${esc(r.id)}">${esc(body)}</failure>`);
+            lines.push(`    </testcase>`);
+        }
+        else if (r.status === 'skip') {
+            lines.push(`    <testcase ${attrs}>`);
+            lines.push(`      <skipped message="${esc(r.message ?? '')}"/>`);
+            lines.push(`    </testcase>`);
+        }
+        else if (r.status === 'warn') {
+            lines.push(`    <testcase ${attrs}>`);
+            lines.push(`      <system-out>${esc(`[warning] ${body}`)}</system-out>`);
+            lines.push(`    </testcase>`);
+        }
+        else {
+            lines.push(`    <testcase ${attrs}/>`);
+        }
+    }
+    if (report.stdoutNoise.length > 0) {
+        lines.push(`    <system-err>${esc(`Non-JSON stdout:\n${report.stdoutNoise.join('\n')}`)}</system-err>`);
+    }
+    lines.push('  </testsuite>');
+    lines.push('</testsuites>');
+    return lines.join('\n') + '\n';
+}

package/dist/report/terminal.d.ts

@@ -0,0 +1,6 @@
+import type { RunReport } from '../types.js';
+export interface TerminalOptions {
+    /** Show the detail block for warnings too, not just failures. */
+    verbose?: boolean;
+}
+export declare function renderTerminal(report: RunReport, opts?: TerminalOptions): string;

package/dist/report/terminal.js

@@ -0,0 +1,101 @@
+const useColor = !process.env['NO_COLOR'] && (process.env['FORCE_COLOR'] === '1' || process.stdout.isTTY === true);
+const c = {
+    reset: useColor ? '\x1b[0m' : '',
+    dim: useColor ? '\x1b[2m' : '',
+    bold: useColor ? '\x1b[1m' : '',
+    red: useColor ? '\x1b[31m' : '',
+    green: useColor ? '\x1b[32m' : '',
+    yellow: useColor ? '\x1b[33m' : '',
+    blue: useColor ? '\x1b[34m' : '',
+    gray: useColor ? '\x1b[90m' : '',
+};
+const MARK = {
+    pass: `${c.green}PASS${c.reset}`,
+    fail: `${c.red}FAIL${c.reset}`,
+    warn: `${c.yellow}WARN${c.reset}`,
+    skip: `${c.gray}SKIP${c.reset}`,
+};
+/** Visible width, so ANSI codes do not throw the column maths off. */
+function width(s) {
+    return s.replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+function pad(s, to) {
+    const w = width(s);
+    return w >= to ? s : s + ' '.repeat(to - w);
+}
+function groupOf(id) {
+    return id.split('.')[0] ?? id;
+}
+const GROUP_TITLES = {
+    connect: 'connection',
+    protocol: 'protocol conformance',
+    schema: 'tool schemas',
+    robustness: 'robustness',
+    hygiene: 'transport hygiene',
+};
+export function renderTerminal(report, opts = {}) {
+    const lines = [];
+    const { server, results, summary } = report;
+    const title = server.name ? `${server.name}${server.version ? ` v${server.version}` : ''}` : server.target;
+    lines.push('');
+    lines.push(`  ${c.bold}mcp-probe${c.reset}  ${title}`);
+    lines.push(`  ${c.gray}${server.target}${server.protocolVersion ? `  ${c.dim}|${c.reset}${c.gray}  protocol ${server.protocolVersion}` : ''}${c.reset}`);
+    lines.push('');
+    const groups = new Map();
+    for (const r of results) {
+        const g = groupOf(r.id);
+        if (!groups.has(g))
+            groups.set(g, []);
+        groups.get(g).push(r);
+    }
+    for (const [group, items] of groups) {
+        lines.push(`  ${c.bold}${GROUP_TITLES[group] ?? group}${c.reset}`);
+        for (const r of items) {
+            const label = r.target ? `${r.title} ${c.gray}(${r.target})${c.reset}` : r.title;
+            const timing = r.ms !== undefined ? `${c.gray}${r.ms}ms${c.reset}` : '';
+            // Some checks report their timing as the message; do not print it twice.
+            const showNote = r.status === 'pass' && r.message && r.message !== `${r.ms}ms`;
+            const note = showNote ? `${c.gray}${r.message}${c.reset}` : '';
+            const right = [note, timing].filter(Boolean).join('  ');
+            lines.push(`    ${MARK[r.status]}  ${pad(label, 58)}${right}`);
+            if (r.status !== 'pass' && r.message) {
+                lines.push(`          ${c.gray}${r.message}${c.reset}`);
+            }
+        }
+        lines.push('');
+    }
+    // Failures always get a detail block. Warnings stay collapsed unless asked
+    // for, so a run with many small nits does not bury the things that broke.
+    const hiddenWarnings = opts.verbose ? 0 : results.filter((r) => r.status === 'warn' && r.detail).length;
+    const withDetail = results.filter((r) => r.detail && (r.status === 'fail' || (opts.verbose && r.status === 'warn')));
+    if (withDetail.length > 0) {
+        lines.push(`  ${c.bold}details${c.reset}`);
+        lines.push('');
+        for (const r of withDetail) {
+            const colour = r.status === 'fail' ? c.red : c.yellow;
+            lines.push(`  ${colour}${r.status === 'fail' ? 'FAIL' : 'WARN'}${c.reset}  ${c.bold}${r.title}${r.target ? ` ${c.reset}${c.gray}(${r.target})` : ''}${c.reset}`);
+            lines.push(`        ${c.gray}${r.id}${r.spec ? `  ${r.spec}` : ''}${c.reset}`);
+            if (r.message)
+                lines.push(`        ${r.message}`);
+            for (const dl of (r.detail ?? '').split('\n'))
+                lines.push(`        ${c.gray}${dl}${c.reset}`);
+            lines.push('');
+        }
+    }
+    const parts = [];
+    if (summary.fail)
+        parts.push(`${c.red}${summary.fail} failed${c.reset}`);
+    if (summary.warn)
+        parts.push(`${c.yellow}${summary.warn} warning${summary.warn === 1 ? '' : 's'}${c.reset}`);
+    if (summary.pass)
+        parts.push(`${c.green}${summary.pass} passed${c.reset}`);
+    if (summary.skip)
+        parts.push(`${c.gray}${summary.skip} skipped${c.reset}`);
+    lines.push(`  ${c.gray}${'-'.repeat(64)}${c.reset}`);
+    lines.push(`  ${parts.join(`${c.gray}  |  ${c.reset}`)}   ${c.gray}${(report.durationMs / 1000).toFixed(2)}s${c.reset}`);
+    if (hiddenWarnings > 0) {
+        lines.push(`  ${c.gray}${hiddenWarnings} warning${hiddenWarnings === 1 ? '' : 's'} not expanded. Run with --verbose for the full explanation.${c.reset}`);
+    }
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/run.d.ts

@@ -0,0 +1,23 @@
+import type { CheckResult, RunOptions, RunReport } from './types.js';
+export interface TargetSpec {
+    kind: 'stdio' | 'http';
+    /** stdio */
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    /** http */
+    url?: string;
+    headers?: Record<string, string>;
+}
+export declare const DEFAULT_OPTIONS: RunOptions;
+/**
+ * Run the suite against one server and return everything that happened.
+ * Never throws for a server-side fault -- a server that cannot even handshake
+ * is a *result*, not an exception, or CI could not report on it.
+ */
+export declare function run(target: TargetSpec, options?: Partial<RunOptions>, hooks?: {
+    onResult?: (r: CheckResult) => void;
+}): Promise<RunReport>;
+/** Exit code contract: 0 clean, 1 findings, 2 could not run. */
+export declare function exitCodeFor(report: RunReport, strict: boolean): number;

package/dist/run.js

@@ -0,0 +1,155 @@
+import { McpClient, StdioTransport, HttpTransport } from './client/index.js';
+import { allChecks, selectChecks } from './checks/index.js';
+import { result } from './checks/util.js';
+export const DEFAULT_OPTIONS = {
+    timeoutMs: 10_000,
+    callTools: false,
+    safeTools: [],
+    strict: false,
+};
+function buildTransport(target) {
+    if (target.kind === 'http') {
+        if (!target.url)
+            throw new Error('An http target needs a url');
+        return new HttpTransport({ url: target.url, headers: target.headers });
+    }
+    if (!target.command)
+        throw new Error('A stdio target needs a command');
+    return new StdioTransport({
+        command: target.command,
+        args: target.args ?? [],
+        env: target.env,
+        cwd: target.cwd,
+    });
+}
+function summarise(results) {
+    const summary = { pass: 0, fail: 0, warn: 0, skip: 0 };
+    for (const r of results)
+        summary[r.status]++;
+    return summary;
+}
+/**
+ * Run the suite against one server and return everything that happened.
+ * Never throws for a server-side fault -- a server that cannot even handshake
+ * is a *result*, not an exception, or CI could not report on it.
+ */
+export async function run(target, options = {}, hooks = {}) {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const started = Date.now();
+    const transport = buildTransport(target);
+    const client = new McpClient(transport, opts.timeoutMs);
+    const results = [];
+    // Two tools that share a name produce results indistinguishable to the
+    // reader, so collapse exact repeats rather than printing the same line twice.
+    const seenResults = new Set();
+    const emit = (r) => {
+        const key = `${r.id}|${r.target ?? ''}|${r.message ?? ''}`;
+        if (seenResults.has(key))
+            return;
+        seenResults.add(key);
+        results.push(r);
+        hooks.onResult?.(r);
+    };
+    const finish = () => ({
+        server: {
+            name: ctx?.serverInfo?.name,
+            version: ctx?.serverInfo?.version,
+            protocolVersion: ctx?.protocolVersion ?? null,
+            target: transport.target,
+        },
+        results,
+        summary: summarise(results),
+        durationMs: Date.now() - started,
+        stdoutNoise: [...transport.stdoutNoise],
+        stderr: [...transport.stderr],
+    });
+    let ctx = null;
+    try {
+        await client.start();
+    }
+    catch (e) {
+        emit(result('connect', 'Server starts', 'fail', 'error', {
+            message: e.message,
+            detail: transport.stderr.slice(-12).join('\n') || undefined,
+        }));
+        return finish();
+    }
+    // The handshake gates everything: without it there is nothing to check.
+    let handshake;
+    try {
+        handshake = await client.initialize();
+    }
+    catch (e) {
+        emit(result('connect', 'Server completes the initialize handshake', 'fail', 'error', {
+            message: e.message,
+            detail: [
+                transport.stdoutNoise.length > 0
+                    ? `Non-JSON output appeared on stdout before any reply:\n${transport.stdoutNoise.slice(0, 5).map((l) => `  > ${l}`).join('\n')}\n\nThis alone will prevent every client from connecting.`
+                    : '',
+                transport.stderr.slice(-12).join('\n'),
+            ]
+                .filter(Boolean)
+                .join('\n\n') || undefined,
+        }));
+        await client.close();
+        return finish();
+    }
+    if (handshake.raw.error) {
+        emit(result('connect', 'Server completes the initialize handshake', 'fail', 'error', {
+            message: `initialize returned error ${handshake.raw.error.code}: ${handshake.raw.error.message}`,
+            ms: handshake.ms,
+        }));
+        await client.close();
+        return finish();
+    }
+    emit(result('connect', 'Server completes the initialize handshake', 'pass', 'error', { ms: handshake.ms }));
+    client.notifyInitialized();
+    // Gather once so individual checks do not each re-list.
+    let tools = [];
+    const { tools: listed, error: listError } = await client.listTools().catch(() => ({ tools: [], error: undefined }));
+    if (listError) {
+        emit(result('connect.tools_list', 'tools/list responds', 'fail', 'error', {
+            message: `tools/list returned error ${listError.error?.code}: ${listError.error?.message}`,
+        }));
+    }
+    else {
+        tools = listed;
+    }
+    const resources = await client.listAll('resources/list', 'resources').then((r) => r.items).catch(() => []);
+    const prompts = await client.listAll('prompts/list', 'prompts').then((r) => r.items).catch(() => []);
+    ctx = {
+        client,
+        tools,
+        resources,
+        prompts,
+        serverInfo: handshake.serverInfo,
+        capabilities: handshake.capabilities,
+        protocolVersion: handshake.protocolVersion,
+        options: opts,
+    };
+    for (const check of selectChecks(allChecks, opts.only, opts.skip)) {
+        try {
+            for (const r of await check.run(ctx))
+                emit(r);
+        }
+        catch (e) {
+            // A check that throws is a bug in mcp-probe, not in the server under
+            // test. Say which one, and keep going -- one broken check must not
+            // invalidate the rest of the report.
+            emit(result(check.id, check.title, 'skip', 'info', {
+                message: `Check errored internally: ${e.message}`,
+                detail: 'This is a bug in mcp-probe. Please report it with the server that triggered it.',
+            }));
+        }
+    }
+    await client.close();
+    return finish();
+}
+/** Exit code contract: 0 clean, 1 findings, 2 could not run. */
+export function exitCodeFor(report, strict) {
+    if (report.summary.fail > 0)
+        return 1;
+    if (strict && report.summary.warn > 0)
+        return 1;
+    return 0;
+}