Как мы сделали SDK, CLI и MCP с ИИ за неделю

За последнюю неделю мы в Pingera активно работали над расширением возможностей нашего API, создав SDK, CLI и даже Model Context Protocol (MCP) сервер. В этой статье я расскажу, как мы это делали, и с какими трудностями столкнулись.

Начнем с API

Исторически сложилось так, что наш бэкенд написан на Python с использованием Flask. На старте мы сразу заложили строгую типизацию данных с помощью библиотеки Marshmallow. Это позволяет описывать схемы данных, которые API должен отдавать, и валидировать входящие запросы. Если вы работали с Django REST, то Marshmallow — это аналог их Schemas.

			from marshmallow import Schema, fields

class ArtistSchema(Schema):
    name = fields.Str()

class AlbumSchema(Schema):
    title = fields.Str()
    release_date = fields.Date()
    artist = fields.Nested(ArtistSchema())

		

В какой-то момент мы решили, что хотим отдавать OpenAPI-спецификацию для нашего API. Мы попробовали flask-apispec, но столкнулись с проблемой: сгенерированная спецификация имела кучу ошибок в валидаторе, потому что библиотека миксовала OpenAPI v2 и v3. Частично это удалось решить с помощью ручных @doc() декораторов, но это было неудобно и больше походило на костыль, чем на нормальное решение.

В итоге я перешел на flask-smorest. Эта библиотека активно развивается, работает поверх Flask и Marshmallow и умеет генерировать корректный OpenAPI v3. Все завелось «из коробки» с минимальными изменениями. Marshmallow-схемы поддерживают метаданные, которые smorest потом проксирует в спецификацию. Например, так выглядит поле type для проверок в нашем коде:

			type = fields.Method(
    'get_type',
    'set_type',
    required=True,
    error_messages={'required': 'type field is required. Valid values are: web, tcp, ssl, api, synthetic, multistep'},
    metadata={
        "description": "The type of monitoring check to perform.",
        "example": "web",
        "enum": ["web", "api", "ssl", "tcp", "synthetic", "multistep"]
    }
)

		

smorest берёт эти данные и добавляет их в спеку. Кроме того, можно (и нужно) описать, какие коды ответов возвращает ваш API-метод и другие детали:

			@check_routes.response(200, MonitorCheckListSchema)
@check_routes.doc(
    summary='Get all monitor checks',
    description='Get all monitor checks for current organization with pagination',
    parameters=[
        {
            'name': 'page',
            'in': 'query',
            'required': False,
            'description': 'Page number for pagination (default: 1).',
            'schema': {'type': 'integer', 'minimum': 1, 'default': 1}
        },
        {
            'name': 'page_size',
            'in': 'query',
            'required': False,
            'description': 'Number of items per page (default: 20, max: 100).',
            'schema': {'type': 'integer', 'minimum': 1, 'maximum': 100, 'default': 20}
        }
    ],
    security=[
        {"bearerAuth": []},
        {"apiKeyAuth": []}
    ]
)

		

Как только мы это сделали, то получили приличный Swagger и валидную OpenAPI JSON-спецификаци

Swagger UI сгенерированный по openapi схеме

SDK

Далее мы поняли, что одного API недостаточно. Чтобы вызывать методы API из будущих CLI или MCP, нам не хотелось писать клиент с нуля. Поэтому мы решили создать SDK.

Если у вас есть OpenAPI-спецификация, то писать клиент с нуля бессмысленно. Для этого есть отличный инструмент — openapi-generator. Он позволяет сгенерировать API-клиенты для разных языков одной командой, просто получив на вход спецификацию.

Так мы получили полноценный Python-клиент и залили его в PyPI. Весь код можно найти на GitHub: pingera/pingera-python-sdk. Особенно интересен файл generate-client.py, который запускает openapi-generator и подменяет директории. После этого оставалось только залить все в PyPI, чтобы можно было использовать пакет в других сервисах и продуктах.

