Перейти к основному содержанию

Как описать сбой MCP без ключей и чужих данных

Соберите минимальный пример: этап ошибки, версии, существенные свойства ввода и ожидаемый результат. Учебный код помогает отделить отчёт от сырого журнала.

· Atomno MCP ·
  • MCP
  • диагностика
  • разработка
На постановочном экране слева ошибка MCP и исходный журнал с закрытыми полями ключа и личных данных, справа краткий отчёт без этих полей.
Учебная иллюстрация: из технического сбоя — в краткий отчёт без секретных значений.

Укажите этап, на котором возникла проблема

Сообщение «MCP не работает» объединяет разные ситуации. Процесс может не запуститься, клиент — не увидеть инструмент, а уже вызванный инструмент — вернуть ошибку. Начните с одного наблюдаемого этапа и одной операции, а не с архива всей конфигурации.

Укажите клиент и его версию, ОС, имя и версию пакета сервера, если они известны. Затем добавьте действие, наблюдаемую категорию ошибки и время. Не называйте источник неисправным только потому, что его ещё не удалось проверить.

Сохраните существенные свойства ввода

Минимальный пример сохраняет то, от чего зависит результат: название параметра, тип, обязательность, длину, пробелы или иной значимый признак. Замена строки на число либо удаление крайних пробелов могут незаметно устранить исходную проблему.

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

Соберите отдельный пример вместо публикации сырого журнала

OWASP рекомендует исключать или защищать в журналах токены, пароли и другие чувствительные значения. Перед публикацией отчёта проверьте также URL с параметрами, переменные окружения, пути, имена и текст ошибок. Скрытый ключ в одном поле не делает весь остальной файл безопасным.

Следующий Python 3.11 пример создаёт сообщение только из выдуманных данных в памяти. Он демонстрирует выбор нужных полей, а не автоматическую очистку настоящих логов. Сохраните его как demo_report.py и запустите python demo_report.py.

import json

# Every value here is synthetic. Do not read real logs with this example.
raw = {
    "client": {"name": "demo-client", "version": "0.0-demo"},
    "tool": "demo_normalize",
    "arguments": {"text": "  Demo  "},
    "observed": {"isError": True, "summary": "DEMO: input rejected"},
    "headers": {"Authorization": "Bearer DEMO-SYNTHETIC-TOKEN"},
    "local_path": "C:/example/private-project",
}
report = {
    "case_id": "DEMO-REPRO-01",
    "client": dict(raw["client"]),
    "tool": raw["tool"],
    "arguments": dict(raw["arguments"]),
    "observed": dict(raw["observed"]),
    "expected": "Expected result must come from the tool contract",
}
encoded = json.dumps(report, ensure_ascii=False, indent=2)
assert report["arguments"]["text"] == "  Demo  "
assert "Authorization" not in encoded
assert "DEMO-SYNTHETIC-TOKEN" not in encoded
assert "private-project" not in encoded
print(encoded)

Прочитайте результат перед отправкой

В полученном JSON сохранены тип и пробелы аргумента, имя учебного инструмента и наблюдаемая отметка ошибки. Заголовок с демонстрационным токеном и частный путь не перенесены. Проверки относятся только к этим заранее известным строкам.

Значения внутри разрешённых полей тоже могут быть чувствительными. В настоящем отчёте прочитайте текст summary и все arguments вручную; код выше не ищет персональные данные и произвольные секреты. В примере не выполнялся MCP-вызов, поэтому его JSON не является доказательством сбоя конкретного сервера.

Добавьте короткие шаги и различите ожидание с наблюдением

К сообщению приложите последовательность: запустить выбранную конфигурацию; открыть нужный инструмент; передать конкретный безопасный ввод; увидеть точный результат. Отдельно напишите, что ожидали по контракту и что наблюдали фактически.

Если клиент показывает ошибку протокола и ошибку выполнения инструмента раздельно, сохраните это различие. Не заменяйте сообщение ошибки фразой «пустой результат», когда отсутствие данных не установлено. Номер версии, метод и обезличенный фрагмент обычно полезнее полного несекретного, но многотысячного журнала.

Не повторяйте изменяющее действие только ради отчёта

Для сообщения о неудачной записи, отправке сообщения или другой операции с последствиями сохраните имеющееся наблюдение. Повтор может создать новое действие; тестируйте дальнейшие шаги только в подходящей согласованной среде.

Готовый результат — небольшой отчёт, у которого понятны условия, ожидаемое и наблюдаемое поведение, а также границы проверки. В документации troubleshooting по ссылке ниже можно выбрать направление разбора. Учебный пример не обещает срок исправления и не назначает новый канал поддержки.

Источники и следующий шаг

Просмотр кода

Копируется исходный текст. Переносы меняют только отображение.

Текст

Поиск по сайту

Введите хотя бы два символа.

Tab — переход по ссылкам · Esc — закрыть