@hafsar/mcp-probe 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-12
+
+Initial release.
+
+### Added
+
+- stdio MCP client that speaks newline-delimited JSON-RPC 2.0 directly, with no
+  runtime dependency on the official MCP SDK.
+- `initialize` handshake with `notifications/initialized`, reporting the
+  server name, version, negotiated protocol version, and declared capabilities.
+- `tools/list` with per-tool JSON Schema linting: type validity, well-formed
+  properties, required entries that must exist in properties, and warnings for
+  missing description, title, or an empty schema.
+- Latency reporting for the handshake and each list call.
+- Optional `--call` flag for safe round-trips against tools that declare no
+  required parameters. No arguments are ever fabricated.
+- `resources/list` and `prompts/list` probing when the server declares those
+  capabilities, with counts.
+- Colorized human report and `--json` machine output. Non-zero exit on any hard
+  failure (bad handshake or invalid tool schema).
+- `--timeout` flag for per-request timeouts.
+- Example stdio MCP server (`examples/echo-server.js`) and a unit test suite for
+  the linter.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haseeb Mohammed Afsar
+
+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,171 @@
+# mcp-probe
+
+[![CI](https://github.com/itguruhaseeb/mcp-probe/actions/workflows/ci.yml/badge.svg)](https://github.com/itguruhaseeb/mcp-probe/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+
+Lint and health-check any [Model Context Protocol](https://modelcontextprotocol.io)
+(MCP) server, over stdio, in one command.
+
+```
+npx @hafsar/mcp-probe -- node ./my-server.js
+```
+
+## Why this exists
+
+MCP is spreading fast, but the tooling around it is still immature. Most servers
+are hand-written, their tool `inputSchema` definitions drift out of spec, and the
+first time anyone notices is when an LLM constructs a malformed tool call in
+production. `mcp-probe` gives you a fast, dependency-light way to point at a
+server, run the handshake, and get a straight answer: does it initialize, are its
+tools well-formed, and how fast does it respond. Think of it as `eslint` plus a
+smoke test for MCP servers.
+
+It talks the MCP wire protocol directly (newline-delimited JSON-RPC 2.0 over the
+child process's stdin/stdout) rather than depending on the full MCP SDK, which
+keeps the install light and the behavior transparent.
+
+## Install and run
+
+No install required. Point it at the command that launches your server, after a
+`--` separator:
+
+```bash
+npx @hafsar/mcp-probe -- node ./server.js
+npx @hafsar/mcp-probe -- python server.py
+npx @hafsar/mcp-probe --call -- node ./server.js
+npx @hafsar/mcp-probe --json -- npx -y @modelcontextprotocol/server-filesystem /tmp
+```
+
+Everything after `--` is treated as the server launch command. Requires Node 18
+or newer.
+
+## Example output
+
+Run against the bundled example server:
+
+```bash
+node bin/mcp-probe.js -- node examples/echo-server.js
+```
+
+```
+mcp-probe v0.1.0
+target: node examples/echo-server.js
+
+Handshake
+  ✓ initialized in 41.5ms
+  • server: echo-server v1.0.0
+  • protocol: 2025-06-18
+  • capabilities: tools
+
+Tools (3)
+  ✓ echo
+  ✓ add
+  ✓ ping
+  tools/list in 0.1ms
+
+Summary: healthy (3 tools, 0 errors, 0 warnings)
+```
+
+Against a server with schema problems, it points at the exact issue and exits
+non-zero:
+
+```
+Tools (2)
+  ✗ broken: 1 error, 2 warnings
+      ! tool has no "description" (LLMs rely on it to choose the tool)
+      ! tool has no "title" annotation
+      ✗ inputSchema.required references "missing" which is not in properties
+  ! notype: 2 warnings
+      ! tool has no "title" annotation
+      ! inputSchema has no "type" (expected "object")
+
+Summary: unhealthy (2 tools, 1 error, 4 warnings)
+```
+
+## What it checks
+
+**Handshake**
+
+- Performs `initialize` with `clientInfo` of `mcp-probe` and sends
+  `notifications/initialized`.
+- Reports the server name, version, negotiated protocol version, and declared
+  capabilities.
+- Flags a mismatch between the protocol version the client offered and the one
+  the server negotiated.
+
+**Tools** (`tools/list`)
+
+For every tool, it lints the `inputSchema` as a JSON Schema:
+
+- `type` is present and is a valid JSON Schema type.
+- `properties` is a well-formed object of schema objects.
+- every entry in `required[]` actually exists in `properties`.
+- `required[]` is an array with no duplicates and no non-string entries.
+- warns on a missing `description`, a missing `title`, or an empty schema (a tool
+  that declares no structured input).
+
+**Resources and prompts**
+
+- If the server declares `resources` or `prompts` capabilities, it calls
+  `resources/list` and `prompts/list` and reports the counts.
+
+**Latency**
+
+- Times the handshake and each list call, so you can spot a slow server.
+
+**Round-trips** (opt-in, `--call`)
+
+- For each tool that has no required parameters, it performs a real `tools/call`
+  with empty arguments and reports whether the server returns cleanly. Tools with
+  required parameters are skipped; `mcp-probe` never fabricates argument values,
+  so it will not accidentally trigger a destructive operation. Round-trips are
+  off by default (list and lint only).
+
+## Flags
+
+| Flag             | Description                                                        |
+| ---------------- | ------------------------------------------------------------------ |
+| `--call`         | attempt a safe round-trip on tools with no required parameters     |
+| `--json`         | emit machine-readable JSON instead of the human report             |
+| `--timeout <ms>` | per-request timeout in milliseconds (default `10000`)              |
+| `-h`, `--help`   | show help                                                          |
+| `-v`, `--version`| show version                                                       |
+
+The `--json` output is the same structured object the human report is rendered
+from, suitable for CI. The process exits non-zero on any hard failure (handshake
+failure or an invalid tool schema), so you can gate a build on it:
+
+```bash
+npx @hafsar/mcp-probe --json -- node ./server.js || echo "MCP server is unhealthy"
+```
+
+## Roadmap
+
+- Deeper JSON Schema validation (nested `$ref`, `oneOf` / `anyOf`, format checks).
+- Optional transport backends (HTTP and SSE) alongside stdio, likely by adopting
+  the official MCP SDK transports.
+- A `--fixture` mode that generates valid sample arguments from a schema so tools
+  with required parameters can be round-tripped safely.
+- Resource read and prompt get smoke tests under `--call`.
+- A GitHub Action wrapper for one-line CI integration.
+
+## Development
+
+```bash
+node --test                                  # run the linter test suite
+node bin/mcp-probe.js -- node examples/echo-server.js
+```
+
+## Citing mcp-probe
+
+If you use mcp-probe in academic work, please cite it. Machine-readable metadata
+lives in [`CITATION.cff`](./CITATION.cff) (GitHub renders a "Cite this repository"
+button from it). A tool paper is drafted under [`paper/`](./paper/paper.md), and a
+reproducible conformance-study protocol lives in
+[`benchmark/STUDY.md`](./benchmark/STUDY.md). A versioned DOI is minted per release
+via Zenodo; the DOI will be added here once the first release is archived.
+
+## License
+
+MIT, Haseeb Mohammed Afsar. See [LICENSE](./LICENSE).

package/bin/mcp-probe.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+// mcp-probe: lint and health-check an MCP (Model Context Protocol) server.
+//
+// Usage:
+//   npx mcp-probe -- <command...>
+//   npx mcp-probe -- node ./my-server.js
+//   npx mcp-probe --call --json -- python server.py
+
+import { runDiagnostics, renderHuman } from '../src/report.js';
+import { color } from '../src/color.js';
+
+const HELP = `mcp-probe  lint and health-check any MCP server over stdio
+
+Usage
+  mcp-probe [options] -- <command...>
+
+Examples
+  mcp-probe -- node ./server.js
+  mcp-probe -- python server.py
+  mcp-probe --call -- node examples/echo-server.js
+  mcp-probe --json -- node examples/echo-server.js
+
+Options
+  --call            attempt a safe round-trip on tools with no required params
+  --json            emit machine-readable JSON instead of the human report
+  --timeout <ms>    per-request timeout in milliseconds (default 10000)
+  -h, --help        show this help
+  -v, --version     show version
+
+Everything after "--" is the command used to launch the target MCP server.
+Exit code is non-zero when a hard failure is found (bad handshake, invalid
+tool schema).`;
+
+const VERSION = '0.1.0';
+
+function parseArgs(argv) {
+  const opts = { call: false, json: false, timeout: 10000, command: null, args: [] };
+  let i = 0;
+  for (; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') {
+      const rest = argv.slice(i + 1);
+      opts.command = rest[0] || null;
+      opts.args = rest.slice(1);
+      return opts;
+    } else if (a === '--call') {
+      opts.call = true;
+    } else if (a === '--json') {
+      opts.json = true;
+    } else if (a === '--timeout') {
+      const val = Number(argv[++i]);
+      if (!Number.isFinite(val) || val <= 0) {
+        throw new UsageError(`--timeout expects a positive number, got "${argv[i]}"`);
+      }
+      opts.timeout = val;
+    } else if (a === '-h' || a === '--help') {
+      opts.help = true;
+    } else if (a === '-v' || a === '--version') {
+      opts.showVersion = true;
+    } else {
+      throw new UsageError(`unknown option "${a}" (did you forget "--" before the command?)`);
+    }
+  }
+  return opts;
+}
+
+class UsageError extends Error {}
+
+async function main() {
+  let opts;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(color.red(`error: ${err.message}\n\n`));
+    process.stderr.write(HELP + '\n');
+    process.exit(2);
+  }
+
+  if (opts.help) {
+    process.stdout.write(HELP + '\n');
+    return;
+  }
+  if (opts.showVersion) {
+    process.stdout.write(VERSION + '\n');
+    return;
+  }
+  if (!opts.command) {
+    process.stderr.write(color.red('error: no server command given\n\n'));
+    process.stderr.write(HELP + '\n');
+    process.exit(2);
+  }
+
+  const result = await runDiagnostics({
+    command: opts.command,
+    args: opts.args,
+    timeout: opts.timeout,
+    call: opts.call,
+  });
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else {
+    renderHuman(result);
+  }
+
+  process.exit(result.ok ? 0 : 1);
+}
+
+main().catch((err) => {
+  process.stderr.write(color.red(`unexpected error: ${err?.stack || err}\n`));
+  process.exit(2);
+});

package/examples/echo-server.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// A minimal, valid stdio MCP server used to exercise mcp-probe end to end.
+// It speaks newline-delimited JSON-RPC 2.0 and exposes two trivial tools:
+//   echo(text) -> returns the same text
+//   add(a, b)  -> returns a + b
+//   ping()     -> returns "pong" (no required params, safe to round-trip)
+//
+// This is intentionally hand-rolled (no SDK) to keep the example dependency
+// free and self-contained.
+
+const PROTOCOL_VERSION = '2025-06-18';
+
+const TOOLS = [
+  {
+    name: 'echo',
+    title: 'Echo',
+    description: 'Return the provided text unchanged.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'The text to echo back.' },
+      },
+      required: ['text'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'add',
+    title: 'Add',
+    description: 'Add two numbers and return the sum.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        a: { type: 'number', description: 'First addend.' },
+        b: { type: 'number', description: 'Second addend.' },
+      },
+      required: ['a', 'b'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'ping',
+    title: 'Ping',
+    description: 'Health check that returns "pong". Takes no parameters.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+];
+
+function send(msg) {
+  process.stdout.write(JSON.stringify(msg) + '\n');
+}
+
+function reply(id, result) {
+  send({ jsonrpc: '2.0', id, result });
+}
+
+function replyError(id, code, message) {
+  send({ jsonrpc: '2.0', id, error: { code, message } });
+}
+
+function textResult(text) {
+  return { content: [{ type: 'text', text }] };
+}
+
+function handle(msg) {
+  const { id, method, params } = msg;
+
+  // Notifications (no id) require no response.
+  if (id === undefined || id === null) return;
+
+  switch (method) {
+    case 'initialize':
+      reply(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: 'echo-server', version: '1.0.0' },
+      });
+      break;
+
+    case 'tools/list':
+      reply(id, { tools: TOOLS });
+      break;
+
+    case 'tools/call': {
+      const name = params?.name;
+      const args = params?.arguments || {};
+      if (name === 'echo') {
+        reply(id, textResult(String(args.text ?? '')));
+      } else if (name === 'add') {
+        reply(id, textResult(String(Number(args.a) + Number(args.b))));
+      } else if (name === 'ping') {
+        reply(id, textResult('pong'));
+      } else {
+        replyError(id, -32602, `unknown tool: ${name}`);
+      }
+      break;
+    }
+
+    default:
+      replyError(id, -32601, `method not found: ${method}`);
+  }
+}
+
+let buffer = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  buffer += chunk;
+  let idx;
+  while ((idx = buffer.indexOf('\n')) !== -1) {
+    const line = buffer.slice(0, idx).trim();
+    buffer = buffer.slice(idx + 1);
+    if (!line) continue;
+    try {
+      handle(JSON.parse(line));
+    } catch {
+      // Ignore malformed input on the example server.
+    }
+  }
+});
+process.stdin.on('end', () => process.exit(0));

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@hafsar/mcp-probe",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Lint and health-check any Model Context Protocol (MCP) server over stdio. Handshake, tools/list, JSON Schema validation, latency, and safe round-trips.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "cli",
+    "linter",
+    "ai",
+    "llm",
+    "diagnostics"
+  ],
+  "author": "Haseeb Mohammed Afsar",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "mcp-probe": "bin/mcp-probe.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/itguruhaseeb/mcp-probe.git"
+  },
+  "homepage": "https://github.com/itguruhaseeb/mcp-probe#readme",
+  "bugs": {
+    "url": "https://github.com/itguruhaseeb/mcp-probe/issues"
+  },
+  "files": [
+    "bin",
+    "src",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "start": "node bin/mcp-probe.js"
+  }
+}

