Двенадцать граблей Gmail API, которые я собрал, пока учил Claude отправлять почту
Коротко
- Gmail API возвращает тело письма в исходной кодировке и не декодирует RFC 2047 в Subject, поэтому кириллицу нужно обрабатывать явно.
- Для событий на весь день end.date является эксклюзивной границей, а повтор запроса после 429 не должен повторно мутировать тот же объект.
- Поиск Google Contacts разделён между «Моими контактами» и «Другими контактами», причём у методов разные scopes, readMask и лимиты выдачи.
- searchContacts без явного pageSize возвращает только 10 результатов, не поддерживает пагинацию и имеет жёсткий максимум в 30 совпадений.
- После обновления до mcp 2.0.0 исчез mcp.server.fastmcp, поэтому незакреплённая версия зависимости может внезапно сломать работающий MCP-сервер.
Сервер работает на собственных OAuth-данных и обращается к Google напрямую. Тонкий серверный слой только принимает параметры и формирует ответы, а основная логика вынесена в отдельный пакет и тестируется без сетевых вызовов: 300 тестов выполняются за девять секунд. При работе с почтой пришлось отдельно учитывать исходные кодировки сообщений, RFC 2047 в темах, локализованные префиксы ответов, неоднозначный разбор адресов и особенности Bcc.
В Calendar и Contacts обнаружились другие ограничения: у событий на весь день конечная дата является эксклюзивной, повторный запрос после ошибки не должен повторно изменять переданный объект, а минимальный OAuth-scope может не давать доступа к соседнему ресурсу API. Поиск контактов разделён между обычными и «Другими контактами», причём методы отличаются разрешениями, полями и лимитами выдачи.
Для AI-агента добавился отдельный слой безопасности: при превращении HTML-письма в текст нужно удалять не только теги, но и содержимое script и style, иначе невидимые человеку инструкции могут попасть в контекст модели. Проект делался вместе с Claude Code по TDD и с отдельным агентом-ревьюером после каждой задачи; ревью нашло девять дефектов, но проблему с реальным OAuth-доступом Calendar API обнаружила только проверка на живом аккаунте после 299 зелёных тестов.
FAQ
Зачем автор сделал собственный локальный MCP-сервер вместо Zapier и других готовых облачных коннекторов для Gmail?
Он не хотел, чтобы личная переписка проходила через стороннюю инфраструктуру. Локальный сервер использует собственные OAuth-данные и обращается к сервисам Google напрямую.
Почему простое удаление HTML-тегов из входящего письма не защищает AI-агента от скрытой непрямой инъекции промпта?
После удаления тегов содержимое script и style может остаться в тексте и попасть в контекст модели, хотя пользователь его не видит. Поэтому такие блоки нужно удалять целиком.
Читайте также
ИИ-агент для скоринга торговых рекомендаций- Gemini Spark теперь работает с вашими логинами в Chrome
- Человекоцентричный B2B-экран: снижение нагрузки на техподдержку и ускорение поиска ошибок
- Telegram 2026 в России: взгляд разработчика ботов
- Кейс рекламного агентства: управленческая аналитика в BI Конструкторе Битрикс24
- Декодирование писем из Gmail API по charset MIME-части: Gmail API возвращает тело письма в исходной кодировке отправителя, а не гарантированно в UTF-8. При чтении необходимо определять charset отдельно для каждой MIME-части по Content-Type и предусматривать безопасный fallback для неизвестных или ошибочных названий кодировок.
[Gmail API]
Зарегистрированные пользователи видят только два тезиса.
Зарегистрироваться
#Google#Безопасность#Хабр#AI-агенты#MCP#prompt-injection#oauth#claude-code#coding-agents#automated-testing#claude#gmail
Автор собрал локальный сервер Model Context Protocol (MCP), который даёт Claude восемь инструментов для Gmail, Google Calendar и Contacts, и описал 12 ошибок, найденных при его разработке. Главный практический вывод: интеграция может корректно проходить сотни тестов, но ломаться на реальных данных, правах доступа и поведении API.