@beeeeen/mcp-probe 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BenYang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,234 @@
+# mcp-probe
+
+**Conformance and robustness tests for MCP servers. Built to run in CI.**
+
+[![CI](https://github.com/Beeeeen/mcp-probe/actions/workflows/ci.yml/badge.svg)](https://github.com/Beeeeen/mcp-probe/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/%40beeeeen%2Fmcp-probe.svg)](https://www.npmjs.com/package/@beeeeen/mcp-probe)
+[![node](https://img.shields.io/node/v/%40beeeeen%2Fmcp-probe.svg)](https://www.npmjs.com/package/@beeeeen/mcp-probe)
+[![license](https://img.shields.io/npm/l/%40beeeeen%2Fmcp-probe.svg)](./LICENSE)
+
+```bash
+npx @beeeeen/mcp-probe -- node build/index.js
+```
+
+No install, no config, no dependencies. Point it at a server, get a verdict.
+
+---
+
+## Why this exists
+
+The official [Inspector](https://github.com/modelcontextprotocol/inspector) is a **visual** tool -- you click through it by hand. The official [conformance suite](https://github.com/modelcontextprotocol/conformance) runs in CI, but it tests servers **over HTTP only**, and it checks the spec, not quality.
+
+Most published MCP servers are **stdio** processes launched by the host -- and stdio is where the deadliest failure mode lives, one no HTTP-based test can even observe:
+
+```js
+console.log('Server started')   // <- stdout IS the protocol channel.
+```
+
+That one line corrupts the JSON-RPC stream. The host cannot parse it, so it disconnects — or worse, silently drops every message after it. No stack trace, no error, no log. The server "just doesn't work in Claude Desktop" and you spend an afternoon on it.
+
+Every MCP client library discards bytes it cannot parse, which is why nothing reports this. **mcp-probe keeps the discarded bytes and shows them to you.**
+
+That is one check out of 16, across roughly 30 distinct findings — all of them things that have shipped in real, published servers. Beyond spec conformance, mcp-probe also grades what the spec cannot: whether a model can actually *use* the server -- description quality, schemas whose `required` fields exist, argument validation that runs before side effects, and the token weight of the tool list.
+
+---
+
+## What it finds
+
+Run against a server with the usual set of mistakes:
+
+```
+  mcp-probe  bad-fixture
+  node server.js  |  protocol 2025-06-18
+
+  protocol conformance
+    WARN  initialize returns serverInfo.version
+          "bad-fixture" reports no version.
+    PASS  Declared "tools" capability answers tools/list            5 tools
+    FAIL  Declared "resources" capability answers resources/list
+          resources/list returned no "resources" array.
+    FAIL  Unknown method returns -32601
+          Server answered a method that does not exist with a success result.
+
+  tool schemas
+    FAIL  Tool name is host-compatible (search files)
+          "search files" contains characters hosts reject.
+    FAIL  Tool names are unique (dup)
+          "dup" is listed 2 times.
+    FAIL  Tool has a description (mystery)
+          No description.
+    FAIL  required fields exist in properties (search files)
+          required lists "directory", which is not in properties.
+    PASS  Tool list does not dominate the context window            ~189 tokens across 5 tools
+
+  robustness
+    FAIL  Calling a tool that does not exist is rejected
+          An unknown tool name returned a success result.
+    FAIL  Missing required arguments are rejected (delete_everything)
+          Ran with none of its 1 required argument and reported success.
+
+  transport hygiene
+    FAIL  stdout carries only JSON-RPC
+          1 non-JSON line written to stdout.
+
+  ----------------------------------------------------------------
+  11 failed  |  8 warnings  |  9 passed  |  1 skipped   0.42s
+```
+
+Every failure comes with the offending payload and an explanation of what breaks:
+
+```
+  FAIL  stdout carries only JSON-RPC
+        hygiene.stdout_purity  https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
+        1 non-JSON line written to stdout.
+        stdout is the protocol channel for stdio transport. Every one of these
+        lines corrupts the stream:
+
+          > bad-server starting up...
+
+        Fix: send all human-readable output to stderr (console.error, or a
+        logger configured with stderr as its sink).
+```
+
+---
+
+## Usage
+
+```bash
+# stdio server
+npx @beeeeen/mcp-probe -- node build/index.js
+npx @beeeeen/mcp-probe -- npx -y @modelcontextprotocol/server-filesystem /tmp
+
+# streamable HTTP
+npx @beeeeen/mcp-probe --url http://localhost:3000/mcp
+
+# a server you already have configured
+npx @beeeeen/mcp-probe --config ~/.claude.json --server github
+```
+
+`--config` reads both the `mcpServers` shape (Claude Desktop, Claude Code, Cursor) and the `servers` shape (VS Code), so you can probe a server without retyping how it launches.
+
+mcp-probe's own flags come first; everything after `--` is the server's command line, untouched.
+
+| flag | |
+|---|---|
+| `--strict` | treat warnings as failures |
+| `--json` / `--json-out <file>` | machine-readable report |
+| `--junit <file>` | JUnit XML for CI test reporting |
+| `--only` / `--skip` | select checks by id or group |
+| `--verbose` | expand the explanation for warnings |
+| `--timeout <ms>` | per-request timeout (default 10000) |
+| `--call-tools` | invoke tools — see [Safety](#safety) |
+
+Exit codes: `0` clean · `1` findings · `2` could not run.
+
+---
+
+## In CI
+
+```yaml
+- uses: Beeeeen/mcp-probe@v1
+  with:
+    command: node build/index.js
+    strict: true
+```
+
+Failures become inline annotations, and a table lands in the job summary. Outputs `failures`, `warnings` and `report` for later steps.
+
+Or without the action:
+
+```yaml
+- run: npx @beeeeen/mcp-probe --junit results.xml -- node build/index.js
+```
+
+---
+
+## What gets checked
+
+**Protocol conformance** — the handshake returns a usable `protocolVersion` and `serverInfo`; declared capabilities are actually implemented *and return the right shape*; unknown methods produce `-32601` rather than a crash or a fake success; `ping` answers; an older `protocolVersion` does not take the process down.
+
+**Tool schemas** — names are unique and host-compatible; descriptions exist and are not `TODO`; `inputSchema` is a real JSON Schema rooted at `type: object`; `required` never names a field that is missing from `properties`; parameters carry descriptions; and the whole tool list is measured in tokens, because it is re-sent on *every* request and nothing else tells you what that costs.
+
+**Robustness** — unknown tool names are rejected; omitting required arguments does not silently execute the tool anyway; wrongly typed arguments are not coerced into a wrong answer; malformed JSON-RPC on the wire does not wedge or kill the read loop; tool results are not large enough to evict the conversation.
+
+**Transport hygiene** — stdout carries only JSON-RPC; stderr has no unhandled exceptions; the process is still alive at the end.
+
+Every check has a stable dotted id (`schema.input_schema.orphan_required`), so `--skip` and `--only` work at any granularity, and a finding you have decided to live with can be silenced precisely.
+
+---
+
+## Safety
+
+**mcp-probe does not invoke your tools unless you ask it to.**
+
+The default run only ever calls tools with *invalid* arguments — missing required fields, wrong types. A correct server rejects those at validation, before any side effect, and that rejection is exactly what is being measured. A server that performs work anyway is the bug being reported.
+
+To measure real responses, opt in explicitly:
+
+```bash
+npx @beeeeen/mcp-probe --safe-tool list_directory -- node server.js   # just this one
+npx @beeeeen/mcp-probe --call-tools -- node server.js                 # all of them
+```
+
+There is a `delete_everything` tool in the test fixtures for a reason.
+
+---
+
+## Programmatic use
+
+```ts
+import { run, exitCodeFor } from 'mcp-probe'
+
+const report = await run(
+  { kind: 'stdio', command: 'node', args: ['build/index.js'] },
+  { strict: true },
+)
+
+for (const r of report.results.filter((r) => r.status === 'fail')) {
+  console.error(`${r.id}: ${r.message}`)
+}
+process.exit(exitCodeFor(report, true))
+```
+
+The check list is exported too, so you can run a subset or add your own:
+
+```ts
+import { allChecks, selectChecks } from 'mcp-probe'
+```
+
+---
+
+## Design notes
+
+**No runtime dependencies, and no MCP SDK.** The JSON-RPC layer is hand-rolled on purpose. Client libraries normalise responses and throw away what they cannot parse — which is precisely the evidence a conformance tester needs. mcp-probe reads the raw bytes so it can report what the SDK would have hidden.
+
+**A broken server is a result, not an exception.** A server that will not start, will not handshake, or dies mid-run produces a report saying so. CI can always render something.
+
+**Findings explain themselves.** Each one carries the payload that triggered it, a link to the relevant part of the spec, and a sentence on what actually breaks. A finding you cannot act on is noise.
+
+---
+
+## Contributing
+
+New checks are welcome, especially ones drawn from a bug you actually hit. A check is one object in `src/checks/`, and the bar is:
+
+- it must be **actionable** — the message says what to change
+- it must not **false-positive** on the reference servers (`@modelcontextprotocol/server-everything` and `server-filesystem` are probed in CI)
+- add the defect to `fixtures/bad-server.js` and assert on it in `test/probe.test.js`
+
+```bash
+npm install && npm run build && npm test
+```
+
+## See also
+
+The rest of the toolchain, built on the same zero-dependency MCP client:
+
+- [**mcp-wtf**](https://github.com/Beeeeen/mcp-wtf) -- your MCP server won't connect; find out why in 10 seconds.
+- [**context-xray**](https://github.com/Beeeeen/context-xray) -- what every configured MCP server costs you in context-window tokens on every request.
+
+mcp-wtf answers "why won't it connect", context-xray answers "what is it costing me", mcp-probe answers "will it break my users".
+
+## License
+
+MIT

package/dist/checks/hygiene.d.ts

@@ -0,0 +1,17 @@
+import type { Check } from '../types.js';
+/**
+ * The single most common way to break an stdio MCP server, and the hardest to
+ * diagnose: one `console.log` anywhere in the process -- yours, a dependency's,
+ * or the runtime's -- puts a non-JSON line on stdout. stdout *is* the protocol
+ * channel, so the host's parser desynchronises and the server appears to hang
+ * or disconnect at random, with no error anywhere.
+ *
+ * Nothing else in the toolchain reports this, because every client library
+ * discards what it cannot parse. We keep the discarded lines instead.
+ */
+export declare const stdoutPurityCheck: Check;
+/** A server that dies during the run fails everything after it; say so plainly. */
+export declare const survivalCheck: Check;
+/** Stack traces on stderr are legal but almost always mean an unhandled path. */
+export declare const stderrSanityCheck: Check;
+export declare const hygieneChecks: Check[];

package/dist/checks/hygiene.js

@@ -0,0 +1,104 @@
+import { result } from './util.js';
+const SPEC = 'https://modelcontextprotocol.io/specification/2025-06-18/basic/transports';
+/** Frameworks and runtimes that print to stdout unless told otherwise. */
+const KNOWN_NOISE_SOURCES = [
+    [/^\s*(Debugger attached|Waiting for the debugger)/i, 'Node.js inspector output. Drop --inspect from the launch command.'],
+    [/npm (warn|notice|WARN)/i, 'npm chatter. Run the built entrypoint directly instead of through `npm run`, or pass --silent.'],
+    [/^\s*>\s/, 'An npm lifecycle script echo. `npm run` prints the command it is about to run onto stdout.'],
+    [/(DeprecationWarning|ExperimentalWarning|MaxListenersExceeded)/i, 'A Node warning. Route warnings to stderr with NODE_OPTIONS=--no-warnings or process.removeAllListeners("warning").'],
+    [/^\s*(INFO|DEBUG|WARN|ERROR|TRACE)[\s:\]]/i, 'A logger writing to stdout. Point the logger at stderr.'],
+    [/^\s*\{\s*$|^\s*\}\s*$/, 'Pretty-printed JSON. The stdio framing is one JSON object per line -- multi-line output desynchronises the stream.'],
+    [/Server (running|started|listening)/i, 'A startup banner. Print it to stderr, or not at all.'],
+];
+function explain(line) {
+    for (const [pattern, hint] of KNOWN_NOISE_SOURCES)
+        if (pattern.test(line))
+            return hint;
+    return null;
+}
+/**
+ * The single most common way to break an stdio MCP server, and the hardest to
+ * diagnose: one `console.log` anywhere in the process -- yours, a dependency's,
+ * or the runtime's -- puts a non-JSON line on stdout. stdout *is* the protocol
+ * channel, so the host's parser desynchronises and the server appears to hang
+ * or disconnect at random, with no error anywhere.
+ *
+ * Nothing else in the toolchain reports this, because every client library
+ * discards what it cannot parse. We keep the discarded lines instead.
+ */
+export const stdoutPurityCheck = {
+    id: 'hygiene.stdout_purity',
+    title: 'stdout carries only JSON-RPC',
+    severity: 'error',
+    spec: SPEC,
+    run(ctx) {
+        const t = ctx.client.transport;
+        if (t.kind !== 'stdio') {
+            return [result('hygiene.stdout_purity', 'stdout carries only JSON-RPC', 'skip', 'error', { message: 'stdio only.' })];
+        }
+        const noise = t.stdoutNoise;
+        if (noise.length === 0) {
+            return [
+                result('hygiene.stdout_purity', 'stdout carries only JSON-RPC', 'pass', 'error', {
+                    message: 'No non-JSON output on stdout.',
+                }),
+            ];
+        }
+        const shown = noise.slice(0, 8);
+        const hints = new Set();
+        for (const line of noise) {
+            const hint = explain(line);
+            if (hint)
+                hints.add(hint);
+        }
+        const lines = shown.map((l) => `  > ${l.length > 160 ? l.slice(0, 160) + ' ...' : l}`).join('\n');
+        const more = noise.length > shown.length ? `\n  ... and ${noise.length - shown.length} more line(s)` : '';
+        const diagnosis = hints.size > 0 ? `\n\nLikely cause:\n${[...hints].map((h) => `  - ${h}`).join('\n')}` : '';
+        return [
+            result('hygiene.stdout_purity', 'stdout carries only JSON-RPC', 'fail', 'error', {
+                message: `${noise.length} non-JSON line${noise.length === 1 ? '' : 's'} written to stdout.`,
+                detail: `stdout is the protocol channel for stdio transport. Every one of these lines corrupts the stream:\n\n${lines}${more}${diagnosis}\n\nFix: send all human-readable output to stderr (console.error, or a logger configured with stderr as its sink).`,
+                spec: SPEC,
+            }),
+        ];
+    },
+};
+/** A server that dies during the run fails everything after it; say so plainly. */
+export const survivalCheck = {
+    id: 'hygiene.survival',
+    title: 'Server is still running at the end of the suite',
+    severity: 'error',
+    run(ctx) {
+        const t = ctx.client.transport;
+        if (t.isAlive()) {
+            return [result('hygiene.survival', 'Server is still running at the end of the suite', 'pass', 'error')];
+        }
+        const info = t.exitInfo();
+        return [
+            result('hygiene.survival', 'Server is still running at the end of the suite', 'fail', 'error', {
+                message: `Server exited during the run (code ${info?.code ?? 'null'}${info?.signal ? `, signal ${info.signal}` : ''}).`,
+                detail: `Last stderr:\n${t.stderr.slice(-12).join('\n') || '(none)'}`,
+            }),
+        ];
+    },
+};
+/** Stack traces on stderr are legal but almost always mean an unhandled path. */
+export const stderrSanityCheck = {
+    id: 'hygiene.stderr',
+    title: 'No unhandled exceptions on stderr',
+    severity: 'warn',
+    run(ctx) {
+        const t = ctx.client.transport;
+        const suspicious = t.stderr.filter((l) => /(UnhandledPromiseRejection|Unhandled 'error' event|^\s*at \S+ \(|Traceback \(most recent call last\)|panic:)/.test(l));
+        if (suspicious.length === 0) {
+            return [result('hygiene.stderr', 'No unhandled exceptions on stderr', 'pass', 'warn')];
+        }
+        return [
+            result('hygiene.stderr', 'No unhandled exceptions on stderr', 'warn', 'warn', {
+                message: `${suspicious.length} line${suspicious.length === 1 ? '' : 's'} on stderr look like an unhandled exception.`,
+                detail: suspicious.slice(0, 12).join('\n'),
+            }),
+        ];
+    },
+};
+export const hygieneChecks = [stdoutPurityCheck, stderrSanityCheck, survivalCheck];

package/dist/checks/index.d.ts

@@ -0,0 +1,16 @@
+import type { Check } from '../types.js';
+import { protocolChecks } from './protocol.js';
+import { schemaChecks } from './schema.js';
+import { robustnessChecks } from './robustness.js';
+import { hygieneChecks } from './hygiene.js';
+export { protocolChecks, schemaChecks, robustnessChecks, hygieneChecks };
+/**
+ * Order is deliberate. Protocol and schema checks are read-only and run first;
+ * robustness checks push malformed traffic at the server, so anything that
+ * would be perturbed by that has already run. Hygiene goes last because it
+ * grades the byproducts -- stdout noise, stderr, liveness -- of everything
+ * above it.
+ */
+export declare const allChecks: Check[];
+/** Ids match by prefix, so `--skip robustness` drops the whole group. */
+export declare function selectChecks(checks: Check[], only?: string[], skip?: string[]): Check[];

package/dist/checks/index.js

@@ -0,0 +1,24 @@
+import { protocolChecks } from './protocol.js';
+import { schemaChecks } from './schema.js';
+import { robustnessChecks } from './robustness.js';
+import { hygieneChecks } from './hygiene.js';
+export { protocolChecks, schemaChecks, robustnessChecks, hygieneChecks };
+/**
+ * Order is deliberate. Protocol and schema checks are read-only and run first;
+ * robustness checks push malformed traffic at the server, so anything that
+ * would be perturbed by that has already run. Hygiene goes last because it
+ * grades the byproducts -- stdout noise, stderr, liveness -- of everything
+ * above it.
+ */
+export const allChecks = [...protocolChecks, ...schemaChecks, ...robustnessChecks, ...hygieneChecks];
+/** Ids match by prefix, so `--skip robustness` drops the whole group. */
+export function selectChecks(checks, only, skip) {
+    let selected = checks;
+    if (only && only.length > 0) {
+        selected = selected.filter((c) => only.some((o) => c.id === o || c.id.startsWith(o + '.')));
+    }
+    if (skip && skip.length > 0) {
+        selected = selected.filter((c) => !skip.some((s) => c.id === s || c.id.startsWith(s + '.')));
+    }
+    return selected;
+}

package/dist/checks/protocol.d.ts

@@ -0,0 +1,15 @@
+import type { Check } from '../types.js';
+/**
+ * The handshake already happened in the runner (everything else depends on it),
+ * so this check grades the response that came back rather than redoing it.
+ */
+export declare const handshakeCheck: Check;
+/** A server that advertises a capability it did not implement breaks clients at runtime. */
+export declare const capabilityHonestyCheck: Check;
+/** Unknown methods must produce -32601, not a crash and not a fake success. */
+export declare const unknownMethodCheck: Check;
+/** `ping` is cheap and hosts use it for liveness. */
+export declare const pingCheck: Check;
+/** Version negotiation: asking for an old version must not kill the server. */
+export declare const versionNegotiationCheck: Check;
+export declare const protocolChecks: Check[];

package/dist/checks/protocol.js

@@ -0,0 +1,225 @@
+import { RPC } from '../client/jsonrpc.js';
+import { SUPPORTED_PROTOCOL_VERSIONS } from '../client/index.js';
+import { result, preview, isPlainObject } from './util.js';
+const SPEC = 'https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle';
+/**
+ * The handshake already happened in the runner (everything else depends on it),
+ * so this check grades the response that came back rather than redoing it.
+ */
+export const handshakeCheck = {
+    id: 'protocol.handshake',
+    title: 'initialize returns a well-formed result',
+    severity: 'error',
+    spec: SPEC,
+    run(ctx) {
+        const out = [];
+        const { protocolVersion, serverInfo } = ctx;
+        if (!protocolVersion) {
+            out.push(result('protocol.handshake.version', 'initialize returns protocolVersion', 'fail', 'error', {
+                message: 'The initialize result had no `protocolVersion` field.',
+                detail: 'Clients use this to decide which features to attempt. Without it, well-behaved clients disconnect.',
+                spec: SPEC,
+            }));
+        }
+        else if (!SUPPORTED_PROTOCOL_VERSIONS.includes(protocolVersion)) {
+            out.push(result('protocol.handshake.version', 'initialize returns protocolVersion', 'warn', 'warn', {
+                message: `Unrecognised protocol version "${protocolVersion}".`,
+                detail: `Known versions: ${SUPPORTED_PROTOCOL_VERSIONS.join(', ')}. A typo here silently breaks feature negotiation.`,
+                spec: SPEC,
+            }));
+        }
+        else {
+            out.push(result('protocol.handshake.version', 'initialize returns protocolVersion', 'pass', 'error', {
+                message: protocolVersion,
+            }));
+        }
+        if (!serverInfo || !serverInfo.name) {
+            out.push(result('protocol.handshake.serverinfo', 'initialize returns serverInfo.name', 'fail', 'error', {
+                message: 'Missing `serverInfo.name`.',
+                detail: 'Hosts show this name in their UI and use it to key per-server settings. An unnamed server is unidentifiable in logs.',
+                spec: SPEC,
+            }));
+        }
+        else if (!serverInfo.version) {
+            out.push(result('protocol.handshake.serverinfo', 'initialize returns serverInfo.version', 'warn', 'warn', {
+                message: `"${serverInfo.name}" reports no version.`,
+                detail: 'Without a version, users cannot tell which build produced a bug report.',
+                spec: SPEC,
+            }));
+        }
+        else {
+            out.push(result('protocol.handshake.serverinfo', 'initialize returns serverInfo', 'pass', 'error', {
+                message: `${serverInfo.name} v${serverInfo.version}`,
+            }));
+        }
+        return out;
+    },
+};
+/** A server that advertises a capability it did not implement breaks clients at runtime. */
+export const capabilityHonestyCheck = {
+    id: 'protocol.capabilities',
+    title: 'Declared capabilities are actually implemented',
+    severity: 'error',
+    spec: SPEC,
+    async run(ctx) {
+        const out = [];
+        const caps = ctx.capabilities;
+        const pairs = [
+            ['tools', 'tools/list'],
+            ['resources', 'resources/list'],
+            ['prompts', 'prompts/list'],
+        ];
+        for (const [cap, method] of pairs) {
+            if (!isPlainObject(caps[cap]))
+                continue;
+            const res = await ctx.client.call(method, {});
+            if (res.error) {
+                out.push(result(`protocol.capabilities.${cap}`, `Declared "${cap}" capability answers ${method}`, 'fail', 'error', {
+                    message: `Server declares "${cap}" but ${method} returned error ${res.error.code}: ${res.error.message}`,
+                    detail: 'Clients call the listing method as soon as the capability is advertised. This fails on first contact.',
+                    spec: SPEC,
+                }));
+                continue;
+            }
+            // A response is not enough: it has to be the right shape. A catch-all
+            // dispatcher answers every method with something, which looks like
+            // success here but hands the client nothing it can use.
+            const payload = (res.result ?? {});
+            if (!Array.isArray(payload[cap])) {
+                out.push(result(`protocol.capabilities.${cap}`, `Declared "${cap}" capability answers ${method}`, 'fail', 'error', {
+                    message: `${method} returned no "${cap}" array.`,
+                    detail: `Got: ${preview(res.result)}\nServer declares the "${cap}" capability, so ${method} must return { "${cap}": [...] }. Returning something else usually means the method is unimplemented and a catch-all branch answered instead.`,
+                    spec: SPEC,
+                }));
+                continue;
+            }
+            out.push(result(`protocol.capabilities.${cap}`, `Declared "${cap}" capability answers ${method}`, 'pass', 'error', {
+                message: `${payload[cap].length} ${cap}`,
+            }));
+        }
+        if (out.length === 0) {
+            out.push(result('protocol.capabilities', 'Declared capabilities are implemented', 'warn', 'warn', {
+                message: 'Server declared no tools, resources or prompts capability.',
+                detail: 'Nothing is reachable through this server. Check that capabilities are registered before connect().',
+            }));
+        }
+        return out;
+    },
+};
+/** Unknown methods must produce -32601, not a crash and not a fake success. */
+export const unknownMethodCheck = {
+    id: 'protocol.unknown_method',
+    title: 'Unknown method returns -32601',
+    severity: 'error',
+    spec: 'https://www.jsonrpc.org/specification#error_object',
+    async run(ctx) {
+        const method = 'mcpProbe/definitelyNotAMethod';
+        try {
+            const res = await ctx.client.call(method, {}, Math.min(ctx.options.timeoutMs, 5000));
+            if (res.error?.code === RPC.METHOD_NOT_FOUND) {
+                return [result('protocol.unknown_method', 'Unknown method returns -32601', 'pass', 'error')];
+            }
+            if (res.error) {
+                return [
+                    result('protocol.unknown_method', 'Unknown method returns -32601', 'warn', 'warn', {
+                        message: `Returned ${res.error.code} instead of ${RPC.METHOD_NOT_FOUND}.`,
+                        detail: `Full error: ${preview(res.error)}\nClients branch on -32601 to feature-detect. A different code reads as "the call failed", not "unsupported".`,
+                    }),
+                ];
+            }
+            return [
+                result('protocol.unknown_method', 'Unknown method returns -32601', 'fail', 'error', {
+                    message: 'Server answered a method that does not exist with a success result.',
+                    detail: `Result: ${preview(res.result)}\nThis means the dispatcher has a catch-all branch, so mistyped method names fail silently.`,
+                }),
+            ];
+        }
+        catch (e) {
+            return [
+                result('protocol.unknown_method', 'Unknown method returns -32601', 'fail', 'error', {
+                    message: `Server did not answer an unknown method: ${e.message}`,
+                    detail: 'An unrecognised method must be answered with an error, never dropped and never fatal.',
+                }),
+            ];
+        }
+    },
+};
+/** `ping` is cheap and hosts use it for liveness. */
+export const pingCheck = {
+    id: 'protocol.ping',
+    title: 'Responds to ping',
+    severity: 'warn',
+    spec: 'https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/ping',
+    async run(ctx) {
+        const t0 = Date.now();
+        try {
+            const res = await ctx.client.call('ping', {}, Math.min(ctx.options.timeoutMs, 5000));
+            const ms = Date.now() - t0;
+            if (res.error) {
+                return [
+                    result('protocol.ping', 'Responds to ping', 'warn', 'warn', {
+                        ms,
+                        message: `ping returned error ${res.error.code}: ${res.error.message}`,
+                        detail: 'Some hosts ping to decide whether to restart a server. Failing this can cause spurious reconnects.',
+                    }),
+                ];
+            }
+            return [result('protocol.ping', 'Responds to ping', 'pass', 'warn', { ms, message: `${ms}ms` })];
+        }
+        catch (e) {
+            return [
+                result('protocol.ping', 'Responds to ping', 'warn', 'warn', {
+                    message: `No response to ping: ${e.message}`,
+                }),
+            ];
+        }
+    },
+};
+/** Version negotiation: asking for an old version must not kill the server. */
+export const versionNegotiationCheck = {
+    id: 'protocol.version_negotiation',
+    title: 'Handles an older protocolVersion gracefully',
+    severity: 'warn',
+    spec: SPEC,
+    async run(ctx) {
+        const old = SUPPORTED_PROTOCOL_VERSIONS[SUPPORTED_PROTOCOL_VERSIONS.length - 1];
+        if (ctx.protocolVersion === old) {
+            return [
+                result('protocol.version_negotiation', 'Handles an older protocolVersion', 'skip', 'warn', {
+                    message: `Server already negotiated the oldest known version (${old}).`,
+                }),
+            ];
+        }
+        try {
+            const res = await ctx.client.call('initialize', { protocolVersion: old, capabilities: {}, clientInfo: { name: 'mcp-probe', version: '0.1.0' } }, Math.min(ctx.options.timeoutMs, 5000));
+            if (res.error) {
+                return [
+                    result('protocol.version_negotiation', 'Handles an older protocolVersion', 'warn', 'warn', {
+                        message: `Rejected version ${old} with error ${res.error.code}.`,
+                        detail: 'Refusing outright is legal, but it locks out hosts that have not upgraded yet. Prefer replying with a version you do support.',
+                    }),
+                ];
+            }
+            return [
+                result('protocol.version_negotiation', 'Handles an older protocolVersion', 'pass', 'warn', {
+                    message: `Answered a ${old} handshake without failing.`,
+                }),
+            ];
+        }
+        catch (e) {
+            return [
+                result('protocol.version_negotiation', 'Handles an older protocolVersion', 'fail', 'error', {
+                    message: `Server stopped responding after an older-version handshake: ${e.message}`,
+                    detail: 'A version it does not like must not take the process down; older hosts would kill the server on every launch.',
+                }),
+            ];
+        }
+    },
+};
+export const protocolChecks = [
+    handshakeCheck,
+    capabilityHonestyCheck,
+    unknownMethodCheck,
+    pingCheck,
+    versionNegotiationCheck,
+];