Skip to content
reaatechREAATECH

@reaatech/mcp-server-doctor-cli

pending npm

Provides a CLI for diagnosing, comparing, and monitoring Model Context Protocol (MCP) server health via stdio, SSE, or HTTP transports. It generates diagnostic reports in multiple formats and supports regression analysis between test runs.

@reaatech/mcp-server-doctor-cli

npm version License: MIT CI

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

CLI for MCP server diagnostics — run a full health check suite, compare reports, or continuously monitor an endpoint. Ships the doctor and mcp-server-doctor binaries.

Installation

terminal
npm install -g @reaatech/mcp-server-doctor-cli
# or
pnpm add -g @reaatech/mcp-server-doctor-cli

Commands

doctor diagnose

Run the full 8-check diagnostic suite against an MCP server endpoint.

terminal
doctor diagnose <endpoint> [options]
OptionDefaultDescription
--transport <type>autoTransport type: stdio, sse, http, auto
--auth <mode>noneAuth mode: none, api-key, bearer, oauth
--api-key <key>API key (prefer MCP_API_KEY env var)
--bearer-token <token>Bearer token (prefer MCP_BEARER_TOKEN env var)
--oauth-client-id <id>OAuth client ID (prefer MCP_OAUTH_CLIENT_ID env var)
--oauth-client-secret <secret>OAuth client secret (prefer MCP_OAUTH_CLIENT_SECRET env var)
--format <format>consoleOutput format: console, json, markdown, html
--output <path>Write report to file
--verbosefalseShow detailed output
--timeout <ms>30000Request timeout in milliseconds
--concurrency <n>10Concurrency level for stress tests

Exit codes:

  • 0 — grade A, B, or C
  • 1 — grade F
  • 2 — grade D
  • 3 — crash / unreachable

Examples:

terminal
# Basic HTTP diagnosis
doctor diagnose http://localhost:8080
 
# With bearer token auth
doctor diagnose http://localhost:8080 --auth bearer --bearer-token $TOKEN
 
# Stdio transport (spawn a child process)
doctor diagnose /usr/local/bin/mcp-server --transport stdio
 
# JSON output to file
doctor diagnose http://localhost:8080 --format json --output report.json
 
# HTML report
doctor diagnose http://localhost:8080 --format html --output report.html

doctor compare

Compare two diagnostic reports and highlight regressions.

terminal
doctor compare <baseline> <current> [options]
OptionDefaultDescription
--format <format>consoleOutput format: console, json, markdown, html
--output <path>Write report to file

Exit codes:

  • 0 — no regression
  • 1 — grade regressed
  • 3 — report file not found or invalid

Examples:

terminal
# Compare two JSON reports
doctor compare baseline.json current.json
 
# With markdown output
doctor compare baseline.json current.json --format markdown --output diff.md

The comparison report includes:

  • Overall grade change (improved / regressed / unchanged)
  • Per-check grade changes
  • Latency delta (p99 change in ms)
  • Tool count change

doctor watch

Continuously monitor an MCP endpoint and alert on grade drops.

terminal
doctor watch <endpoint> [options]
OptionDefaultDescription
--interval <seconds>60Check interval in seconds (minimum 10)
--alert-threshold <grade>CAlert when grade drops below this threshold
--transport <type>autoTransport type: stdio, sse, http, auto
--auth <mode>noneAuth mode
--format <format>consoleOutput format
--output <path>Write report to file (overwritten each cycle)

Graceful shutdown on SIGINT (Ctrl+C) or SIGTERM.

Example:

terminal
# Monitor every 30 seconds, alert below B
doctor watch http://localhost:8080 --interval 30 --alert-threshold B

Programmatic Use

All commands are exported and can be used programmatically:

typescript
import { runDiagnoseCommand, runCompareCommand, runWatchCommand } from "@reaatech/mcp-server-doctor-cli";
 
// Run a diagnosis programmatically
await runDiagnoseCommand("http://localhost:8080", {
  transport: "http",
  auth: "bearer",
  bearerToken: process.env.MCP_BEARER_TOKEN,
  format: "json",
  output: "report.json",
  verbose: false,
  timeout: "30000",
  concurrency: "10",
});
 
// Compare two reports
await runCompareCommand("baseline.json", "current.json", {
  format: "console",
});
 
// Start monitoring
await runWatchCommand("http://localhost:8080", {
  interval: "60",
  alertThreshold: "C",
  transport: "http",
  auth: "none",
  format: "console",
});

Environment Variables

VariableDescription
MCP_API_KEYAPI key for api-key auth mode
MCP_BEARER_TOKENBearer token for bearer / oauth auth modes
MCP_OAUTH_CLIENT_IDOAuth client ID
MCP_OAUTH_CLIENT_SECRETOAuth client secret
DOCTOR_WATCH_MIN_INTERVAL_MSMinimum watch interval in ms (default: 10000)
OTEL_EXPORTER_OTLP_ENDPOINTSet to enable OpenTelemetry metrics and tracing
LOG_LEVELOverride log level (trace, debug, info, warn, error, fatal)
NODE_ENVproduction → raw JSON logs; otherwise → pretty-printed

License

MIT