Ваш кастомный код сразу готов для агентов: как мы создали Medusa MCP

Вчера мы анонсировали Medusa MCP — удаленный сервер MCP, который передает ваши данные вашим агентам. MCP повышает эффективность ваших операций и разработки; он интегрируется в ваши повседневные рабочие процессы с использованием агентов для извлечения данных, создания отчетов о продажах, расследования сбоев развертывания и многого другого.

Medusa MCP работает не только с базовыми моделями данных и рабочими процессами Medusa. Он также из коробки поддерживает вашу бизнес-логику и функциональность. От подписок до аналитики и интегрированных CMS-платформ — все, что вы предоставляете через API-маршрут, доступно с сервера MCP.

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

Ограничения традиционного подхода к серверам MCP

Большинство коммерческих платформ, предлагающих серверы MCP, предоставляют определенные инструменты для каждой коммерческой операции. Например, инструмент Copy to clipboardread_product для получения информации о продукте и отдельный инструмент Copy to clipboardcreate_cart для создания корзины.

Хотя этот подход справляется с задачей, у него есть ряд ограничений:

• Ограничения на инструменты: Клиенты MCP имеют лимит на количество инструментов, принимаемых от сервера MCP. Например, VS Code принимает 128 инструментов, в то время как Cursor принимает 40. Таким образом, этим серверам MCP приходится идти на компромисс с доступностью одних коммерческих операций в пользу других, даже если они актуальны для вашего сценария использования.
• Кастомные инструменты: У вас нет возможности добавлять инструменты для вашей собственной бизнес-логики и функций, или, если она есть, вам приходится брать на себя бремя реализации и поддержки этих инструментов. Сервер MCP становится универсальным инструментом, а не специализированным, созданным под ваш магазин.
• Контроль версий: Для систем с открытым исходным кодом или платформ, где вы сами отвечаете за версию своего приложения, инструменты сервера MCP могут не работать со старыми версиями из-за их жесткой реализации.

Когда мы приступали к созданию Medusa MCP, нашей целью было не просто предоставить эти коммерческие операции через сервер MCP, но и решить эти проблемы для наших пользователей. Наши пользователи получают сервер MCP, который работает с данными их магазина и поддерживает любые их сценарии использования.

Два инструмента для каждого API-маршрута

Вместо специализированных инструментов для каждой базовой коммерческой операции, Medusa MCP предлагает следующие универсальные инструменты для доступа к данным вашего магазина:

• Copy to clipboardread_admin_api: Выполнение операции чтения для любого API-маршрута, начинающегося с префикса Copy to clipboard/admin. Инструмент обрабатывает базовую аутентификацию, необходимую для доступа к маршруту в качестве администратора. Таким образом, вам не нужно передавать агенту какие-либо учетные данные или секреты, а аутентификация остается безопасной.
• Инструмент обрабатывает базовую аутентификацию, необходимую для доступа к маршруту в качестве администратора. Таким образом, вам не нужно передавать агенту какие-либо учетные данные или секреты, а аутентификация остается безопасной.
• Copy to clipboardread_store_api: Выполнение операции чтения для любого API-маршрута, начинающегося с префикса Copy to clipboard/store. Он обрабатывает передачу необходимых заголовоков, таких как публикуемый ключ API вашего магазина.

Таким образом, когда вы просите агента прочитать данные о заказах (основной функционал Medusa) или проверить активные подписки (функционал вашего магазина), он использует соответствующий инструмент выше для отправки запроса по адресу Copy to clipboard/admin/orders или Copy to clipboard/admin/subscriptions и предоставления вам необходимых данных.

Операции записи также скоро появятся на сервере MCP.

Но как агент узнает, какие API-маршруты доступны, особенно кастомные, реализованные в вашем магазине, или маршруты, доступные для вашей версии Medusa? Это второе и третье ограничения, которые решает Medusa MCP.

Документы спецификации OpenAPI с возможностью поиска

Medusa Cloud хранит API-маршруты среды, включая базовые и кастомные маршруты, в виде поискового индекса Medusa. Medusa преобразует спецификации OpenAPI (OAS) среды в записи в поисковом индексе.

Что такое OpenAPI Spec? Спецификация OpenAPI — это стандартный документ для описания HTTP- и REST API. Обычно он используется в целях документации, чтобы сообщить, что делает набор API и как их можно использовать.

Каждая запись поискового индекса содержит такую информацию, как метод API-маршрута, описание его назначения, а также необходимые параметры пути, запроса и параметры запроса.

