Поле отсутствует или равно null в MCP: почему это разные запросы
Определите различие между «не менять поле» и «очистить поле». Отсутствующее свойство и JSON null не обязаны означать одно действие, поэтому сервер не должен угадывать намерение.
Разберём рабочий случай
Инструмент обновляет карточку клиента. Пользователь просит поменять должность, а агент передаёт phone: null вместе с новым значением position. Если null означает очистку, телефон исчезнет без отдельной просьбы. Обратная ошибка тоже возможна: сервер игнорирует null, и пользователь не может удалить устаревший номер. Это вопрос контракта обновления, а не косметика JSON.
Что изменить
Запишите три состояния: поле отсутствует — сохраняем прежнее значение; строка — заменяем после проверки; null — очищаем, если это разрешено. В JSON Schema допустимость null и обязательность свойства задаются разными правилами. Для чувствительных данных можно вынести очистку в отдельную операцию или подтверждение. Не передавайте все необязательные поля с пустыми значениями только ради одинакового внешнего вида запросов. Клиент и сервер должны одинаково понимать каждое состояние.
Как проверить результат
| Проверка | Ожидаемое поведение |
|---|---|
| Обновить должность без свойства телефона | Телефон сохранён; отсутствие ключа не превращается в пустое значение во внутренней модели. |
| Передать явный null для очищаемого телефона | Поле очищено только при наличии соответствующего права и допустимого намерения пользователя. |
| Передать пустую строку вместо null | Поведение определено отдельно: ошибка, нормализация или допустимое значение, но не случайное совпадение с отсутствующим полем. |
Для интерфейса редактирования покажите пользователю разницу между отсутствующим изменением и очисткой. Если форма всегда отправляет все поля, семантика сервера должна быть согласована с этим поведением клиента.
Этот контракт подходит не любому API: некоторые системы используют полную замену объекта или отдельный формат patch. При обёртке внешнего сервиса нужно учитывать его семантику, иначе MCP лишь скрывает несовместимость.
Надёжные tools требуют понимания схемы, обновлений и проверок на границах приложения. В платном курсе AI Agent Integrations PRO: MCP можно продолжить изучение соответствующего инженерного направления. Перед покупкой сравните программу и открытые материалы со своей задачей.
Документация для проверки технических деталей: null в JSON Schema, Объекты JSON Schema.
Следующий шаг: MCP-интеграции: контракты инструментов, ошибки и доступ. По смежным вопросам: Документ в MCP: resource или tool для чтения, readOnlyHint в MCP: почему аннотация не даёт защиту.
