CloudOps MCP

CloudOps MCP — это сервер Model Context Protocol только для чтения, который предоставляет нормализованный операционный контекст инфраструктуры (логи, метрики, развертывания, состояние здоровья) агентам ИИ через небольшой набор типизированных, ограниченных инструментов.

Зачем это нужно

Агенту, расследующему инцидент, нужен операционный контекст: что изменилось недавно, как выглядит уровень ошибок, что говорят логи. Ему не нужен неограниченный доступ к облачным API, и он не должен решать, что является первопричиной.

CloudOps MCP находится между ними:

Cloud APIs / observability systems
        |
Provider adapters
        |
Normalized operational domain
        |
Deterministic services
        |
MCP tools
        |
AI agent

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

CloudOps MCP возвращает операционные факты, а не заключения о первопричинах. Инструмент может сказать «уровень ошибок вырос с 0,4% до 8% в 14:06»; он не скажет «развертывание вызвало сбой». Это решение остается за агентом, с фактами, которые CloudOps MCP предоставляет ему в качестве доказательств.

Related MCP server: cloud-chat-assistant

Возможности

Шесть инструментов, все только для чтения и с ограничениями:

get_operational_snapshot объединяет те же примитивные сервисы, которые используют остальные пять инструментов, выполняя все четыре независимых запроса одновременно. Он никогда не общается с провайдером напрямую и никогда не выходит из строя целиком из-за недоступности одного раздела; каждый раздел сообщает о своем собственном статусе.

Принципы проектирования

• Только для чтения по построению. Интерфейсы провайдеров не предоставляют методов модификации. Нет кода, ведущего к API записи.

• Идентификация сервиса, нейтральная к провайдеру. Сервис идентифицируется по (service, environment). Зависящие от вендора идентификаторы (группа логов CloudWatch, имя объекта Kubernetes) остаются внутренними для привязок провайдера и никогда не являются частью публичного контракта.

• Канонические, расширяемые метрики. error_rate, latency_p99 и подобные названия — наши, а не вендора. Отображение канонического имени на реальную метрику находится в конфигурации, для каждого сервиса. Словарь открыт, а не является фиксированным перечислением.

• Ограниченные запросы. Каждый телеметрический запрос имеет ограничение по временному диапазону и по количеству. Вызывающий может запросить меньше; он не может запросить неограниченные данные.

• Явная доступность данных. Каждая коллекция сообщает одно из SUCCESS, EMPTY, PARTIAL или FAILED. Отсутствующие данные никогда молча не воспринимаются как «здорово» или «ничего не произошло».

• Доступность отдельно от результата. NOT_CONFIGURED (нет подключенного провайдера) и EMPTY (успешно запрошено, ноль совпадений) — разные состояния и никогда не смешиваются.

• Происхождение без утечки внутренних деталей. Отдельные результаты содержат provider и source, если их предоставляет адаптер провайдера. Внутренняя ссылка, использованная для вызова провайдера, никогда не копируется в публичный вывод.

• UTC везде. Все метки времени учитывают часовой пояс и нормализованы к UTC; наивные даты и время отклоняются на границе модели.

• Никаких LLM внутри сервера MCP. Никакого обобщения, никакой классификации, никаких выводов по содержимому логов. Сообщения логов обрабатываются как непрозрачный, ненадежный текст.

• Никаких причинно-следственных рассуждений. Инструменты сообщают, что изменилось и когда. Интерпретация «почему» оставлена агенту.

Быстрый старт: режим эмуляции

Режим эмуляции используется по умолчанию и является основным способом опробовать CloudOps MCP. Для него не требуется учетная запись облака.

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Запустите сервер (транспорт stdio):

python -m cloudops_mcp.server

Или, если пакет установлен с его консольным скриптом:

cloudops-mcp