package/src/client.js

@@ -0,0 +1,206 @@
+// Minimal MCP (Model Context Protocol) client that speaks JSON-RPC 2.0 to a
+// stdio server over a child process's stdin/stdout.
+//
+// MCP stdio transport frames messages as newline-delimited JSON: each JSON-RPC
+// message is a single line terminated by '\n', with no embedded newlines. We
+// implement exactly that here rather than pulling in @modelcontextprotocol/sdk,
+// which keeps mcp-probe dependency-light and demonstrates the wire protocol.
+// (Swapping in the official SDK's StdioClientTransport is a reasonable future
+// option once we want richer transport support such as HTTP/SSE.)
+
+import { spawn } from 'node:child_process';
+
+// The protocol version mcp-probe advertises during initialize. Servers may
+// negotiate a different one back; we surface whatever they return.
+export const PROTOCOL_VERSION = '2025-06-18';
+
+export class McpError extends Error {
+  constructor(message, { code, data } = {}) {
+    super(message);
+    this.name = 'McpError';
+    this.code = code;
+    this.data = data;
+  }
+}
+
+export class McpClient {
+  /**
+   * @param {string} command  executable to launch (e.g. "node", "python")
+   * @param {string[]} args   arguments for that executable
+   * @param {object} opts
+   * @param {number} opts.timeout  per-request timeout in ms
+   */
+  constructor(command, args = [], { timeout = 10000 } = {}) {
+    this.command = command;
+    this.args = args;
+    this.timeout = timeout;
+
+    this.child = null;
+    this._nextId = 1;
+    this._pending = new Map(); // id -> { resolve, reject, timer }
+    this._buffer = '';
+    this._stderr = '';
+    this._closed = false;
+    this._closeReason = null;
+  }
+
+  start() {
+    this.child = spawn(this.command, this.args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: process.env,
+    });
+
+    this.child.stdout.setEncoding('utf8');
+    this.child.stdout.on('data', (chunk) => this._onStdout(chunk));
+
+    this.child.stderr.setEncoding('utf8');
+    this.child.stderr.on('data', (chunk) => {
+      // Keep a bounded tail of stderr for diagnostics.
+      this._stderr = (this._stderr + chunk).slice(-4000);
+    });
+
+    this.child.on('error', (err) => {
+      this._fail(new McpError(`failed to launch "${this.command}": ${err.message}`));
+    });
+
+    this.child.on('exit', (code, signal) => {
+      const reason =
+        signal != null
+          ? `server exited via signal ${signal}`
+          : `server exited with code ${code}`;
+      this._closeReason = reason;
+      this._fail(new McpError(reason, { data: { stderr: this._stderr.trim() } }));
+    });
+  }
+
+  _onStdout(chunk) {
+    this._buffer += chunk;
+    let idx;
+    while ((idx = this._buffer.indexOf('\n')) !== -1) {
+      const line = this._buffer.slice(0, idx).trim();
+      this._buffer = this._buffer.slice(idx + 1);
+      if (line === '') continue;
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        // Non-JSON noise on stdout is a protocol violation for stdio MCP.
+        // Record it but keep going; the linter surfaces it as a warning.
+        this._nonJsonLines = (this._nonJsonLines || []);
+        this._nonJsonLines.push(line);
+        continue;
+      }
+      this._dispatch(msg);
+    }
+  }
+
+  _dispatch(msg) {
+    // We only issue requests, so we care about responses keyed by id.
+    // Notifications/requests from the server are ignored for the MVP.
+    if (msg.id === undefined || msg.id === null) return;
+    const pending = this._pending.get(msg.id);
+    if (!pending) return;
+    this._pending.delete(msg.id);
+    clearTimeout(pending.timer);
+    if (msg.error) {
+      pending.reject(
+        new McpError(msg.error.message || 'server returned an error', {
+          code: msg.error.code,
+          data: msg.error.data,
+        })
+      );
+    } else {
+      pending.resolve(msg.result);
+    }
+  }
+
+  _fail(err) {
+    if (this._closed) return;
+    this._closed = true;
+    for (const [, pending] of this._pending) {
+      clearTimeout(pending.timer);
+      pending.reject(err);
+    }
+    this._pending.clear();
+  }
+
+  _send(obj) {
+    if (this._closed) throw new McpError(this._closeReason || 'connection closed');
+    this.child.stdin.write(JSON.stringify(obj) + '\n');
+  }
+
+  /** Send a JSON-RPC request and await its result. */
+  request(method, params) {
+    const id = this._nextId++;
+    const payload = { jsonrpc: '2.0', id, method };
+    if (params !== undefined) payload.params = params;
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._pending.delete(id);
+        reject(new McpError(`timed out after ${this.timeout}ms waiting for "${method}"`));
+      }, this.timeout);
+      this._pending.set(id, { resolve, reject, timer });
+      try {
+        this._send(payload);
+      } catch (err) {
+        clearTimeout(timer);
+        this._pending.delete(id);
+        reject(err);
+      }
+    });
+  }
+
+  /** Send a JSON-RPC notification (no id, no response expected). */
+  notify(method, params) {
+    const payload = { jsonrpc: '2.0', method };
+    if (params !== undefined) payload.params = params;
+    this._send(payload);
+  }
+
+  /** Perform the MCP initialize handshake. Returns the server's result. */
+  async initialize() {
+    const result = await this.request('initialize', {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: 'mcp-probe', version: '0.1.0' },
+    });
+    // Per spec the client confirms readiness before making other calls.
+    this.notify('notifications/initialized');
+    return result;
+  }
+
+  get nonJsonLines() {
+    return this._nonJsonLines || [];
+  }
+
+  async close() {
+    this._closed = true;
+    if (!this.child) return;
+    for (const [, pending] of this._pending) clearTimeout(pending.timer);
+    this._pending.clear();
+    try {
+      this.child.stdin.end();
+    } catch {
+      // ignore
+    }
+    // Give the child a moment to exit cleanly, then force it.
+    await new Promise((resolve) => {
+      if (this.child.exitCode !== null || this.child.signalCode !== null) {
+        return resolve();
+      }
+      const t = setTimeout(() => {
+        try {
+          this.child.kill('SIGKILL');
+        } catch {
+          // ignore
+        }
+        resolve();
+      }, 500);
+      this.child.once('exit', () => {
+        clearTimeout(t);
+        resolve();
+      });
+    });
+  }
+}

