MCP Python SDK 2.0.1 пояснила зламані імпорти FastMCP

Model Context Protocol Python SDK 2.0.1 випустили як терміновий backport для розробників, які зіткнулися з помилками старих імпортів FastMCP після переходу на гілку 2.x. Замість мовчазного падіння або неочевидного traceback пакет тепер спрямовує користувача до migration guide. Рекомендація команди проста: тимчасово зафіксувати mcp<2 або завершити міграцію на API другої версії.

Чому маленький patch-реліз важливий

Зміна в 2.0.1 невелика: імпорти з mcp.server.fastmcp, які більше не відповідають новій структурі, повинні показати зрозуміле попередження з посиланням на інструкцію. Але команда зробила окремий backport, тому що помилка масово проявлялася не лише в самому SDK: користувачі відкривали issues у downstream-проєктах, вважаючи, що зламався агент, сервер або стороння інтеграція.

Це типовий наслідок великого оновлення екосистемного пакета. Python імпортує символи під час старту процесу, тому зміна публічного шляху може зупинити весь MCP-сервер ще до ініціалізації логування, healthcheck або реєстрації інструментів. Якщо залежність указана без верхньої межі, нова major-версія потрапляє у чисте середовище навіть тоді, коли локальний lock-файл давно не оновлювався.

Два безпечні сценарії

Перший сценарій — короткострокова стабілізація. Якщо команді потрібен швидкий відкат працездатності, варто зафіксувати залежність як mcp<2, перебудувати lock-файл і повторно розгорнути застосунок. Така дія не переносить нові можливості 2.x, зате зменшує площу змін під час інциденту.

Другий сценарій — контрольована міграція. Створіть окрему гілку, оновіть імпорти за migration guide, прогоніть контрактні тести для tools, resources і prompts, перевірте транспорт, авторизацію та завершення з’єднань. Після цього залежність можна зафіксувати на сумісному діапазоні 2.x. Саме такий шлях прибирає технічний борг, але потребує більше часу.

Не змішуйте підходи: просте встановлення 2.0.1 не повертає старий FastMCP API. Воно лише робить причину помилки зрозумілішою. Для роботи потрібне або pinning на 1.x, або фактичне оновлення коду.

Що перевірити в CI

• Чисте встановлення. Тестуйте не лише кешоване середовище розробника, а новий контейнер без старого lock і wheels.
• Імпорт entry point. Окремий smoke test має імпортувати та запускати MCP-сервер.
• Контракти інструментів. Перевірте JSON Schema аргументів, типи відповідей та обробку помилок.
• Транспорт. Якщо використовуються stdio, SSE або streamable HTTP, кожен режим потребує власного тесту життєвого циклу.
• Верхня межа залежності. Для застосунку краще свідомо дозволяти major-оновлення, а не отримувати їх випадково.

Висновок для розробників агентів

MCP швидко розвивається, і його SDK уже є інфраструктурною залежністю для багатьох агентів та IDE. Тому міграційні повідомлення — не дрібниця UX, а частина надійності екосистеми. Вони скорочують час діагностики, але не замінюють semver-дисципліну, lock-файли й інтеграційні тести.

Перед оновленням production варто інвентаризувати не лише прямий імпорт SDK, а й бібліотеки, які тягнуть MCP транзитивно. Саме там часто виникає конфлікт: головний застосунок готовий до 2.x, а плагін усе ще імпортує старий шлях.

Джерело та права

Матеріал є самостійним українським переказом release notes MCP Python SDK 2.0.1 від 26 серпня 2026 року та редакційним поясненням міграційних ризиків. Репозиторій поширюється за MIT License. Перекладено, адаптовано й доповнено редакцією «Бібліотеки програміста».