Skip to content
reaatechREAATECH

@reaatech/mcp-server-doctor-cli

npm v1.0.0

A CLI that runs a full diagnostic suite against an MCP server endpoint, compares reports to detect regressions, or continuously monitors an endpoint for grade drops. It ships the `doctor` and `mcp-server-doctor` binaries.

@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