MCP Healthcheck

mcp健康检查

MCP（模型上下文协议）服务器的程序化健康和活性探针。

](https://www.npmjs.com/package/mcp-healthcheck) ](https://www.npmjs.com/package/mcp-healthcheck)  ](https://nodejs.org)

______________________________________________________________________

描述

mcp-healthcheck 通过任何支持的传输（stdio、Streamable HTTP或传统SSE）连接到MCP服务器，执行协议握手，枚举服务器的功能（工具、资源、提示），测量每个操作的延迟，并返回结构化的健康报告。它被设计为在自动化环境中无头运行——Kubernetes活性/就绪性探针、CI管道门、监控仪表板——在这些环境中，交互式调试工具是不可行的。

该包提供了用于编程的TypeScript/JavaScriptneneneba API，以及用于终端和shell脚本的CLI。API返回结构化 HealthReport 具有每次检查状态、延迟和错误详细信息的对象。CLI打印人类可读或JSON输出，并使用常规代码退出（0表示健康，1表示不健康，2表示配置错误，3表示降级）。

唯一的运行时依赖关系是 @modelcontextprotocol/sdk.

______________________________________________________________________

安装

npm install mcp-healthcheck @modelcontextprotocol/sdk

@modelcontextprotocol/sdk 是对等依赖，必须与此软件包一起安装。

仅用于CLI而不在本地安装：

npx mcp-healthcheck --stdio 'node ./server.js'

______________________________________________________________________

快速开始

程序化（TypeScript）

import { checkHealth } from 'mcp-healthcheck';

const report = await checkHealth({
  transport: {
    type: 'stdio',
    command: 'node',
    args: ['./my-mcp-server.js'],
  },
  timeout: 10_000,
});

console.log(report.status);  // 'healthy' | 'unhealthy' | 'degraded'
console.log(report.totalMs); // 342
console.log(report.checks);  // individual check results

命令行界面

# stdio transport
mcp-healthcheck --stdio 'node ./server.js'

# Streamable HTTP transport
mcp-healthcheck --url https://mcp.example.com/mcp --header 'Authorization:Bearer sk-...'

# Legacy SSE transport
mcp-healthcheck --sse http://localhost:3000/sse

# JSON output for scripting
mcp-healthcheck --stdio 'node ./server.js' --format json

# Quiet mode (exit code only)
mcp-healthcheck --url http://localhost:3000/mcp --quiet

______________________________________________________________________

特性

• 三种运输方式 --stdio（子进程）、流式HTTP和传统SSE。
• 完整的MCP生命周期验证 --传输连接、协议握手和功能枚举（工具、资源、提示）。
• 每次检查延迟测量 --每次检查都使用高分辨率计时 performance.now().
• 可配置阈值 --最小/最大工具计数、最小资源/提示计数和每次检查的最大延迟。
• 自定义检查 --用户定义的异步函数，用于接收连接的MCP Client 例如，针对特定领域的断言。
• 超时执行 --每次检查超时和总超时，并自动清理剩余的检查。
• 中止信号支持 --通过标准进行外部取消 AbortSignal 界面。
• 自动跳过 --对于服务器未声明的功能的检查将自动跳过，并传递结果。
• 结构化健康报告 --机器可读 HealthReport 具有状态、每次检查结果、摘要计数和服务器信息的对象。
• HTTP处理程序工厂 --在Express、Koa、Fastify或raw中挂载健康端点 http.createServer 只需一次函数调用。
• 具有确定性退出代码的CLI --0（健康），1（不健康），2（配置错误），3（降级）。
• 环境变量配置 --所有CLI标志都具有容器和CI环境的环境变量等效值。
• 子流程清理 --stdio传输总是终止（SIGTERM，然后是5秒后的SIGKILL），以防止僵尸进程。
• 从不投掷 -- checkHealth() 总是返回a HealthReport，捕获报告结构中的所有错误。

______________________________________________________________________

API 参考

checkHealth(options: HealthCheckOptions): Promise

主要API。连接到MCP服务器，运行所有健康检查，并返回结构化报告。此函数从不抛出；所有错误都记录在返回的报告中。

import { checkHealth } from 'mcp-healthcheck';

const report = await checkHealth({
  transport: {
    type: 'stdio',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
  },
});

if (report.status === 'healthy') {
  console.log(`${report.summary.passed}/${report.summary.total} checks passed in ${report.totalMs}ms.`);
} else {
  for (const check of report.checks.filter(c => !c.passed)) {
    console.error(`FAIL: ${check.name} -- ${check.error?.message}`);
  }
}

isHealthy(options: HealthCheckOptions): Promise

运行的便利功能 checkHealth 并返回 true 仅当状态为 'healthy'.退货 false 对两者 'unhealthy' 和 'degraded'.

import { isHealthy } from 'mcp-healthcheck';

const healthy = await isHealthy({
  transport: { type: 'stdio', command: 'node', args: ['./server.js'] },
});

if (!healthy) {
  process.exit(1);
}

createHttpHandler(options: HealthCheckOptions): (req: IncomingMessage, res: ServerResponse) => void

创建一个公开健康检查端点的HTTP请求处理程序。适用于安装在任何Node.js HTTP框架或原始 http.createServer.

• 获取 请求：运行 checkHealth(options) 并作出回应 200 OK （健康或退化）或 503 Service Unavailable （不健康），与 Content-Type: application/json 和那个 HealthReport 作为响应体。
• 任何其他方法：回复如下 405 Method Not Allowed.

import http from 'node:http';
import { createHttpHandler } from 'mcp-healthcheck';

const handler = createHttpHandler({
  transport: { type: 'stdio', command: 'node', args: ['./server.js'] },
  timeout: 10_000,
});

const server = http.createServer(handler);
server.listen(8080);

类型

HealthCheckOptions

传递给的主配置对象 checkHealth, isHealthy，以及 createHttpHandler.

TransportConfig

三种运输配置的区别性结合：

StdioTransportConfig

HttpTransportConfig

SseTransportConfig

Thresholds

CustomCheckFn

type CustomCheckFn = (client: Client) => Promise;

用户定义的异步函数，用于接收连接的MCP Client 实例并返回a CustomCheckResult.

CustomCheckResult

HealthReport

返回的完整健康报告 checkHealth.

HealthStatus

type HealthStatus = 'healthy' | 'unhealthy' | 'degraded';

• healthy --所有必需的检查均已通过，所有阈值均已满足。
• unhealthy --一个或多个必需的检查失败。
• degraded --所有必需的检查都通过了，但可选检查或延迟阈值失败。

CheckResult

专业检查结果详情：

______________________________________________________________________

配置

默认值

检查顺序

检查按此固定顺序运行。每次检查都取决于之前要求的检查是否成功。

如果 connect 或 initialize 如果失败，则跳过所有后续检查。

如果服务器没有声明能力（例如。， resources)，相应的检查将自动跳过 passed: true.