Сервер говорит по протоколу MCP через stdio и ожидает клиента на другом конце. Чтобы попробовать его напрямую из Python, используя официальный клиент SDK:

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(command="python", args=["-m", "cloudops_mcp.server"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

            result = await session.call_tool(
                "get_operational_snapshot",
                {"service": "checkout-api", "environment": "production"},
            )
            print(result.structured_content)

asyncio.run(main())

Сценарии эмуляции

Выберите сценарий с помощью CLOUDOPS_MCP_SCENARIO (по умолчанию healthy):

CLOUDOPS_MCP_SCENARIO=bad_deploy python -m cloudops_mcp.server

bad_deploy закладывает три коррелированных факта с фиксированными метками времени: развертывание, затем сдвиг метрик через несколько минут, затем строки логов с тайм-аутами вскоре после этого. CloudOps MCP сообщает об этих трех фактах и ни о чем больше. Он не утверждает, что развертывание вызвало ошибки; этот вывод полностью оставлен потребляющему агенту.

Режим AWS CloudWatch

pip install -e ".[aws]"        # runtime only
pip install -e ".[dev,aws]"    # development

CLOUDOPS_MCP_MODE=aws CLOUDOPS_MCP_CONFIG=/path/to/cloudops.toml cloudops-mcp

Полный пример конфигурации см. в examples/aws-cloudwatch.toml. В нем используются только значения-заполнители; ни один реальный идентификатор учетной записи, ARN или учетные данные не должны находиться в этом файле.

Учетные данные полностью берутся из стандартной цепочки провайдеров boto3: AWS_PROFILE, AWS_REGION / AWS_DEFAULT_REGION, учетные данные из окружения или роль IAM. CloudOps MCP никогда не читает, не хранит и не регистрирует ключ доступа или секрет.

Реализовано в режиме AWS:

• Логи: CloudWatch Logs FilterLogEvents.

• Метрики: CloudWatch GetMetricData (только запросы MetricStat).

Пока не реализовано: развертывания и здоровье на базе AWS. Сервис, настроенный без этих разделов, просто сообщает NOT_CONFIGURED для них, так же как и для любой другой ненастроенной возможности. См. docs/aws.md для схемы конфигурации, поведения пагинации и ограничений.

AWS IAM

Минимальная политика только для чтения для этой интеграции (вымышленная учетная запись и группа логов):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "logs:FilterLogEvents",
      "Resource": "arn:aws:logs:us-east-1:123456789012:log-group:/aws/lambda/checkout-api"
    },
    {
      "Effect": "Allow",
      "Action": "cloudwatch:GetMetricData",
      "Resource": "*"
    }
  ]
}

FilterLogEvents может быть ограничен конкретным ARN группы логов. Для запросов MetricStat, которые выполняет эта интеграция, GetMetricData не имеет ограничения на уровне ресурсов в модели авторизации IAM AWS, поэтому в этом выражении используется Resource: "*". Это свойство API, а не выбор, сделанный здесь.

Ограниченные запросы

Каждый ограниченный результат сообщает как requested_bounds, так и applied_bounds, чтобы вызывающий мог точно увидеть, что было обрезано. Обрезка запроса до жесткого лимита — это не то же самое, что PARTIAL: обрезанный, но полностью удовлетворенный запрос по-прежнему является SUCCESS. PARTIAL означает, что извлечение, как известно, неполное, например, провайдер выполнил пагинацию и остановился до того, как исчерпал все совпадения в пределах примененного окна.

Семантика доступности данных

Два ортогональных вопроса, никогда не сводимые в один:

1. Настроена ли возможность для этого сервиса вообще? (CONFIGURED / NOT_CONFIGURED)

2. Если она была запрошена, что произошло? (SUCCESS / EMPTY / PARTIAL / FAILED)

Проверка здоровья для сервиса, у которого не настроен провайдер здоровья, — это NOT_CONFIGURED, а не EMPTY и не FAILED. Запрос логов, который обоснованно ничего не нашел во временном окне, — это EMPTY, а не FAILED. Вызов метрик, который достиг ограничения скорости, прежде чем вернуть что-либо полезное, — это FAILED с причиной, а не молча пустые данные.

