mcpstub

Фиктивный MCP-сервер, созданный по реальному контракту.

mcpstub превращает отчёт mcpdoctor или небольшой JSON-фикстур в детерминированный stdio-сервер. Тестируйте MCP-клиентов, шлюзы и агентские обвязки без живых учётных данных, нестабильных API и вручную написанного JSON-RPC.

$ mcpstub from mcpdoctor.json --out fixtures/docs.json
mcpstub: wrote fixtures/docs.json (14 tools)

$ mcpstub check fixtures/docs.json
✓ valid mcpstub fixture: fixtures/docs.json

$ mcpstub serve fixtures/docs.json
# speaks MCP on stdin/stdout until the client disconnects

Полезный цикл

Один раз изучите реальный сервер, просмотрите контракт, а затем тестируйте против локальной заглушки:

# 1. Inventory the server. mcpdoctor never calls its tools.
npx --yes github:jovial-liu/mcpdoctor#v1 inspect \
  --format json --out mcpdoctor.json -- \
  npx -y @modelcontextprotocol/server-filesystem /tmp

# 2. Generate a safe starting fixture from the advertised contract.
npx --yes github:jovial-liu/mcpstub#v1 from mcpdoctor.json --out fixtures/files.json

# 3. Point an MCP client at the deterministic fixture server.
npx --yes github:jovial-liu/mcpstub#v1 serve fixtures/files.json

Сгенерированный фикстур сохраняет имена инструментов, описания, схемы, аннотации, ресурсы, шаблоны, промпты и идентичность сервера. Он создаёт результаты-заглушки — и никогда не перехватывает реальный вывод рабочих инструментов.

Ручные сценарии

Фикстуры — это обычный проверяемый JSON. Добавляйте специфичные для аргументов случаи прямо в инструмент:

{
  "schema": "mcpstub/v1",
  "server": { "name": "weather-fixture", "version": "1.0.0" },
  "tools": [
    {
      "name": "get_weather",
      "description": "Get a fixture forecast",
      "inputSchema": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      },
      "cases": [
        {
          "when": { "city": "Paris" },
          "result": { "content": [{ "type": "text", "text": "Paris: 21°C, clear" }] }
        },
        {
          "when": { "city": "Atlantis" },
          "error": { "code": -32004, "message": "Fixture city not found" }
        }
      ],
      "result": { "content": [{ "type": "text", "text": "Fixture forecast unavailable" }] }
    }
  ]
}

when выполняет рекурсивное частичное сопоставление объектов аргументов. Объектные случаи могут игнорировать нерелевантные аргументы; массивы сопоставляются по длине и позиции. Выигрывает первый совпавший случай, а result используется как запасной вариант. Если нет ни того, ни другого, mcpstub возвращает детерминированный сгенерированный результат, содержащий имя инструмента и аргументы.

Попробуйте поддерживаемый пример:

npx --yes github:jovial-liu/mcpstub#v1 check examples/weather.json
npx --yes github:jovial-liu/mcpstub#v1 serve examples/weather.json

Что он реализует

• современный 2026-07-28 server/discover, дискриминаторы результатов и метаданные кэша;

• устаревшее согласование initialize, по умолчанию 2025-11-25;

• tools/list и детерминированные результаты tools/call или ошибки JSON-RPC;

• списки ресурсов и шаблонов ресурсов, а также resources/read;

• список промптов и prompts/get;

• ping, ошибки неизвестного метода и ошибки парсинга;

• опциональная JSONL-запись вызовов, сделанных к заглушке.

Обе эпохи протокола доступны из одного процесса с фикстурой. Современный клиент начинает с server/discover; устаревший клиент — с initialize.

Необязательные проверки вызовов

Запишите, что тестируемая система просила заглушку сделать:

mcpstub serve fixture.json --log calls.jsonl

Журнал содержит временные метки, имена инструментов и аргументы. Он включается явно, потому что аргументы могут содержать секреты или личные данные. До тех пор, пока журналы вызовов не будут проверены и санированы, не включайте их в систему контроля версий.

CLI

mcpstub from <mcpdoctor.json> [--out mcpstub.json]
mcpstub check <fixture.json> [--json]
mcpstub serve <fixture.json> [--log calls.jsonl]
mcpstub --version

Формат фикстур версионируется через schema/fixture.schema.json. check также отклоняет повторяющиеся имена и некорректные случаи со стабильными кодами проблем.

Безопасность и ограничения

mcpstub не запускает реальный MCP-сервер, не вызывает реальный инструмент, не исполняет команды оболочки, не загружает учётные данные из окружения и не отправляет сетевых запросов. Он читает только указанный вами фикстур и записывает только явно заданный путь вывода или журнала.

Это протокольный фикстур, а не песочница безопасности или полный эмулятор сервера:

• stdio поддерживается; Streamable HTTP и авторизация — нет;

• многоэтапные запросы, подписки, сэмплирование, расшифровка и расширения не моделируются;

• объявленные JSON-схемы не используются для проверки аргументов вызовов;

• сгенерированные фикстуры содержат контракты и ответы-заглушки, а не их поведенческие записи;

• вредоносный фикстур всё равно может вернуть вредоносный текст тестируемому клиенту, поэтому относитесь к сторонним фикстурам как к кодоподобным тестовым данным.

Для записи живых сессий используйте кассетный рекордер. mcpstub intentionally построен вокруг контракта: небольшие фикстуры, явные случаи, детерминированные результаты.

Разработка

git clone https://github.com/jovial-liu/mcpstub.git
cd mcpstub
npm run check

Node.js 20+ и ноль зависимостей в рантайме. См. CONTRIBUTING.md и SECURITY.md.

Лицензия

MIT