超时策略

超时在两个层面上执行：

• 每次检查超时 (checkTimeout)：每张支票都包裹在 Promise.race 有一个超时。如果检查超出此范围，则失败并返回错误代码 CHECK_TIMEOUT.
• 总体超时 (timeout)：主计时器为整个时间运行 checkHealth() 电话。如果它在所有检查完成之前触发，则跳过剩余的检查并返回错误代码 OVERALL_TIMEOUT.

两个超时级别都使用 AbortController 在内部与提供的任何来电者进行沟通 signal.

______________________________________________________________________

错误处理

checkHealth() 从不投掷。所有错误都在返回的 HealthReport未通过的检查包括 error 带有分类代码、消息和可选堆栈跟踪的对象。

错误代码

依赖失败传播

如果需要检查(connect 或 initialize)如果失败，则跳过所有后续检查，并记录一条指示先前失败的消息。即使早期检查失败，这也提供了一个完整的报告结构。

______________________________________________________________________

高级用法

自定义检查

自定义检查在标准检查后运行，并接收连接的MCP Client 例子每个检查都可以标记为 required （失败使状态 'unhealthy')或可选（失败使状态 'degraded'，这是默认设置）。

import { checkHealth } from 'mcp-healthcheck';

const report = await checkHealth({
  transport: { type: 'stdio', command: 'node', args: ['./server.js'] },
  customChecks: [
    {
      name: 'has-search-tool',
      required: true,
      fn: async (client) => {
        const { tools } = await client.listTools();
        const hasSearch = tools.some(t => t.name === 'search');
        return {
          passed: hasSearch,
          message: hasSearch ? 'search tool is registered' : 'search tool is missing',
        };
      },
    },
  ],
});

引发异常的自定义检查被视为失败，并带有错误代码 CUSTOM_CHECK_ERROR同步抛出和拒绝的promise都会被处理。

中止信号取消

通过A AbortSignal 要从外部取消健康检查：

import { checkHealth } from 'mcp-healthcheck';

const controller = new AbortController();
setTimeout(() => controller.abort(), 5_000);

const report = await checkHealth({
  transport: { type: 'stdio', command: 'node', args: ['./server.js'] },
  signal: controller.signal,
});

中止时，健康检查立即停止，并返回一个包含错误代码的不健康报告 ABORTED.

带阈值的HTTP传输

import { checkHealth } from 'mcp-healthcheck';

const report = await checkHealth({
  transport: {
    type: 'http',
    url: 'https://mcp.example.com/mcp',
    headers: { 'Authorization': 'Bearer sk-...' },
  },
  timeout: 15_000,
  checkTimeout: 5_000,
  thresholds: {
    maxLatencyMs: 2_000,
    minTools: 3,
  },
});

HTTP健康端点

在任何Node.js应用程序中将健康检查作为HTTP端点公开：

import http from 'node:http';
import { createHttpHandler } from 'mcp-healthcheck';

const handler = createHttpHandler({
  transport: { type: 'stdio', command: 'node', args: ['./server.js'] },
  timeout: 10_000,
});

