AWS Resource MCP

Локальный MCP-сервер, разработанный на Python, для запроса реальных ресурсов аккаунта AWS в режиме только для чтения.

Статус

Фаза 9 реализована. Сервер сочетает унифицированную инвентаризацию, консервативный анализ активности, явную диагностику, экономический анализ и политики IAM с минимальными привилегиями, сгенерированные на основе реального журнала операций.

Related MCP server: aws-mcp-server

Предполагаемый охват

• Локальный транспорт MCP через stdio.

• Основной регион: eu-west-1.

• Запросы к AWS исключительно на чтение и с минимальными привилегиями.

• Доступные инструменты: health_check(), listar_recursos_aws(), analizar_actividad_recursos(), diagnosticar_cobertura_aws(), analizar_riesgo_costes(), revisar_free_tier() и consultar_costes_aws().

• Cost Explorer заблокирован до получения эфемерного согласия на точный запрос.

• Без развёртывания в AWS и без CI/CD.

Надёжность

Фаза 10 включает локальные тесты интеграции, контракта, безопасности, производительности и протокола MCP. Инвентаризация также применяет AWS_MCP_MAX_REQUESTS_PER_TOOL (250 по умолчанию) перед каждым вызовом SDK; при исчерпании лимита сохраняет результат и возвращает partial_request_budget_exhausted.

Непрерывная интеграция выполняет при каждом pull request форматирование, lint, компиляцию, детерминированную валидацию IAM и локальные тесты. Она не настраивает учётные данные AWS и не выполняет операции AWS.

Использование с Codex

Codex — основной клиент. Используйте точку входа пакета uv run aws-resource-mcp через stdio, настройте любой профиль AWS за пределами репозитория и начинайте с вопросов на естественном языке, например: «Какие ресурсы у меня есть в eu-west-1?». Когда ответ — partial_pending_consent, Codex должен объяснить точную операцию и дождаться явного одобрения; он никогда не создаёт постоянное согласие. См. интеграцию с Codex и демо.

Релиз v0.1.0

Первая версия готова к рецензированию: включает защиту только для чтения, эфемерное согласие, интеграцию с Codex и CI. Ознакомьтесь с чек-листом релиза, чтобы проверить её локально и запустить безопасное демо.

Разработка

Проект управляется с помощью uv и Python 3.12 или новее.

Установка зависимостей

uv sync

Запуск сервера

uv run aws-resource-mcp

Для диагностики его также можно запустить как модуль:

uv run python -m aws_resource_mcp.server

Сервер использует stdio: он ожидает, что MCP-клиент будет обмениваться сообщениями через стандартный ввод и вывод. Его можно открыть с помощью MCP Inspector через инструменты, включённые в SDK:

uv run mcp dev src/aws_resource_mcp/server.py

Запуск тестов

uv run pytest

Генерация и валидация политик IAM

uv run aws-resource-mcp-generate-iam
uv run aws-resource-mcp-generate-iam --check

Генерация выполняется локально, детерминированно и не использует учётные данные. Проект не создаёт и не изменяет роли или политики в AWS. Политики разделяют бесплатные операции, чтения, требующие согласия, и максимальную комбинацию; разрешение IAM никогда не заменяет согласие приложения.

Запуск инвентаризации AWS

Перед реальной диагностикой проверьте, какую личность определит локальная конфигурация:

aws sts get-caller-identity

Затем выполните инвентаризацию в регионе по умолчанию eu-west-1:

uv run python -m aws_resource_mcp.aws.inventory

Регион и общий профиль необязательны:

uv run python -m aws_resource_mcp.aws.inventory --region eu-central-1 --profile example

Ключи не сохраняются в проекте. Boto3 использует стандартную цепочку разрешения учётных данных; если указан AWS_PROFILE или --profile, выбирается только профиль, который уже должен существовать за пределами репозитория.

Инструменты MCP

health_check

health_check(check_aws=True) разделяет локальное состояние здоровья и доступность AWS. Без аргументов выполняет максимум один защищённый вызов STS; с check_aws=false не использует сеть. Возвращает версию, транспорт, зарегистрированные инструменты и адаптеры, регион, экономическую политику и ноль платных операций. Его состояния:

• ok: сервер и конфигурация действительны; STS ответил, когда это было запрошено.

• degraded: сервер работает, но отсутствуют учётные данные или STS недоступен.

• error: безопасная конфигурация или внутренние журналы не могут быть инициализированы.

