Чтобы использовать это по-настоящему, оберните ваш сервер в конфигурацию MCP вашего клиента.```json
{
  "mcpServers": {
    "my-server": {
      "command": "mcpsnoop",
      "args": ["--", "node", "build/index.js"]
    }
  }
}

`wrap` находит `claude_desktop_config.json`, копирует его в
`claude_desktop_config.json.mcpsnoop.bak` при первом запуске и перезаписывает только запись
этого одного сервера, так что ваше форматирование и все остальные серверы остаются нетронутыми.
Внутри перезаписанной записи ключи возвращаются в алфавитном порядке. `unwrap`
восстанавливает файл и удаляет резервную копию, как только ни один сервер больше не обёрнут.
После любого из этих действий перезапустите Claude Desktop, поскольку MCP-серверы запускаются один раз при старте.

Затем используйте ваш клиент как обычно и откройте интерфейс.```bash
mcpsnoop

HTTP-статус каждого ответа отображается в потоке, так что ответ, не несущий
собственного JSON-RPC-сообщения, всё равно остаётся видимым кадром, а не
пустотой: вызов 401, 403 при отклонённом Origin, 202, подтверждающий приём
уведомления, и 502, когда цель вообще недоступна. Заголовок `WWW-Authenticate`
в ответе 401 сохраняется дословно и показывается в инспекторе, поскольку он
называет схему аутентификации и метаданные ресурса для следующего шага.
Фильтруйте по статусу с помощью `status:401` в TUI или по любой ошибке
с помощью `status:err`. Статус 4xx или 5xx считается ошибкой, поэтому запуск
`mcpsnoop check` по умолчанию завершается неудачей.