const server = http.createServer(handler);
server.listen(8080);
// GET http://localhost:8080 -> 200 (healthy/degraded) or 503 (unhealthy)

Kubernetes生存性和就绪性探测

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-server
spec:
  template:
    spec:
      containers:
        - name: mcp-server
          image: my-mcp-server:latest
          ports:
            - containerPort: 3000
        - name: healthcheck
          image: node:20-slim
          command: ['sleep', 'infinity']
          livenessProbe:
            exec:
              command:
                - mcp-healthcheck
                - '--url'
                - 'http://localhost:3000/mcp'
                - '--timeout'
                - '5000'
                - '--skip'
                - 'resources'
                - '--skip'
                - 'prompts'
                - '--quiet'
            initialDelaySeconds: 15
            periodSeconds: 30
            timeoutSeconds: 8
            failureThreshold: 3
          readinessProbe:
            exec:
              command:
                - mcp-healthcheck
                - '--url'
                - 'http://localhost:3000/mcp'
                - '--timeout'
                - '5000'
                - '--min-tools'
                - '5'
                - '--quiet'
            initialDelaySeconds: 5
            periodSeconds: 10
            timeoutSeconds: 8
            failureThreshold: 1

CI管道闸门

- name: Wait for MCP server to be healthy
  run: |
    for i in $(seq 1 10); do
      npx mcp-healthcheck \
        --url http://localhost:3000/mcp \
        --timeout 5000 \
        --min-tools 3 \
        --format json \
        && exit 0
      echo "Attempt $i failed, retrying in 2s..."
      sleep 2
    done
    echo "MCP server failed to become healthy"
    exit 1

监控仪表板集成

import { checkHealth } from 'mcp-healthcheck';

const servers = [
  { name: 'search-server', transport: { type: 'http' as const, url: 'https://search.internal/mcp' } },
  { name: 'db-server', transport: { type: 'http' as const, url: 'https://db.internal/mcp' } },
];

const results = await Promise.all(
  servers.map(async (s) => ({
    name: s.name,
    report: await checkHealth({ transport: s.transport, timeout: 10_000 }),
  })),
);

for (const { name, report } of results) {
  console.log(`${name}: ${report.status} (${report.totalMs}ms)`);
}

______________________________________________________________________

CLI参考

mcp-healthcheck [options]

Transport (exactly one required):
  --stdio           Spawn an MCP server via stdio transport.
  --url                 Connect via Streamable HTTP transport.
  --sse                 Connect via legacy SSE transport.

Transport options:
  --header        Add an HTTP header (repeatable). For --url and --sse only.
  --cwd 
               Working directory for --stdio subprocess.
  --env           Environment variable for --stdio subprocess (repeatable).

Check options:
  --timeout              Overall timeout in milliseconds. Default: 30000.
  --check-timeout        Per-check timeout in milliseconds. Default: 10000.
  --skip              Skip a check (repeatable). Values: tools, resources, prompts.
  --min-tools             Minimum expected tool count.
  --max-tools             Maximum expected tool count.
  --min-resources         Minimum expected resource count.
  --min-prompts           Minimum expected prompt count.
  --max-latency          Maximum allowed latency per check.

Output options:
  --format           Output format: human, json. Default: human.
  --quiet                    Suppress all output except the exit code.
  --verbose                  Show detailed check information.

Meta:
  --version                  Print version and exit.
  --help                     Print help and exit.

退出代码

环境变量

所有CLI标志都可以通过环境变量设置。显式CLI标志覆盖环境变量。

人类可读输出示例

$ mcp-healthcheck --stdio 'node ./server.js' --min-tools 2

  mcp-healthcheck v0.2.0

  Target: stdio -- node ./server.js
  Status: healthy

  PASS  connect         12ms   stdio transport connected
  PASS  initialize      45ms   protocol v2025-06-18, server: my-server v1.0.0
  PASS  tools           28ms   5 tools: search, create, update, delete, list
  PASS  resources       15ms   2 resources
  PASS  prompts          8ms   1 prompt

  Summary: 5/5 passed in 108ms

______________________________________________________________________

TypeScript

这个包是用TypeScript编写的，并附带了类型声明(dist/index.d.ts).所有公共类型都从主入口点导出：

import {
  checkHealth,
  isHealthy,
  createHttpHandler,
  // Types
  type HealthCheckOptions,
  type HealthReport,
  type HealthStatus,
  type CheckResult,
  type ConnectCheckResult,
  type InitializeCheckResult,
  type ToolsCheckResult,
  type ResourcesCheckResult,
  type PromptsCheckResult,
  type CustomCheckCheckResult,
  type TransportConfig,
  type StdioTransportConfig,
  type HttpTransportConfig,
  type SseTransportConfig,
  type Thresholds,
  type CustomCheckFn,
  type CustomCheckResult,
} from 'mcp-healthcheck';

需要TypeScript 5.0或更高版本。该包使用CommonJS模块编译为ES2022。

______________________________________________________________________

许可证

麻省理工学院