Личность анонимизируется: сохраняется только общий тип субъекта и, если он существует, замаскированный аккаунт. Не выполняет инвентаризацию, Resource Explorer, адаптеры, CloudTrail или CloudWatch.

listar_recursos_aws

Запрашивает доступную инвентаризацию AWS для локальных учётных данных без изменения ресурсов. Параметры:

• region: ограничивает поиск регионом; без значения использует всё доступное покрытие.

• services: фильтрует по сервисам, таким как lambda, s3, ec2 или rds.

• include_account_id: позволяет опустить ID аккаунта из ответа для упрощения анонимизации.

• resource_types: фильтрует по динамическим типам, таким как ec2:instance.

• query: ищет по тексту или имени.

• all_regions: использует включённые регионы, когда region не указан.

• include_details: включает специфические метаданные внутри details.

• include_cost_indicators: включает потенциальные сигналы стоимости без утверждения реальных расходов.

• confirm_potentially_billable_operations: устаревший параметр, который больше не предоставляет разрешений.

• include_activity_summary: добавляет краткую сводку, используя только уже полученные поля; не запрашивает CloudTrail или CloudWatch.

• consent_request_id, consent_action и approved_services: возобновляют или отменяют эфемерный и ограниченный запрос.

• timeout_seconds: настраиваемый бюджет от 1 до 120 секунд.

Пример аргументов, отправляемых MCP-клиентом:

{
  "region": "eu-west-1",
  "services": ["lambda", "s3"],
  "include_account_id": false,
  "all_regions": true
}

Первый вызов возвращает ресурсы, полученные с помощью разрешённых операций. Если для завершения S3, SQS или SNS требуются операции, подлежащие учёту, возвращается partial_pending_consent, pending_operations и запрос, срок действия которого истекает через пять минут. Эти операции не выполняются до второго явного вызова:

{
  "consent_request_id": "<id devuelto por la primera llamada>",
  "consent_action": "approve",
  "approved_services": ["s3"]
}

Одобрение одноразовое, привязано к исходной личности и охвату и ограничивает операции, регионы и запросы. Обнаружение и обогащение авторизуются отдельно; дополнительная страница требует нового запроса. consent_action: "cancel" не выполняет инвентаризацию AWS.

Состояния различают complete_for_requested_scope, partial_pending_consent, partial_timeout, partial_permission_denied, partial_unavailable, consent_cancelled и error. Пустой список означает только то, что сервис был пуст на момент запроса.

resources, all_resources и resources_by_service представляют одну и ту же дедуплицированную инвентаризацию. Каждый ресурс содержит id, arn, name, service, resource_type, region, account_id, state, created_at, sources, details, cost_indicators и activity. Инструмент не рассчитывает стоимость, не запрашивает Free Tier и не выполняет операций записи.

analizar_actividad_recursos

Анализирует последний известный признак, используя один и тот же журнал и модель для всех ресурсов. Принимает фильтры по services, regions и resource_ids, а также inactive_days, lookback_days, include_administrative_events и настраиваемые лимиты. История CloudTrail ограничена 90 днями и запрашивается по регионам, а не по каждому ресурсу отдельно.

Ответ разделяет last_functional_usage_at, last_administrative_activity_at, last_configuration_change_at и last_state_change_at. best_known_activity_at всегда также указывает тип сигнала. Активное состояние, запрос Describe* или дата изменения не представляются как функциональное использование.

Состояния по ресурсам: active, inactive_candidate, unknown, not_supported или error. Кандидат на неактивность — это лишь элемент для проверки: требуется достаточный возраст, релевантный запрошенный источник и отсутствие недавних противоречивых доказательств. Отсутствие разрешений, недостаточные источники или неоднозначные связи дают unknown, а не ложную уверенность в неактивности.

CloudWatch мог бы предоставить функциональные метрики, но GetMetricData, GetMetricStatistics и ListMetrics зарегистрированы как потенциально платные и заблокированы. include_paid_sources=true только запрашивает структурированное объяснение; это не является согласием и никогда не выполняет эти операции на данном этапе.

diagnosticar_cobertura_aws

Объясняет, что MCP действительно может запрашивать, не перечисляя ресурсы. Принимает фильтры services и regions и позволяет опускать разделы разрешений, активности или экономической политики.

Проверяет STS, включённые регионы, существующие индексы Resource Explorer, журнал и возможности адаптеров, бесплатные источники активности и заблокированные операции. Проверки ограничены пятью регионами за выполнение, одной выборкой CloudTrail и ни одним вызовом CloudWatch.