Структурированные выходные данные MCP

Каждый инструмент принимает типизированные аргументы и возвращает типизированную модель Pydantic. Официальный Python MCP SDK извлекает structuredContent и схему вывода инструмента непосредственно из этого типа возврата; ответы инструментов — это реальные структурированные данные, а не строка JSON, обернутая в текстовый блок.

Архитектура

flowchart TD
    subgraph Providers
        Fake[Fake providers]
        AWS[AWS CloudWatch providers]
    end

    Fake --> Services
    AWS --> Services

    Registry[ServiceRegistry] --> Services

    subgraph Services[Deterministic services]
        Catalog[catalog_service]
        Health[health_service]
        Deploy[deployment_service]
        Logs[logs_service]
        Metrics[metrics_service]
        Snapshot[snapshot_service]
    end

    Snapshot --> Deploy
    Snapshot --> Logs
    Snapshot --> Metrics
    Snapshot --> Health

    Services --> Tools[MCP tools]
    Tools --> Agent[AI agent]

get_operational_snapshot объединяет примитивные сервисы, он не обходит их и не общается с провайдерами самостоятельно. Полную техническую разбивку см. в docs/architecture.md.

Тестирование

• Детерминированные сценарии эмуляции проверяют всю поверхность инструментов от начала до конца.

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

• Тесты AWS-провайдеров используют маленькие клиенты-заглушки CloudWatch, никаких реальных вызовов AWS, никакого moto, никакого LocalStack.

• Один тест запускает реальный клиент MCP SDK против внутрипроцессного сервера, подтверждая саму границу протокола (обнаружение инструментов, структурированный вывод), а не только внутреннюю логику.

ruff check src tests
mypy src tests --strict
pytest -q

Текущие ограничения

• Прямая валидация AWS выполнялась с помощью типизированного разбора конфигурации, тестов с клиентами-заглушками и реальной границы клиент/сервер MCP, но еще не против реальной учетной записи AWS. Для этого требуются выбранные пользователем ресурсы, и это намеренно не автоматизировано: CloudOps MCP не обнаруживает и не сканирует учетную запись самостоятельно.

• Пока нет провайдера развертываний или здоровья на базе AWS.

• Только транспорт stdio, удаленный MCP отсутствует.

• Реестр сервисов статичен и основан на конфигурации, нет автоматического обнаружения сервисов из облачной учетной записи.

• Нет никаких мутаций, исправлений или путей записи.

План развития

• Дополнительные возможности только для чтения у существующих провайдеров.

• Второй реальный провайдер для проверки границы нормализации с более чем одним вендором.

• Удаленный транспорт, если сценарий развертывания действительно в нем нуждается.

• Использование агентами реагирования на инциденты, как один из примеров универсального клиента MCP. CloudOps MCP не привязан к какому-либо конкретному потребителю.

Безопасность

• Никаких методов мутации в интерфейсах провайдера.

• Никакого выполнения команд оболочки, никаких вызовов подпроцессов облачного CLI.

• IAM с минимальными привилегиями: только logs:FilterLogEvents и cloudwatch:GetMetricData, ничего не запрашивается "на всякий случай".

• Только стандартная цепочка учетных данных AWS, без обработки пользовательских учетных данных.

• Внутренние ссылки провайдера (имена групп логов, измерения CloudWatch) никогда не появляются в выводе инструмента.

• Содержимое логов рассматривается как ненадежный, непрозрачный текст: никогда не анализируется, не выполняется и не интерпретируется.

• Неожиданные сбои санируются на границе инструмента; только фиксированное общее сообщение пересекает ее, никогда — необработанная строка исключения.

• Каждый телеметрический запрос ограничен, защищая как API провайдера, так и контекстное окно агента.

Лицензия

MIT, см. LICENSE.