Конечно, имена сгенерированных методов не самые изящные, например v1_checks_check_id_results_check_result_id_get, но это в сто раз лучше, чем каждый раз писать requests.get, добавлять try-except обертки и волноваться об изменениях в API.

Model Context Protocol (MCP) сервер

MCP — это стандарт, разработанный компанией Anthropic (создатели Claude). Его идея — стандартизировать взаимодействие LLM с данными или сервисами, превращая их в ИИ-агентов. Теперь не нужно объяснять агенту, как взять данные из базы данных или JIRA, достаточно указать MCP-сервер, который уже это умеет, и агент сам разберётся.

Мы в Pingera давно задумывались о том, как искусственный интеллект повлияет на мониторинг, поэтому создание собственного MCP-сервера было логичным шагом.

Для создания MCP-сервера мы использовали фреймворк fastmcp. Код MCP-инструментов («tools») повторяет структуру нашего SDK. Например, в MCP есть код, который выводит список проверок:

			@mcp.tool()
async def list_checks(
    page: Optional[int] = None,
    page_size: Optional[int] = None,
    check_type: Optional[str] = None,
    status: Optional[str] = None
) -> str:
    """
    List all monitoring checks in your account.

    Checks are automated tests that monitor your websites, APIs, and services.
    They run at regular intervals and can trigger alerts when issues are detected.

    Args:
        page: Page number for pagination
        page_size: Number of items per page (max: 100)
        check_type: Filter by check type ('http', 'https', 'ping', 'tcp', 'ssl', 'dns', 'keyword')
        status: Filter by status ('active', 'paused', 'disabled')

    Returns:
        JSON with list of checks including names, URLs, types, intervals, and current status.
    """
    return await checks_tools.list_checks(page, page_size, check_type, status)

		

list_checks здесь просто вызывает метод SDK v1_checks_get().

Из-за такой повторяемости 80-85% кода MCP-сервера было сгенерировано ИИ-агентом Replit (можно взять любой другой). Весь код мы также опубликовали на GitHub: pingera/pingera-mcp. Подробнее о сценариях использования можно прочитать в нашем блоге: Pingera MCP сервер — ближе к AI.

Интерфейс MCP inspector

Command Line Interface (CLI)

CLI — это про консоль и инженеров. Иногда гораздо удобнее выполнить команду в терминале, чем заходить в веб-интерфейс и кликать мышкой.

Создание CLI было похоже на работу над MCP — много похожих вызовов методов. ИИ-агент снова отлично справился, хотя были проблемы с выводом результатов. Мы взяли две библиотеки: Typer для создания интерфейса и Rich для красивого, цветного вывода в консоль. С Rich были трудности — то таблица уезжала, то цвет не тот. Но ИИ справился и помог решить эти проблемы.

Вывод pngr - CLI тузлы Pingera

Весь код также доступен на GitHub: pingera/pingera-cli. Из-за ограниченного контекста LLM, нельзя было скормить агенту всю спецификацию сразу. Поэтому пока наш CLI умеет работать только с проверками.

Заключение

Использование ИИ-агентов для генерации повторяющегося кода — это не просто удобная фича. Как показал наш опыт с Replit, такие помощники берут на себя рутину, освобождая время для более сложных и творческих задач. Когда 80-85% кода MCP-сервера было сгенерировано автоматически, это позволило нам сосредоточиться на архитектуре, логике и оптимизации, вместо того чтобы вручную переписывать однотипные вызовы методов.

В конечном итоге, ИИ-агенты — это не замена инженеру, а инструмент, который многократно может повысить производительность. В будущем мы видим всё больше сценариев, где ИИ будет не просто предлагать фрагменты кода, а создавать целые модули и сервисы на основе высокоуровневых спецификаций. Это приближает нас к тому моменту, когда разработка будет похожа на управление оркестром, где дирижер (разработчик или продакт) задает направление, а умные агенты исполняют отдельные партии, обеспечивая гармонию и эффективность всего процесса.