Состояния покрытия различают available, partial, unavailable, not_configured, permission_denied, blocked_by_cost_policy, not_supported, not_checked и error. Операция, объявленная политикой как разрешённая, не представляется как доказанное разрешение IAM: диагностика не выполняет инвентаризацию сервисов для её проверки.

Пример:

{
  "services": ["ec2", "rds"],
  "regions": ["eu-west-1"],
  "include_activity_sources": true
}

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

analizar_riesgo_costes

Приоритизирует ресурсы с помощью индикаторов инвентаризации и, при необходимости, общего конвейера активности. Возвращает none_detected, low, medium, high, critical или unknown, объяснимую оценку и неисполняемые рекомендации. Сигнал не подтверждает расходы, а none_detected не означает нулевую стоимость.

include_free_tier=true добавляет официальные данные Free Tier. include_actual_cost=true только подготавливает согласие для Cost Explorer: запрос не выполняется.

revisar_free_tier

Запрашивает GetFreeTierUsage и GetAccountPlanState — операции, которые AWS документирует как бесплатные. Разделяет месячные лимиты, прогноз, план и кредиты. Может возвращать частичную или неизвестную информацию из-за разрешений, задержки обновления, исчерпания предложения или различий в праве на участие. Не утверждает, что конкретный ресурс бесплатен.

consultar_costes_aws

Подготавливает агрегированный запрос GetCostAndUsage для точного периода и фильтров. Первый вызов выполняет ноль операций AWS и возвращает эфемерный запрос с опубликованной ценой 0,01 USD за запрос по основному представлению. Второй вызов с consent_action="approve" выполняет максимум одну страницу; каждая дополнительная страница требует нового согласия. cancel не вызывает AWS.

Гранулярность может быть MONTHLY или DAILY; end_date является исключающей. Прогноз, детализация по ресурсам, связанные аккаунты и пользовательские billing views не реализованы на данном этапе.

Инвентаризация AWS

Boto3 — официальный SDK AWS для Python. Слой инвентаризации использует:

• STS GetCallerIdentity для идентификации аккаунта и фактической личности.

• EC2 DescribeRegions для обнаружения только включённых регионов.

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

• Общий реестр адаптеров для Lambda, S3, EC2/EBS/VPC, RDS/Aurora, DynamoDB, ECS/Fargate, API Gateway, CloudFormation, SQS, SNS, IAM, CloudFront и Route 53.

• CloudTrail LookupEvents для бесплатной региональной истории событий управления за последние 90 дней.

Lambda и S3 были первыми реализованными сервисами, но больше не сохраняют особых архитектурных путей. Все адаптеры объявляют метаданные, операции Boto3, область действия, типы, детали и индикаторы через один и тот же контракт. Конкретные детали находятся исключительно внутри details.

Результаты дедуплицируются по ARN или, если он отсутствует, по типу, региону и идентификатору/имени. Предпочтителен агрегирующий индекс; при локальных индексах результаты объединяются, а покрытие является частичным. Если Resource Explorer недоступен, выполняются все выбранные адаптеры, поддерживающие обнаружение.

Отсутствие учетных данных или невозможность идентифицировать учетную запись является глобальной ошибкой для инвентаризации, но лишь состоянием degraded для локального здоровья. Диагностика сохраняет свои локальные проверки и безопасно пропускает зависящие от AWS.

Все вызовы Boto3 сначала проходят через центральный реестр. Незарегистрированные операции, операции записи или операции с неизвестной стоимостью блокируются. Режим free-only остается активным на протяжении всего процесса. S3, SQS и SNS могут учитывать запросы: их перечисления представляются как ожидающие, и только точный эфемерный грант позволяет их выполнить. Страж учитывает отдельно уникальные операции и реальные запросы.

Примеры для MCP-клиента: «Какие ресурсы есть в моей учетной записи?», «Перечисли экземпляры EC2 в eu-west-1», «Найди ресурсы с именем web» или «Покажи развернутые типы RDS». Resource Explorer обеспечивает широкое, но не универсальное покрытие.

Документация

• Архитектура

• Решения

• Этапы

• Прогресс

• Политика zero-cost

• Адаптеры сервисов

• Анализ активности

• Диагностика и покрытие

• Поток согласия инвентаризации

• Экономический анализ, Free Tier и реальные затраты

• IAM с минимальными привилегиями

• Матрица разрешений IAM

• Ручная настройка IAM