Skip to main content
Glama
deenesjakoruzh
pardovot

mcp-flightcheck

by pardovot
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript

mcp-flightcheck

在用户之前尝试破坏你的 MCP 服务器。它会执行正常的客户端启动，然后发送客户端通常不会发送的内容：没有工具名称的调用、未知方法、缺少必需参数的工具调用，并监控崩溃、挂起以及不应运行的工具的运行情况。你会得到一份评分卡，每项发现都会引用背后的规范条款，并且 CI 会收到非零退出码。

我针对官方注册表中的所有远程服务器运行了它，共 6,892 个。在那些甚至接受连接的服务器中，四分之一未能通过检查，七分之一完全损坏，它们崩溃、挂起或执行了一个未指定工具名称的 tools/call。官方 Inspector 是交互式的，不会导致构建失败，因此这些问题在发布前都不会被发现。

$ npx mcp-flightcheck node dist/server.js

mcp-flightcheck | my-server 1.4.0 (node dist/server.js)

Protocol conformance
  PASS  Declared capabilities actually work - declared capabilities respond: tools
  PASS  Responds to ping - ping answered
  PASS  Rejects unknown methods - unknown method rejected with -32601 (method not found)
  WARN  Rejects malformed request params - malformed params surfaced as -32603, expected -32602

Tool quality
  PASS  tools/list works - listed 12 tools
  FAIL  Every tool has a valid input schema - 3 of 12 tools have missing or broken input schemas
          delete_item: no inputSchema at all (official SDK clients reject the entire tool list over this)
  PASS  Tool names are unique and well-formed - all tool names unique and well-formed

Reliability
  PASS  Responds quickly - median tools/list latency 11ms
  FAIL  Tools reject invalid arguments cleanly - invalid arguments crashed the server (probed 10 tools)
          update_config: server crashed
  FAIL  Server still healthy after all probes - server is gone after probing, it crashed somewhere above

Hygiene
  PASS  Server identifies itself - my-server 1.4.0
  WARN  Every tool has a description - 2 of 12 tools have no description

NOT READY  7 pass, 2 warn, 3 fail, 0 skip (1840ms)

安装

npx mcp-flightcheck <your server>     # no install
npm i -D mcp-flightcheck              # or as a dev dependency

需要 Node 20+。

Related MCP server: mcp-test-server

用法

mcp-flightcheck node dist/server.js           # stdio server
mcp-flightcheck python -m my_mcp_server       # any command, any language
mcp-flightcheck https://example.com/mcp       # Streamable HTTP server

mcp-flightcheck --json node dist/server.js    # machine-readable report
mcp-flightcheck --strict node dist/server.js  # warnings also fail the run
mcp-flightcheck --no-probe node server.js     # skip invalid-argument probing
mcp-flightcheck --timeout 30000 slow-server   # per-request timeout in ms

认证（在 CI 中测试你自己的受限服务器）

大多数生产环境中的远程服务器都需要令牌，这正是你希望在 CI 中加以限制的。使用 --bearer 传递令牌，或使用 --header（可重复）设置任意标头：

mcp-flightcheck --strict --bearer "$MCP_TOKEN" https://your-server/mcp
mcp-flightcheck --header "X-Api-Key: $API_KEY" --header "X-Tenant: acme" https://your-server/mcp

将令牌保存在 CI 机密中，并通过环境变量传递，如上所示。mcp-flightcheck 从不打印标头值，JSON 报告仅通过 URL 标识目标。认证标志适用于远程（http）目标；stdio 服务器通过自己的环境变量和参数获取凭据。

退出码：0 表示干净，1 表示有发现，2 表示无法连接或用法错误。直接将其放入 CI：

- run: npx mcp-flightcheck --strict node dist/server.js

检查内容

协议合规性

  • 未知方法被拒绝并返回 -32601，而不是挂起、崩溃或虚假成功。

  • 格式错误的请求参数返回清晰的 JSON-RPC 错误。

  • 按照规范要求，ping 得到响应。

  • 服务器声明的每个能力（工具、资源、提示）都实际响应。声明无法提供的内容会破坏客户端。

工具质量

  • tools/list 正常工作，并且分页不会陷入循环。

  • 每个工具都提供了 inputSchema，该模式可编译为 JSON Schema，且根节点为对象。缺少模式的服务器会被官方 SDK 客户端直接拒绝，而提供类型化模式是衡量公共服务器质量的最强区分因素。

  • 工具名称唯一且格式良好。存在描述，因为模型会据此进行路由。

可靠性

  • 无效参数探测：每个具有必需参数的工具都在缺少参数的情况下被调用。构建良好的服务器会在任何操作执行之前拒绝该调用。mcp-flightcheck 会标记那些仍然执行、挂起直到超时或导致整个进程崩溃的工具。

  • 中位 tools/list 延迟，因为代理在每次会话中都会支付这个开销。

  • 最终健康检查确保服务器在其自身的错误路径中存活下来。

失败分类与现实中导致故障的原因一致：模式不匹配、超时、崩溃、协议违规。

发现引用规范

每项发现都附带了其强制执行的条款，并逐字引用并附带链接：

WARN  Rejects malformed request params - malformed params surfaced as -32603, expected -32602
        MUST: -32602 Invalid params: Invalid method parameter(s). (JSON-RPC 2.0, which MCP messages MUST follow)
        https://www.jsonrpc.org/specification#error_object

没有规范条款支持规则会被标记为 HEURISTIC，这样你总能区分规范违规和主观判断。没有规范性基础的两项检查（探测后健康检查、延迟）不附带引用，而不是编造一个。

为什么默认启用探测

探测仅发送无效输入（缺少必需参数）。任何具有输入验证的服务器都会在副作用发生之前拒绝它。仍然执行的服务器存在你希望现在（而不是在生产环境中）知道的错误。如果你的工具即使在无效输入下也会产生副作用，请运行 --no-probe 并修复该问题。

编程 API

import { runChecks } from "mcp-flightcheck";

const report = await runChecks(client, "my-server", {
  timeoutMs: 10_000,
  probe: true,
  probeLimit: 10,
});
console.log(report.summary); // { pass, warn, fail, skip }

测试方式

mcp-flightcheck 通过一个一致性语料库进行验证：examples/ 中的一组虚拟 MCP 服务器，每个服务器代表一种原型（干净、缺少模式、无输入验证、调用时崩溃、调用时挂起、谎报能力、无 ping、无文档工具、匿名、未知方法时挂起）。每个原型都固定了 mcp-flightcheck 应返回的确切判定结果，test/corpus.test.ts 断言 mcp-flightcheck 能重现每一个结果。这是 mcp-flightcheck 自身的精确度/召回率门控：回归测试如果停止捕获缺陷，或开始标记干净服务器，则构建失败。

查看整个语料库针对每个原型的实时运行情况：

npm run demo

路线图

  • 跨协议版本的版本协商检查

  • 资源和提示内容验证

  • 用于 PR 评论的 --report md

  • 声明了 outputSchema 的工具的结构化输出验证

  • 公共可靠性数据集：针对官方注册表运行 mcp-flightcheck

许可证

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Everything

    s2005
    A
    license
    Not graded
    quality
    D
    maintenance
    A test server implementing all features of the MCP protocol, including prompts, tools, resources, and sampling, designed for testing MCP clients rather than practical applications.
    MIT