Нет своего сервера? [Попробуйте вживую](https://github.com/kerlenton/mcpsnoop/blob/HEAD/docs/TRY_IT.md) на опубликованном
тестовом сервере под управлением вашего собственного клиента. Чтобы изучить
сеанс после его завершения, см. [разбор прошлых сеансов по журналам](https://github.com/kerlenton/mcpsnoop/blob/HEAD/docs/POST_MORTEM.md).

### Файл конфигурации

Если вы используете одни и те же флаги shim в рамках проекта, поместите их
в файл `.mcpsnoop.toml` в текущем рабочем каталоге.```toml
label = "filesystem"
trace-file = "trace.jsonl"
redact-secrets = true
redact-key = "token,authorization"
redact-value = "sk-[A-Za-z0-9]+"
redact-path = "$.params.arguments.password"
no-trace = false

### Homebrew```bash
brew install mcpsnoop

`--older-than` обязателен (по умолчанию ничего не удаляется) и
принимает количество дней, например `30d`, или Go-длительность, например `72h`. Базовые показатели инструментов
не затрагиваются, поскольку базовый показатель привязан к метке сервера, а не к сеансу.

Поскольку он находится в самом конвейере, а не в стороне, как Inspector, он
видит именно то, что ваши реальные клиент и сервер говорят друг другу, независимо от того, на чём
написан сервер.

## Сочетания клавиш

| Клавиша | Действие | | Клавиша | Действие |
|---|---|---|---|---|
| `enter` | просмотр / переход внутрь | | `/` | фильтр |
| `esc` | назад | | `:` | команда |
| `j` / `k` | перемещение | | `r` | повторить вызов |
| `g` / `G` | вверх / вниз | | `c` | возможности |
| `ctrl-f` / `ctrl-b` | страница | | `s` | сводка по инструментам |
| `p` | пауза | | `y` | копировать |
| `shift`+`<key>` | сортировать по столбцу | | `e` | экспорт |
| `ctrl-d` | удалить сеанс | | `f` | следовать |
| `?` | помощь | | | |

Нажмите `?` в приложении для полного списка.

## Фильтрация потока

Нажмите `/` в сеансе и комбинируйте токены, разделённые пробелами, через И. Простой текст
соответствует методу, инструменту, идентификатору и полезной нагрузке.

| Токен | Фильтрует по | Пример |
|---|---|---|
| `tool:` | имя инструмента | `tool:search` |
| `method:` | метод JSON-RPC | `method:tools/call` |
| `id:` | идентификатор запроса и любые повторные попытки, продолжающие его | `id:7` |
| `task:` | идентификатор задачи | `task:01J...` |
| `dir:` | направление (`c2s`, `s2c`) | `dir:s2c` |
| `kind:` | тип кадра (`req`, `resp`, `notify`, `stderr`, `invalid`) | `kind:invalid` |
| `status:` | результат вызова (`ok`, `error`, `cancel`, `late`, `cancelled`, `pending`, `bad`, `warn`, `mismatch` или HTTP-статус, например `401`) | `status:error` |

Объединяйте токены, чтобы получить конкретный результат.```text
tool:search status:pending        # in-flight calls to one search tool
status:cancel                     # calls the client gave up on (status:cancelled is a cancelled task)
status:late                       # results that arrived after the cancellation
method:tools/call status:error    # tool calls that failed
dir:s2c kind:req                  # server-initiated requests (servers before 2026-07-28)

| Формат | Что вы получаете |
|---|---|
| `json` | скоррелированные вызовы, количество по каждому инструменту и задержки p50/p95/p99, самые медленные вызовы, возможности и сырые кадры |
| `html` | автономный файл для браузера с поиском и сворачиваемым JSON |
| `text` | читаемый текстовый дамп |
| `har` | одна запись на каждый скоррелированный вызов; открывается в инструментах разработчика браузера и в любом другом ПО, поддерживающем HAR |
| `otlp` | OTLP JSON с одним span на каждый скоррелированный вызов; W3C trace context объединяет трассы вызывающей стороны, в противном случае используется одна трасса на сессию |

MCP — это не HTTP, поэтому URL, код состояния и тайминги записи HAR представляют собой намеренное сопоставление каждого вызова, а не точную запись сетевого обмена.

Для OTLP поле `_meta.traceparent` запроса задаёт идентификаторы трассы и родительского span для этого вызова, а `_meta.tracestate` передаётся вместе со span. Если traceparent отсутствует или недействителен, mcpsnoop сохраняет трассу, производную от сессии, и не несёт никакого состояния. mcpsnoop наблюдает, а не участвует, поэтому он не добавляет собственной записи поставщика и передаёт состояние вызывающего без изменений.```bash
mcpsnoop export -T html -o out.html                    # an HTML file to open in a browser
mcpsnoop export -T text server.py-48213-7f3a1c9e2b04   # a specific session, as text
mcpsnoop export -T json | jq                           # the newest session, piped to jq
mcpsnoop export -T har -o session.har                  # a HAR file to open in browser devtools
mcpsnoop export -T otlp -o trace.json                  # import into an OTLP-compatible tracing backend

Эти флаги перезаписывают экспортированный файл или представление TUI в памяти, но никогда — исходный JSONL. `export` отказывается записывать в тот же файл, что и входной, и пишет через временный файл, который затем переименовывается на место, так что при сбое предыдущий файл остаётся целым.

`inputSchema` и `outputSchema` инструмента, как они объявлены в результате `tools/list`, не затрагиваются `--redact-key` и `--redact-secrets`. Имя внутри схемы — это объявление типа, а не значение; само имя в любом случае остаётся в журнале, а очистка подсхемы под свойством с именем `token` унесла бы с собой и собственные проверки инструмента. Исключение действует только для этой позиции, поэтому аргумент, который по случайности называется `inputSchema`, очищается как любой другой, и оно останавливается на `default`, `const`, `examples` и `enum`, где хранятся данные, а не структура. Используйте `--redact-path`, чтобы указать что-то внутри схемы, или `--redact-value`, который сопоставляет текст где угодно, кроме двух ключевых слов, которые разбирает mcpsnoop, — `type` и `x-mcp-header`.

Область действия каждого флага различается, поэтому проверяйте результат, а не полагайтесь на предположения. Все четыре очищают полезные нагрузки JSON-RPC, а `--redact-key`, `--redact-path` и `--redact-secrets` достигают только их. Только `--redact-value` также очищает stderr, прочий не-JSON текст и внутренности строк. Заголовок `Mcp-Param-*` очищается вместе с тем значением тела, которое он отражает; остальные метаданные конверта, метки сервера, `Mcp-Name`, `Mcp-Method` и HTTP-статус остаются такими, как были записаны. Редактирование выполняется по принципу «лучшее из возможного», поэтому используйте отдельный путь вывода и прочтите результат перед тем, как делиться им.

### Потоковая передача завершённых вызовов в коллектор OTLP

Отправляйте спаны, пока прокси запущен, указав ему конечную точку трасс OTLP/HTTP JSON. Повторяйте `--otlp-header` для заголовков аутентификации коллектора или арендатора.```bash
mcpsnoop \
  --otlp-endpoint http://localhost:4318/v1/traces \
  --otlp-header "Authorization=Bearer $OTLP_TOKEN" \
  -- node build/index.js

mcpsnoop http \
  --target http://localhost:3000/mcp \
  --otlp-endpoint http://localhost:4318/v1/traces

Отчет показывает инструменты, которые были добавлены или удалены, изменения описания и `inputSchema`, сопоставленные вызовы инструментов, чей статус изменился, и заметные сдвиги длительности. Вызовы сопоставляются по имени инструмента и аргументам, поэтому переупорядоченные вызовы по-прежнему корректно сравниваются. По умолчанию изменения длительности должны отличаться как минимум на 100 мс и в 2 раза; используйте `--duration-threshold` и `--duration-ratio`, чтобы настроить эти пороговые значения.

Передайте `--exit-code`, чтобы применять гейт CI по регрессиям: он завершается с ненулевым кодом, когда последующая сессия удаляет инструмент, изменяет описание инструмента, заголовок, входную схему, выходную схему или аннотации, имеет вызов, чей статус ухудшился, или замедляется. Улучшения (добавленные инструменты, исправленные вызовы, ускорения) по-прежнему завершаются с нулевым кодом, как и изменение иконки, которое меняет внешний вид инструмента, не меняя его функциональность.

## Проверка сессий в CI

Пропускайте записанный запуск агента через гейт по ошибкам, повреждению потока, предупреждениям протокола, несоответствиям заголовков маршрутизации, вызовам, которые так и не получили ответа, потерянным кадрам, оставляющим захват неполным, дрейфу определений инструментов или использованию устаревших функций протокола.```bash
mcpsnoop check [--format text|junit|sarif] [--fail-on error,invalid,warn,mismatch,pending,late-result,drift,deprecated,incomplete,schema] [session-id|log.jsonl|-]

Счётчик потерянных кадров также передаётся вместе с артефактами, поэтому захват,
который занижает собственные показатели, сообщает об этом везде, где его открывают:
`missing_frames` в JSON-экспорте, `log.comment` в HAR и атрибут ресурса
`mcpsnoop.session.missing_frames` в OTLP.```bash
mcpsnoop check build-agent
mcpsnoop check --fail-on error,invalid artifacts/session.jsonl
mcpsnoop check --fail-on mismatch gateway-run.jsonl

### Сообщайте туда, куда уже смотрит CI

`--format junit` записывает один `<testcase>` на каждый сигнал и сессию, а его сбои
следуют тому же выбору `--fail-on`, что и текстовый вывод.```yaml
- name: Check captured MCP session
  run: |
    mkdir -p test-results
    mcpsnoop check --format junit artifacts/session.jsonl > test-results/mcpsnoop.xml
- name: Upload mcpsnoop JUnit report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: mcpsnoop-junit
    path: test-results/mcpsnoop.xml

### Обнаружение заголовка маршрутизации, не согласующегося с телом

В транспорте streamable-HTTP шлюз маршрутизирует по `Mcp-Method` и `Mcp-Name`, пока сервер читает тело, поэтому заголовок, не согласующийся с телом, означает, что они видят два разных запроса. Сигнал `mismatch` охватывает и этот случай, и заголовок, следующий с пакетом, который он не может адресовать, и полностью отсутствующий обязательный заголовок.

Начиная с 2026-07-28 отсутствующий заголовок маршрутизации является ошибкой валидации, и соответствующий спецификации сервер отклоняет запрос с `400` и `-32020`. mcpsnoop сообщает о нём только тогда, когда известно, что сеанс работает на этой ревизии или более поздней, поскольку более ранние ревизии вообще не определяют эти заголовки, и их отсутствие там корректно. Собственное отклонение сервера с `-32020` считается тем же сигналом.

Имя или URI ресурса, которые не помещаются в значение HTTP-поля, передаются в Base64 в виде сентинела `=?base64?…?=`, который декодируется перед сравнением, поэтому клиент, кодирующий корректно, никогда не помечается.

Для HTTP-запросов `tools/call` mcpsnoop также показывает каждый заголовок `Mcp-Param-{Name}` и, когда известно соответствующее объявленное определение инструмента, сравнивает его с аннотированным путём аргумента. Вложенные свойства, Base64-сентинел, логические значения и численно эквивалентные безопасные целые числа обрабатываются без ложных срабатываний строкового сравнения. Неизвестные заголовки параметров и сеансы без соответствующего определения инструмента остаются в режиме наблюдения. Маскирование на основе ключей и значений применяется к захваченным значениям заголовков параметров до того, как они попадут в приёмник, и значение, которое mcpsnoop замаскировал сам, никогда не сообщается как расхождение.

### Обнаружение расхождения определений инструментов

Первое полное `tools/list`, наблюдавшееся для метки сервера, становится его доверенным эталоном. Более поздние сеансы сравнивают этот эталон поле за полем: описание, название, схемы ввода и вывода, аннотации и иконки, а также инструменты, которые были добавлены или удалены. Аннотации имеют наибольшее значение, поскольку инструмент, одобренный с `readOnlyHint`, который позже объявляет себя разрушительным, — это тот самый подвох, ради которого существует эта проверка, а спецификация предписывает клиентам относиться к аннотациям как к ненадёжным. Название и иконки отслеживаются, потому что именно их видит пользователь, а спецификация ставит `title` инструмента выше `annotations.title` и его имени. Таблица сеансов и сводка по инструментам помечают расхождение, не блокируя и не изменяя MCP-трафик.

Аннотации сравниваются с учётом значений по умолчанию их спецификации, поэтому сервер, который начинает явно прописывать подсказку, на которую уже полагался, не помечается. Эталон, записанный до того, как mcpsnoop начал отслеживать поле, продолжает работать для полей, которые он записывает, и сообщает, за какие не может поручиться; перезапишите его с помощью `mcpsnoop baseline --accept`, когда доверитесь текущим определениям.

Изменение того, что записывает маскирование, меняет то, что сравнивается при проверке расхождения. Эталон, снятый без `--redact-value`, а затем проверенный по захвату, снятому с этим флагом, помечает замаскированные поля как изменённые, что корректно, поскольку записанное определение действительно изменилось. Перезапишите с флагом `--accept` после изменения настроек маскирования.

Используйте стабильный уникальный флаг `--label` для каждого сервера, у которого имя команды или целевой хост в противном случае совпадали бы. Эталоны хранятся в обычном каталоге состояния mcpsnoop, поэтому `MCPSNOOP_HOME` и `XDG_STATE_HOME` применяются.```bash
mcpsnoop check --fail-on drift session.jsonl
mcpsnoop baseline session.jsonl
mcpsnoop baseline --accept session.jsonl  # trust a legitimate definition change
mcpsnoop baseline --reset session.jsonl   # trust the next complete tools/list

`drift` является опциональным для `check`; стандартный фильтр `error,invalid,warn` не изменился.

### Помечать устаревшие возможности протокола

Редакция от 2026-07-28 объявляет устаревшими Roots, Sampling и Logging. Они продолжат
работать как минимум год, поэтому mcpsnoop помечает их, а не считает ошибками.
Поток, инспектор возможностей и экспорт помечают их, и каждая пометка
называет замену.

Две из трёх теперь доступны только через запрос с несколькими циклами обмена,
когда имя метода находится внутри карты `inputRequests` сервера, а не в самом
кадре. Они тоже помечаются, так что сервер, перешедший на новый паттерн,
не перестанет молча сообщать о них.```bash
mcpsnoop check --fail-on deprecated session.jsonl

Столбец несёт предупреждающий цвет и никогда не принимает красный цвет столбца ERR, а
mcpsnoop по-прежнему ничего не меняет в пересылаемом им трафике.

Ничто не разрешается и не извлекается. Внешний `$ref` распознаётся только по своей форме
сам по себе, а схема, на которую он указывает, никогда не читается.

### Смотрите, во что сервер обходится вам в контексте

Определения инструментов попадают в контекст модели при каждом разговоре, а
результаты инструментов — при каждом вызове. Сводка по инструментам (`s`) измеряет и то и другое по сессии,
которую вы фактически захватили.

Строка `definitions` — это фиксированная стоимость: сколько весит `tools/list` этого сервера
до того, как сделан хотя бы один вызов. Столбец `DEF` разбивает это по
каждому инструменту, а `RESULT` — сколько на данный момент стоили ответы каждого инструмента. Таблица остаётся
отсортированной по ошибкам и задержке, так что просматривайте `DEF`, чтобы найти дорогие определения;
экспорт перечисляет их сначала самыми тяжёлыми. Строка под таблицей называет единственный
самый тяжёлый результат, который скрывает итог.

Значения определений — это JSON с удалёнными незначимыми пробелами, поэтому
сервер, который делает pretty-print своего `tools/list`, не считается более дорогим, чем
тот, который этого не делает, и один и тот же сервер при разных захватах измеряется одинаково.
`RESULT` — это байты в том виде, в котором они поступили: результат — это разовая полезная нагрузка, а не
контракт, который стоит нормализовать.```bash
mcpsnoop export -T json | jq '.summary.definitions'

Сокет находится в каталоге состояния удалённой системы, определяемом как `MCPSNOOP_HOME`,
иначе `XDG_STATE_HOME/mcpsnoop`, иначе `~/.local/state/mcpsnoop`. По умолчанию mcpsnoop
предполагает домашний каталог Linux `/home/<user>` из вашего `user@host` и выводит напоминание
в stderr всякий раз, когда прибегает к этому предположению. Если на удалённой системе расположение
определяется иначе, укажите этот единственный нестандартный элемент.```bash
# a non-Linux or custom home, macOS is /Users/<user> and root is /root
mcpsnoop remote --remote-home /Users/remote-user remote-user@remote-host

# an explicit MCPSNOOP_HOME on the remote
mcpsnoop remote --remote-mcpsnoop-home /srv/mcpsnoop remote-user@remote-host

# an explicit XDG_STATE_HOME on the remote
mcpsnoop remote --remote-xdg-state-home /var/lib/state remote-user@remote-host

Чтобы вместо этого сохранить локальную копию, скопируйте логи с помощью scp в каталог сеансов и запустите
TUI как обычно.```bash
# copy the remote logs into your local sessions directory
mkdir -p ~/.local/state/mcpsnoop/sessions
scp remote-user@remote-host:'~/.local/state/mcpsnoop/sessions/*.jsonl' \
  ~/.local/state/mcpsnoop/sessions/

# open the TUI, it backfills the copied sessions
mcpsnoop

Для удалённых рабочих процессов используйте SSH-туннелирование или SSH-передачу
файлов, чтобы аутентификация транспорта, шифрование, проверка хоста, ротация
ключей и политика аудита оставались в вашей существующей SSH-инфраструктуре.

## Участие

Приветствуются Issues и pull requests. Подробности см. в
[CONTRIBUTING.md](https://github.com/kerlenton/mcpsnoop/blob/HEAD/CONTRIBUTING.md).

## Лицензия

[MIT](https://github.com/kerlenton/mcpsnoop/blob/HEAD/LICENSE)