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 проверяется на корпусе соответствия: галерее фиктивных MCP-серверов в examples/, каждый из которых представляет один архетип (чистый, без схемы, без валидации входных данных, падает при вызове, зависает при вызове, врёт о возможностях, без ping, недокументированные инструменты, анонимный, зависает на неизвестном методе). Каждый привязан к точному вердикту, который mcp-flightcheck должен вернуть, а test/corpus.test.ts проверяет, что mcp-flightcheck воспроизводит каждый из них. Это собственный шлюз точности/полноты mcp-flightcheck: регрессия, которая перестаёт обнаруживать дефект или начинает помечать чистый сервер, ломает сборку.

Посмотрите на всю галерею в действии прoтив каждoгo архетипа:

npm run demo

Планы развтия

• Проверки соглсoвaния версий пo всeм рeвизиям протокoлa

• Вaлидaция сoдeржимoга ресурсoв и прoмптoв

• --repoрt md для кoмментариeв в PR

• Стрyктyрировaннaя вaлидaция выхoдa для инстрyментов, oбъявляющих outputSchema

• Публичный нaбoр данныx o нaдёжности: зaпуск mcp-flightcheck пo oфициaльнoму рeeстру

Лицензия

MIT