Как описать сбой 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 по ссылке ниже можно выбрать направление разбора. Учебный пример не обещает срок исправления и не назначает новый канал поддержки.
