mcp-flightcheck

Versucht, Ihren MCP-Server zu zerstören, bevor Ihre Benutzer es tun. Es führt den normalen Client-Start aus, sendet dann die Dinge, die ein Client normalerweise nicht senden würde – einen Aufruf ohne Toolnamen, eine unbekannte Methode, einen Tool-Aufruf mit fehlenden erforderlichen Argumenten – und beobachtet auf Abstürze, Hänger und Tools, die laufen, wenn sie nicht sollten. Sie erhalten eine Bewertungstabelle, bei der jeder Fund die dahinterstehende Spezifikationsklausel zitiert, und einen Exit-Code ungleich Null für CI.

Ich habe es gegen jeden Remote-Server im offiziellen Registry ausgeführt, 6.892 Stück. Von denen, die überhaupt eine Verbindung akzeptieren, fällt ein Viertel bei einer Prüfung durch und einer von sieben ist einfach kaputt: Sie stürzen ab, hängen oder führen einen tools/call aus, der kein Tool benennt. Der offizielle Inspector ist interaktiv, nichts baut einen Build fehlschlagen, daher wird nichts davon erfasst, bevor es ausgeliefert wird.

$ 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)

Installieren

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

Nutzung

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

Authentifizierung (eigenen gated Server in CI testen)

Die meisten produktiven Remote-Server erfordern ein Token, was genau das ist, was Sie in CI absichern möchten. Übergeben Sie eines mit --bearer oder setzen Sie beliebige Header mit --header (wiederholbar):

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

Bewahren Sie Tokens in CI-Geheimnissen auf und übergeben Sie sie per Umgebungsvariable, wie oben. mcp-flightcheck gibt niemals Header-Werte aus, und der JSON-Bericht identifiziert das Ziel nur per URL. Auth-Flags gelten für Remote- (http) Ziele; ein stdio-Server nimmt Anmeldedaten über seine eigenen Umgebungsvariablen und Argumente entgegen.

Exit-Codes: 0 sauber, 1 Befunde, 2 konnte nicht verbinden oder Nutzungsfehler. Werfen Sie es direkt in CI:

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

Was es prüft

Protokollkonformität

• Unbekannte Methoden werden mit -32601 abgelehnt, nicht mit einem Hänger, einem Absturz oder einem vorgetäuschten Erfolg.

• Fehlerhafte Anfrageparameter werden als sauberer JSON-RPC-Fehler zurückgegeben.

• ping wird beantwortet, wie es die Spezifikation verlangt.

• Jede Fähigkeit, die der Server deklariert (Tools, Ressourcen, Prompts), antwortet tatsächlich. Zu deklarieren, was man nicht bedienen kann, zerstört Clients.

Tool-Qualität

• tools/list funktioniert und paginiert ohne Schleifen.

• Jedes Tool liefert ein inputSchema, das als JSON-Schema kompiliert, mit einem Objekt-Root. Server ohne Schemas werden von offiziellen SDK-Clients sofort abgelehnt, und das Ausliefern typisierter Schemas ist der stärkste Qualitätsunterscheider, der bei öffentlichen Servern gemessen wurde.

• Tool-Namen sind eindeutig und wohlgeformt. Beschreibungen existieren, weil das Modell sich an ihnen orientiert.

Zuverlässigkeit

• Sondierung mit ungültigen Argumenten: Jedes Tool mit erforderlichen Argumenten wird ohne diese aufgerufen. Ein gut gebauter Server lehnt den Aufruf ab, bevor etwas ausgeführt wird. mcp-flightcheck markiert Tools, die trotzdem ausgeführt werden, bis zum Timeout hängen oder den gesamten Prozess zum Absturz bringen.

• Mittlere tools/list-Latenz, weil Agenten sie bei jeder Sitzung bezahlen.

• Eine abschließende Gesundheitsprüfung bestätigt, dass der Server seine eigenen Fehlerpfade überlebt hat.

Die Fehlerklassifizierung entspricht dem, was in der Praxis kaputtgeht: Schema-Fehlanpassung, Timeout, Absturz, Protokollverletzung.

Funde zitieren die Spezifikation

Jeder Fund trägt die Klausel, die er durchsetzt, wörtlich zitiert mit einem Link:

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

Regeln ohne dahinterliegende Klausel werden mit HEURISTIC gekennzeichnet, sodass Sie immer eine Spezifikationsverletzung von einer Ermessensentscheidung unterscheiden können. Die beiden Prüfungen ohne normative Grundlage (Post-Probe-Gesundheit, Latenz) tragen kein Zitat statt eines erfundenen.

Warum die Sondierung standardmäßig aktiviert ist

Die Sondierung sendet nur ungültige Eingaben (fehlende erforderliche Argumente). Ein Server mit irgendeiner Eingabevalidierung lehnt sie ab, bevor Nebenwirkungen auftreten können. Ein Server, der trotzdem ausführt, hat einen Fehler, den Sie jetzt kennen sollten, nicht in der Produktion. Wenn Ihre Tools auch bei ungültigen Eingaben Nebenwirkungen haben, führen Sie --no-probe aus und beheben Sie das.

Programmatische 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 }

Wie es getestet wird

mcp-flightcheck wird gegen ein Konformitätskorpus validiert: eine Galerie von Dummy-MCP-Servern in examples/, die jeweils einen Archetyp verkörpern (sauber, fehlendes Schema, keine Eingabevalidierung, stürzt beim Aufruf ab, hängt beim Aufruf, lügt über Fähigkeiten, kein Ping, undokumentierte Tools, anonym, hängt bei unbekannter Methode). Jeder ist auf das genaue Urteil festgelegt, das mcp-flightcheck zurückgeben soll, und test/corpus.test.ts stellt sicher, dass mcp-flightcheck jeden reproduziert. Dies ist das eigene Präzisions-/Recall-Gate von mcp-flightcheck: Eine Regression, die einen Fehler nicht mehr erkennt oder einen sauberen Server zu melden beginnt, lässt den Build fehlschlagen.

Sehen Sie die gesamte Galerie live gegen jeden Archetyp laufen:

npm run demo

Fahrplan

• Versionsaushandlungsprüfungen über Protokollrevisionen hinweg

• Validierung von Ressourcen- und Prompt-Inhalten

• --report md für PR-Kommentare

• Strukturierte Ausgabevalidierung für Tools, die outputSchema deklarieren

• Öffentlicher Zuverlässigkeitsdatensatz: mcp-flightcheck läuft über das offizielle Registry

Lizenz

MIT