package/src/color.js

@@ -0,0 +1,31 @@
+// Tiny zero-dependency ANSI color helper.
+// Respects NO_COLOR (https://no-color.org) and non-TTY output.
+
+const enabled =
+  process.env.NO_COLOR === undefined &&
+  process.env.TERM !== 'dumb' &&
+  process.stdout.isTTY === true;
+
+function wrap(open, close) {
+  return (s) => (enabled ? `[${open}m${s}[${close}m` : String(s));
+}
+
+export const color = {
+  enabled,
+  bold: wrap(1, 22),
+  dim: wrap(2, 22),
+  red: wrap(31, 39),
+  green: wrap(32, 39),
+  yellow: wrap(33, 39),
+  blue: wrap(34, 39),
+  cyan: wrap(36, 39),
+  gray: wrap(90, 39),
+};
+
+// Status glyphs used across the report.
+export const glyph = {
+  pass: () => color.green('✓'),
+  warn: () => color.yellow('!'),
+  fail: () => color.red('✗'),
+  info: () => color.cyan('•'),
+};

package/src/linter.js

@@ -0,0 +1,193 @@
+// JSON Schema and metadata linting for MCP tool definitions.
+//
+// MCP tools declare an `inputSchema` that is a JSON Schema object (draft 2020-12
+// in practice, though servers vary). Clients and LLMs rely on that schema to
+// construct valid tool calls, so a malformed schema is a real correctness bug.
+// These checks catch the mistakes we see most often in the wild without pulling
+// in a full JSON Schema validator.
+
+const VALID_TYPES = new Set([
+  'string',
+  'number',
+  'integer',
+  'boolean',
+  'object',
+  'array',
+  'null',
+]);
+
+// Severity levels, ordered.
+export const FAIL = 'fail';
+export const WARN = 'warn';
+
+function issue(severity, message) {
+  return { severity, message };
+}
+
+/**
+ * Lint a single JSON Schema object (an MCP inputSchema).
+ * Returns an array of { severity, message } issues. Empty means clean.
+ *
+ * `path` is a human-readable prefix for nested reporting (e.g. "properties.foo").
+ */
+export function lintSchema(schema, path = 'inputSchema') {
+  const issues = [];
+
+  if (schema === undefined || schema === null) {
+    issues.push(issue(FAIL, `${path} is missing`));
+    return issues;
+  }
+  if (typeof schema !== 'object' || Array.isArray(schema)) {
+    issues.push(issue(FAIL, `${path} must be a JSON object, got ${describe(schema)}`));
+    return issues;
+  }
+
+  // `type` is not strictly required by JSON Schema, but MCP input schemas
+  // should be objects. A missing type on the root is worth a warning.
+  const type = schema.type;
+  if (type === undefined) {
+    if (path === 'inputSchema') {
+      issues.push(issue(WARN, `${path} has no "type" (expected "object")`));
+    }
+  } else if (typeof type === 'string') {
+    if (!VALID_TYPES.has(type)) {
+      issues.push(issue(FAIL, `${path}.type "${type}" is not a valid JSON Schema type`));
+    }
+    if (path === 'inputSchema' && type !== 'object') {
+      issues.push(
+        issue(WARN, `${path}.type is "${type}"; MCP input schemas are conventionally objects`)
+      );
+    }
+  } else if (Array.isArray(type)) {
+    for (const t of type) {
+      if (!VALID_TYPES.has(t)) {
+        issues.push(issue(FAIL, `${path}.type contains invalid entry "${t}"`));
+      }
+    }
+  } else {
+    issues.push(issue(FAIL, `${path}.type must be a string or array of strings`));
+  }
+
+  // properties must be an object-of-schemas when present.
+  const props = schema.properties;
+  let propKeys = [];
+  if (props !== undefined) {
+    if (typeof props !== 'object' || Array.isArray(props) || props === null) {
+      issues.push(issue(FAIL, `${path}.properties must be an object`));
+    } else {
+      propKeys = Object.keys(props);
+      for (const key of propKeys) {
+        const sub = props[key];
+        if (typeof sub !== 'object' || sub === null || Array.isArray(sub)) {
+          issues.push(issue(FAIL, `${path}.properties.${key} must be a schema object`));
+          continue;
+        }
+        // Recurse one level for object/array property schemas.
+        for (const sublint of lintSchema(sub, `${path}.properties.${key}`)) {
+          // Downgrade the "no type" root-only rule; nested is only warned when clearly wrong.
+          issues.push(sublint);
+        }
+        if (sub.description === undefined && sub.type !== 'object') {
+          // Missing per-property descriptions hurt LLM tool use but are common;
+          // keep this quiet to avoid noise. Intentionally not reported.
+        }
+      }
+    }
+  }
+
+  // required[] must be an array of strings that all exist in properties.
+  const required = schema.required;
+  if (required !== undefined) {
+    if (!Array.isArray(required)) {
+      issues.push(issue(FAIL, `${path}.required must be an array`));
+    } else {
+      const seen = new Set();
+      for (const r of required) {
+        if (typeof r !== 'string') {
+          issues.push(issue(FAIL, `${path}.required contains a non-string entry`));
+          continue;
+        }
+        if (seen.has(r)) {
+          issues.push(issue(WARN, `${path}.required lists "${r}" more than once`));
+        }
+        seen.add(r);
+        if (props !== undefined && !propKeys.includes(r)) {
+          issues.push(
+            issue(FAIL, `${path}.required references "${r}" which is not in properties`)
+          );
+        }
+      }
+      if (required.length > 0 && props === undefined) {
+        issues.push(
+          issue(FAIL, `${path}.required is set but there are no properties to require`)
+        );
+      }
+    }
+  }
+
+  // An object schema with neither properties nor a permissive marker is an
+  // empty contract. Common but worth flagging on the root.
+  if (
+    path === 'inputSchema' &&
+    (type === 'object' || type === undefined) &&
+    props === undefined &&
+    schema.additionalProperties === undefined
+  ) {
+    issues.push(
+      issue(WARN, `${path} declares no properties (tool takes no structured input)`)
+    );
+  }
+
+  return issues;
+}
+
+/**
+ * Lint a full MCP tool descriptor: { name, description, inputSchema, ... }.
+ * Returns { name, issues, schemaIssueCount, ... }.
+ */
+export function lintTool(tool) {
+  const issues = [];
+  const name = typeof tool?.name === 'string' ? tool.name : '(unnamed)';
+
+  if (typeof tool?.name !== 'string' || tool.name.trim() === '') {
+    issues.push(issue(FAIL, 'tool is missing a "name"'));
+  }
+
+  if (typeof tool?.description !== 'string' || tool.description.trim() === '') {
+    issues.push(issue(WARN, 'tool has no "description" (LLMs rely on it to choose the tool)'));
+  }
+
+  // `title` is an optional human-facing label in recent MCP revisions.
+  if (tool?.title === undefined && tool?.annotations?.title === undefined) {
+    issues.push(issue(WARN, 'tool has no "title" annotation'));
+  }
+
+  issues.push(...lintSchema(tool?.inputSchema, 'inputSchema'));
+
+  return {
+    name,
+    issues,
+    fails: issues.filter((i) => i.severity === FAIL).length,
+    warns: issues.filter((i) => i.severity === WARN).length,
+  };
+}
+
+function describe(v) {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'array';
+  return typeof v;
+}
+
+/**
+ * Decide whether a tool can be safely round-tripped with empty/minimal args.
+ * A tool is "safe to call" for our purposes when it has no required parameters,
+ * so we never fabricate values. Returns { safe: boolean, args: object }.
+ */
+export function safeCallArgs(tool) {
+  const schema = tool?.inputSchema;
+  const required = Array.isArray(schema?.required) ? schema.required : [];
+  if (required.length === 0) {
+    return { safe: true, args: {} };
+  }
+  return { safe: false, args: null };
+}

