mcp-tester

Инструментированный MCP-сервер для тестирования соответствия клиента уведомлениям */list_changed и другим функциям протокола.

Зачем

В PR mcaps-microsoft/msx-mcp#321 было предложено динамическое появление инструментов через notifications/tools/list_changed. PR был закрыт с утверждением, что «Copilot CLI кэширует tools/list при запуске сессии и игнорирует notifications/tools/list_changed» — однако никаких инструментальных экспериментов для подтверждения или опровержения этого не проводилось.

Этот репозиторий предоставляет аппарат для проверки данного утверждения — и соответствия любого MCP-клиента стандарту list_changed — с помощью реальных доказательств.

Что он делает

1. Пробный MCP-сервер (src/server.ts) — самоинструментирующийся MCP-сервер, который записывает каждое сообщение JSON-RPC в свой канал stdio. Он предоставляет инструменты, ресурсы и промпты в альфа-состоянии, а также инструменты-триггеры, которые переключают их в бета-состояние и отправляют соответствующее уведомление */list_changed.

2. Автоматизированный клиентский драйвер (src/driver.ts) — MCP-клиент на основе SDK, который управляет сервером через полный цикл мутации. Это контроль: он доказывает, что протокол работает, когда обе конечные точки соблюдают спецификацию. Любой клиент, который отклоняется от этого поведения, доказуемо не соответствует стандарту.

3. Анализатор логов (src/analyze.ts) — считывает лог JSONL и создает таблицу доказательств в формате markdown, отвечающую на конкретные вопросы: получил ли клиент уведомление? Выполнил ли он повторный запрос? Может ли он вызвать новый элемент? Может ли он все еще вызвать удаленный элемент?

4. Протокол для человека (PROTOCOL.md) — пошаговые инструкции по запуску того же теста для Copilot CLI или любого другого MCP-клиента.

Быстрый старт

git clone https://github.com/ericchansen/mcp-tester.git
cd mcp-tester
npm install
npm run build

Запуск автоматизированного контроля (SDK-клиент)

npm run driver -- --domain all

Это запускает пробный сервер, выполняет полный протокол мутации для инструментов, ресурсов и промптов, а также сообщает результаты. Вы должны увидеть, что все три домена проходят проверку с полным соответствием.

Анализ лога

npm run analyze -- path/to/log.jsonl --domain tools

Тестирование вашего собственного MCP-клиента

См. PROTOCOL.md для получения пошаговых инструкций по тестированию Copilot CLI или любого другого MCP-клиента с помощью этого пробника.

Структура репозитория

mcp-tester/
|-- README.md          # This file
|-- PROTOCOL.md        # Human-driven test procedure
|-- LICENSE            # MIT
|-- package.json
|-- tsconfig.json
|-- src/
|   |-- server.ts      # Probe MCP server (stdio)
|   |-- logger.ts      # JSONL stdio tap + log writer
|   |-- analyze.ts     # CLI: parses log -> markdown evidence table
|   +-- driver.ts      # CLI: spawns server, drives it via SDK Client
+-- results/
    +-- copilot-cli/
        +-- .gitkeep   # Committed experiment results go here

Как работает пробник

Начальное состояние (Альфа)

Плюс пять постоянных инструментов: mcptester_mutate_tools, mcptester_mutate_resources, mcptester_mutate_prompts, mcptester_status.

После мутации (Бета)

Когда вызывается инструмент mcptester_mutate_*:

1. Альфа-элемент удаляется (через handle.remove() в SDK)

2. Регистрируется бета-элемент

3. SDK автоматически отправляет соответствующее уведомление notifications/*/list_changed

4. debouncedNotificationMethods объединяет удаление и регистрацию в одно уведомление

Логирование

Каждое сообщение JSON-RPC (входящее и исходящее) записывается в файл JSONL. Логгер перехватывает process.stdin и process.stdout через потоки Transform, установленные перед транспортом SDK, поэтому он видит каждый байт, не вмешиваясь в работу протокола.

Ограничения

• Только транспорт stdio — тестирование HTTP/SSE пока не реализовано

• Только три потока list_changed — в будущем планируются тесты для выборки, получения данных, корней, прогресса, завершений

• Тестирование одного сервера — за раз тестируется одно соединение с MCP-сервером

Лицензия

MIT