Затем Medusa MCP предоставляет следующие инструменты:

• Copy to clipboardfind_commerce_api: Поиск по записям OAS в среде пользователя для поиска 10 наиболее релевантных API-маршрутов по запросу. Например, агент может искать по ключевым словам, таким как Copy to clipboardlist orders или Copy to clipboardget subscription, и инструмент возвращает API-маршруты, которые могут подойти.
• Copy to clipboarddescribe_commerce_api: Получение всех сведений о конкретном API-маршруте, включая ожидаемые им параметры.

Таким образом, когда агент хочет выполнить коммерческую операцию от вашего имени, он использует инструменты в следующем порядке:

• Copy to clipboardfind_commerce_api для поиска наиболее подходящего API-маршрута под конкретный сценарий использования.
• Copy to clipboarddescribe_commerce_api для просмотра полных деталей выбранного API-маршрута.
• Copy to clipboardread_admin_api или Copy to clipboardread_store_api для отправки запроса на API-маршрут с необходимыми параметрами.

Это работает не только с базовыми API-маршрутами Medusa, для которых у нас уже есть OAS, но и с API-маршрутами, которые вы определяете в исходном коде своего проекта. Итак, как мы обнаруживаем ваши API-маршруты и сохраняем их как часть того же поискового индекса?

Обнаружение кастомных API-маршрутов

В процессе сборки вашего проекта для нового развертывания в Medusa Cloud мы обнаруживаем API-маршруты, доступные для вашего магазина.

Для базовых API-маршрутов мы определяем версию вашего приложения Medusa, а затем получаем OAS, которую мы размещаем для этой версии в рамках нашей справочной документации. Конечная точка документации https://docs.medusajs.com/api/versions возвращает все версии Medusa, для которых мы храним документ OAS, вместе с URL-адресом для его получения.

Для ваших кастомных API-маршрутов мы используем TypeScript Compiler API для их обнаружения и преобразования в OAS. Мы выполняем следующие действия во время сборки вашего приложения:

• Находим все файлы API-маршрутов в каталогах Copy to clipboardsrc/api/admin и Copy to clipboardsrc/api/store вашего приложения Medusa.
• Для каждого файла мы делаем следующее: обходим его абстрактное синтаксическое дерево (AST) для поиска функций-обработчиков маршрутов. Это функции, которые определяют API-маршруты, такие как функции Copy to clipboardGET и Copy to clipboardPOST. Извлекаем типы запросов и ответов, переданные в качестве аргументов типов в Copy to clipboardMedusaRequest и Copy to clipboardMedusaResponse, если они доступны. Генерируем операцию OAS для API-маршрута, включая ожидаемые параметры запроса и ключевые слова, релевантные для вашего API-маршрута.
• Обходим его абстрактное синтаксическое дерево (AST) для поиска функций-обработчиков маршрутов. Это функции, которые определяют API-маршруты, такие как функции Copy to clipboardGET и Copy to clipboardPOST.
• Извлекаем типы запросов и ответов, переданные в качестве аргументов типов в Copy to clipboardMedusaRequest и Copy to clipboardMedusaResponse, если они доступны.
• Сгенерируйте операцию OAS для маршрута API, включая ожидаемые параметры запроса и ключевые слова, имеющие отношение к вашему маршруту API.
• Объедините базовый OAS и сгенерированные операции пользовательских маршрутов API в единый документ OAS.

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

Medusa MCP: Никаких ограничений для ваших торговых операций

Благодаря этой реализации Medusa MCP устраняет три ограничения, которые накладывают традиционные подходы к серверам MCP:

• Не нужно учитывать ограничения на количество инструментов. Операции чтения объединены в два инструмента, то же самое относится и к операциям записи. Нам не нужно идти на компромисс с доступностью торгового функционала через сервер MCP.
• Пользовательские маршруты API и рабочие процессы обрабатываются как часть инструментов чтения и записи, аналогично базовым данным. Вам также не нужно поддерживать реализацию: доступ с сервера MCP к этим маршрутам доступен из коробки при развертывании в Medusa Cloud.
• Medusa предоставляет вашему агенту соответствующий OAS и доступные маршруты для версии вашего приложения Medusa. Вы можете использовать Medusa MCP с любой версией Medusa.

Начало работы с Medusa Cloud

Чтобы начать использовать Medusa MCP, начните работу с Medusa Cloud и разверните свой проект. После этого вы сможете управлять им с помощью вашего ИИ-агента.

Обратитесь к документации для получения более подробной информации о Medusa MCP.