package/src/report.js

@@ -0,0 +1,292 @@
+// Orchestrates a full health check against an MCP server and renders the report
+// either as colorized human output or as a machine-readable JSON document.
+
+import { McpClient, McpError, PROTOCOL_VERSION } from './client.js';
+import { lintTool, safeCallArgs, FAIL, WARN } from './linter.js';
+import { color, glyph } from './color.js';
+
+function now() {
+  return Number(process.hrtime.bigint() / 1000000n); // ms as integer
+}
+
+async function timed(fn) {
+  const start = process.hrtime.bigint();
+  const value = await fn();
+  const ms = Number(process.hrtime.bigint() - start) / 1e6;
+  return { value, ms: Math.round(ms * 10) / 10 };
+}
+
+/**
+ * Run the full diagnostic. Returns a structured result object regardless of
+ * output format, so both the human renderer and --json consume the same data.
+ *
+ * @param {object} opts
+ * @param {string} opts.command
+ * @param {string[]} opts.args
+ * @param {number} opts.timeout
+ * @param {boolean} opts.call   attempt safe round-trips
+ */
+export async function runDiagnostics({ command, args, timeout, call }) {
+  const result = {
+    tool: 'mcp-probe',
+    version: '0.1.0',
+    target: [command, ...args].join(' '),
+    clientProtocolVersion: PROTOCOL_VERSION,
+    ok: true,
+    server: null,
+    capabilities: null,
+    timings: {},
+    tools: [],
+    resources: null,
+    prompts: null,
+    calls: [],
+    warnings: [],
+    errors: [],
+  };
+
+  const client = new McpClient(command, args, { timeout });
+  client.start();
+
+  try {
+    // 1. Handshake.
+    let init;
+    try {
+      const t = await timed(() => client.initialize());
+      init = t.value;
+      result.timings.handshakeMs = t.ms;
+    } catch (err) {
+      result.ok = false;
+      result.errors.push(`handshake failed: ${err.message}`);
+      if (err instanceof McpError && err.data?.stderr) {
+        result.errors.push(`server stderr: ${err.data.stderr}`);
+      }
+      return result;
+    }
+
+    result.server = init?.serverInfo || null;
+    result.capabilities = init?.capabilities || {};
+    result.negotiatedProtocolVersion = init?.protocolVersion || null;
+
+    if (init?.protocolVersion && init.protocolVersion !== PROTOCOL_VERSION) {
+      result.warnings.push(
+        `server negotiated protocol ${init.protocolVersion} (client offered ${PROTOCOL_VERSION})`
+      );
+    }
+
+    const caps = result.capabilities || {};
+
+    // 2. tools/list (only if declared, but many servers expose it regardless).
+    if (caps.tools !== undefined || true) {
+      try {
+        const t = await timed(() => client.request('tools/list', {}));
+        result.timings.toolsListMs = t.ms;
+        const tools = Array.isArray(t.value?.tools) ? t.value.tools : [];
+        for (const tool of tools) {
+          const linted = lintTool(tool);
+          result.tools.push({
+            name: linted.name,
+            description: tool.description || null,
+            issues: linted.issues,
+            fails: linted.fails,
+            warns: linted.warns,
+            safeToCall: safeCallArgs(tool).safe,
+          });
+          if (linted.fails > 0) result.ok = false;
+        }
+      } catch (err) {
+        if (caps.tools !== undefined) {
+          result.ok = false;
+          result.errors.push(`tools/list failed: ${err.message}`);
+        } else {
+          result.warnings.push(`tools/list not available: ${err.message}`);
+        }
+      }
+    }
+
+    // 3. resources/list, if declared.
+    if (caps.resources !== undefined) {
+      try {
+        const t = await timed(() => client.request('resources/list', {}));
+        result.timings.resourcesListMs = t.ms;
+        result.resources = { count: Array.isArray(t.value?.resources) ? t.value.resources.length : 0 };
+      } catch (err) {
+        result.warnings.push(`resources/list failed: ${err.message}`);
+      }
+    }
+
+    // 4. prompts/list, if declared.
+    if (caps.prompts !== undefined) {
+      try {
+        const t = await timed(() => client.request('prompts/list', {}));
+        result.timings.promptsListMs = t.ms;
+        result.prompts = { count: Array.isArray(t.value?.prompts) ? t.value.prompts.length : 0 };
+      } catch (err) {
+        result.warnings.push(`prompts/list failed: ${err.message}`);
+      }
+    }
+
+    // 5. Optional safe round-trips.
+    if (call && result.tools.length > 0) {
+      // We need the raw tool list again to build args; re-fetch is cheap and
+      // avoids threading raw descriptors through the linted view.
+      let rawTools = [];
+      try {
+        const listed = await client.request('tools/list', {});
+        rawTools = Array.isArray(listed?.tools) ? listed.tools : [];
+      } catch {
+        rawTools = [];
+      }
+      for (const tool of rawTools) {
+        const { safe, args: callArgs } = safeCallArgs(tool);
+        if (!safe) {
+          result.calls.push({ name: tool.name, skipped: true, reason: 'has required parameters' });
+          continue;
+        }
+        try {
+          const t = await timed(() =>
+            client.request('tools/call', { name: tool.name, arguments: callArgs })
+          );
+          const isError = t.value?.isError === true;
+          result.calls.push({
+            name: tool.name,
+            skipped: false,
+            ok: !isError,
+            ms: t.ms,
+            isError,
+          });
+          if (isError) {
+            result.warnings.push(`tools/call "${tool.name}" returned isError=true`);
+          }
+        } catch (err) {
+          result.calls.push({ name: tool.name, skipped: false, ok: false, error: err.message });
+          result.warnings.push(`tools/call "${tool.name}" failed: ${err.message}`);
+        }
+      }
+    }
+
+    // Surface any non-JSON stdout noise as a protocol warning.
+    if (client.nonJsonLines.length > 0) {
+      result.warnings.push(
+        `server wrote ${client.nonJsonLines.length} non-JSON line(s) to stdout (breaks stdio framing)`
+      );
+    }
+
+    return result;
+  } finally {
+    await client.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Human renderer
+// ---------------------------------------------------------------------------
+
+export function renderHuman(r, out = process.stdout) {
+  const lines = [];
+  const p = (s = '') => lines.push(s);
+
+  p();
+  p(color.bold(`mcp-probe ${color.dim('v' + r.version)}`));
+  p(color.gray(`target: ${r.target}`));
+  p();
+
+  // Handshake section.
+  p(color.bold('Handshake'));
+  if (r.errors.length && !r.server) {
+    for (const e of r.errors) p(`  ${glyph.fail()} ${e}`);
+    p();
+    p(section('Summary', r));
+    out.write(lines.join('\n') + '\n');
+    return;
+  }
+  const s = r.server || {};
+  p(`  ${glyph.pass()} initialized in ${fmtMs(r.timings.handshakeMs)}`);
+  p(`  ${glyph.info()} server: ${color.cyan(s.name || 'unknown')} ${color.dim(s.version ? 'v' + s.version : '')}`.trimEnd());
+  if (r.negotiatedProtocolVersion) {
+    p(`  ${glyph.info()} protocol: ${r.negotiatedProtocolVersion}`);
+  }
+  const capNames = Object.keys(r.capabilities || {});
+  p(`  ${glyph.info()} capabilities: ${capNames.length ? capNames.join(', ') : color.dim('none declared')}`);
+  p();
+
+  // Tools section.
+  p(color.bold(`Tools ${color.dim(`(${r.tools.length})`)}`));
+  if (r.tools.length === 0) {
+    p(`  ${color.dim('no tools listed')}`);
+  }
+  for (const tool of r.tools) {
+    const g = tool.fails > 0 ? glyph.fail() : tool.warns > 0 ? glyph.warn() : glyph.pass();
+    const meta = [];
+    if (tool.fails) meta.push(color.red(`${tool.fails} error${tool.fails > 1 ? 's' : ''}`));
+    if (tool.warns) meta.push(color.yellow(`${tool.warns} warning${tool.warns > 1 ? 's' : ''}`));
+    const suffix = meta.length ? color.dim(': ') + meta.join(color.dim(', ')) : '';
+    p(`  ${g} ${color.bold(tool.name)}${suffix}`);
+    for (const iss of tool.issues) {
+      const ig = iss.severity === FAIL ? glyph.fail() : glyph.warn();
+      p(`      ${ig} ${iss.message}`);
+    }
+  }
+  if (r.timings.toolsListMs !== undefined) {
+    p(`  ${color.dim(`tools/list in ${fmtMs(r.timings.toolsListMs)}`)}`);
+  }
+  p();
+
+  // Resources / prompts.
+  if (r.resources || r.prompts) {
+    p(color.bold('Other'));
+    if (r.resources) p(`  ${glyph.info()} resources: ${r.resources.count}`);
+    if (r.prompts) p(`  ${glyph.info()} prompts: ${r.prompts.count}`);
+    p();
+  }
+
+  // Calls.
+  if (r.calls.length) {
+    p(color.bold('Round-trips (--call)'));
+    for (const c of r.calls) {
+      if (c.skipped) {
+        p(`  ${glyph.info()} ${c.name} ${color.dim('skipped (' + c.reason + ')')}`);
+      } else if (c.ok) {
+        p(`  ${glyph.pass()} ${c.name} ${color.dim('returned in ' + fmtMs(c.ms))}`);
+      } else {
+        p(`  ${glyph.fail()} ${c.name} ${color.red(c.error || 'returned isError')}`);
+      }
+    }
+    p();
+  }
+
+  // Warnings not tied to a specific tool.
+  if (r.warnings.length) {
+    p(color.bold('Warnings'));
+    for (const w of r.warnings) p(`  ${glyph.warn()} ${w}`);
+    p();
+  }
+
+  p(section('Summary', r));
+  out.write(lines.join('\n') + '\n');
+}
+
+function section(title, r) {
+  const totalFails =
+    r.errors.length + r.tools.reduce((n, t) => n + t.fails, 0);
+  const totalWarns =
+    r.warnings.length + r.tools.reduce((n, t) => n + t.warns, 0);
+  const parts = [];
+  parts.push(`${r.tools.length} tool${r.tools.length === 1 ? '' : 's'}`);
+  if (totalFails === 0) {
+    parts.push(color.green('0 errors'));
+  } else {
+    parts.push(color.red(`${totalFails} error${totalFails === 1 ? '' : 's'}`));
+  }
+  parts.push(
+    totalWarns === 0
+      ? color.dim('0 warnings')
+      : color.yellow(`${totalWarns} warning${totalWarns === 1 ? '' : 's'}`)
+  );
+  const verdict = r.ok ? color.green('healthy') : color.red('unhealthy');
+  return `${color.bold(title)}: ${verdict} ${color.dim('(' + parts.join(', ') + ')')}`;
+}
+
+function fmtMs(ms) {
+  if (ms === undefined || ms === null) return 'n/a';
+  return `${ms}ms`;
+}