AWS DynamoDB MCP Server

AWS DynamoDB MCP Server

Официальный MCP-сервер для разработчиков, работающих с Amazon DynamoDB. Этот сервер предоставляет экспертные рекомендации по проектированию DynamoDB и помощь в моделировании данных.

[!IMPORTANT] Генеративный ИИ может допускать ошибки. Рекомендуется проверять все выходные данные, сгенерированные выбранной вами моделью ИИ и ассистентом по кодированию. См. Политику ответственного использования ИИ AWS.

Доступные инструменты

MCP-сервер DynamoDB предоставляет восемь инструментов для моделирования данных, валидации, анализа затрат и генерации кода:

• dynamodb_data_modeling - Извлекает полный экспертный промпт по моделированию данных DynamoDB с шаблонами проектирования корпоративного уровня, стратегиями оптимизации затрат и философией проектирования с несколькими таблицами. Проводит через сбор требований, анализ шаблонов доступа и проектирование схемы.

  Пример вызова: "Спроектируй модель данных для моего приложения электронной коммерции, используя MCP-сервер моделирования данных DynamoDB"

• dynamodb_data_model_validation - Проверяет вашу модель данных DynamoDB, загружая dynamodb_data_model.json, настраивая DynamoDB Local, создавая таблицы с тестовыми данными и выполняя все определенные шаблоны доступа. Сохраняет подробные результаты валидации в dynamodb_model_validation.json.

  Пример вызова: "Проверь мою модель данных DynamoDB"

• source_db_analyzer - Анализирует существующие базы данных (MySQL, PostgreSQL, SQL Server, Oracle) для извлечения структуры схемы, шаблонов доступа и генерирует файлы анализа с временными метками для использования с dynamodb_data_modeling. Поддерживает доступ как через RDS Data API, так и на основе подключения для MySQL.

  Пример вызова: "Проанализируй мою базу данных MySQL и помоги спроектировать модель данных DynamoDB"

• generate_resources - Генерирует различные ресурсы из JSON-файла модели данных DynamoDB (dynamodb_data_model.json). В настоящее время поддерживается только тип ресурса cdk. Передача cdk в качестве параметра resource_type генерирует CDK-приложение для развертывания таблиц DynamoDB. CDK-приложение читает dynamodb_data_model.json для создания таблиц с правильной конфигурацией.

  Пример вызова: "Сгенерируй ресурсы для развертывания моей модели данных DynamoDB с помощью CDK"

• dynamodb_data_model_schema_converter - Преобразует вашу модель данных (dynamodb_data_model.md) в структурированный файл schema.json, представляющий ваши таблицы DynamoDB, индексы, сущности, поля и шаблоны доступа. Этот машиночитаемый формат используется для генерации кода и может быть расширен для других целей, таких как генерация документации или предоставление инфраструктуры. Автоматически проверяет схему до 8 итераций для обеспечения корректности.

  Пример вызова: "Преобразуй мою модель данных в schema.json для генерации кода"

• dynamodb_data_model_schema_validator - Проверяет файлы schema.json на совместимость с генерацией кода. Проверяет типы полей, операции, сопоставления GSI, идентификаторы шаблонов и предоставляет подробные сообщения об ошибках с предложениями по исправлению. Гарантирует, что ваша схема готова для инструмента generate_data_access_layer.

  Пример вызова: "Проверь мой файл schema.json по пути /path/to/schema.json"

• generate_data_access_layer - Генерирует типобезопасный код Python из schema.json, включая классы сущностей с валидацией полей, классы репозиториев с операциями CRUD, полностью реализованные шаблоны доступа и опциональные примеры использования. Сгенерированный код использует Pydantic для валидации и boto3 для операций DynamoDB.

  Пример вызова: "Сгенерируй код Python из моего schema.json"

• compute_performances_and_costs - Рассчитывает единицы емкости DynamoDB (RCU/WCU) и ежемесячные затраты на основе шаблонов доступа. Анализирует все операции DynamoDB (GetItem, Query, Scan, PutItem, UpdateItem, DeleteItem, BatchGetItem, BatchWriteItem, TransactGetItems, TransactWriteItems), отслеживает дополнительную запись в GSI и рассчитывает затраты на хранение. Добавляет подробный отчет о затратах в dynamodb_data_model.md.

  Пример вызова: "Рассчитай стоимость и производительность для моей модели данных DynamoDB"

Предварительные требования

1. Установите uv с Astral или из README на GitHub
2. Установите Python с помощью uv python install 3.10
3. Настройте учетные данные AWS с доступом к сервисам AWS

Установка

Kiro	Cursor	VS Code

Примечание: Кнопки установки выше по умолчанию настраивают AWS_REGION на us-west-2. Обновите это значение в конфигурации MCP после установки, если вам нужен другой регион.

Добавьте MCP-сервер в файл конфигурации (для Kiro добавьте в .kiro/settings/mcp.json - см. путь конфигурации):

{
  "mcpServers": {
    "awslabs-dynamodb-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.dynamodb-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Установка в Windows

Для пользователей Windows формат конфигурации MCP-сервера немного отличается:

{
  "mcpServers": {
    "awslabs-dynamodb-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "awslabs.dynamodb-mcp-server@latest",
        "awslabs.dynamodb-mcp-server.exe"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

Установка с Docker

После успешного docker build -t awslabs/dynamodb-mcp-server .:

{
  "mcpServers": {
    "awslabs-dynamodb-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--interactive",
        "--env",
        "FASTMCP_LOG_LEVEL=ERROR",
        "awslabs/dynamodb-mcp-server:latest"
      ],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

Моделирование данных

Моделирование данных на естественном языке

Используйте инструмент dynamodb_data_modeling для проектирования моделей данных DynamoDB через общение на естественном языке с вашим ИИ-агентом. Просто спросите: "используй мой DynamoDB MCP, чтобы помочь спроектировать модель данных DynamoDB."

Инструмент обеспечивает структурированный рабочий процесс, который преобразует требования приложения в модели данных DynamoDB:

Фаза сбора требований:

• Фиксирует шаблоны доступа через общение на естественном языке
• Документирует сущности, связи и шаблоны чтения/записи
• Записывает предполагаемое количество запросов в секунду (RPS) для каждого шаблона
• Создает файл dynamodb_requirements.md, который обновляется в реальном времени
• Определяет шаблоны, лучше подходящие для других сервисов AWS (OpenSearch для текстового поиска, Redshift для аналитики)
• Отмечает особые соображения по проектированию (например, массивные шаблоны fan-out, требующие DynamoDB Streams и Lambda)

Фаза проектирования:

• Генерирует оптимизированные проекты таблиц и индексов
• Создает dynamodb_data_model.md с подробным обоснованием проекта
• Предоставляет предполагаемые ежемесячные затраты
• Документирует, как поддерживается каждый шаблон доступа
• Включает рекомендации по оптимизации для масштабирования и производительности

Инструмент подкреплен экспертно-разработанным контекстом, который помогает моделям рассуждения проводить вас через продвинутые техники моделирования. Наилучшие результаты достигаются с моделями, способными к рассуждению, такими как Anthropic Claude 4/4.5 Sonnet, OpenAI o3 и Google Gemini 2.5.

Валидация модели данных

Предварительные требования для валидации модели данных: Для использования инструмента валидации модели данных вам необходимо одно из следующего:

• Среда выполнения контейнеров: Docker, Podman, Finch или nerdctl с запущенным демоном
• Среда выполнения Java: Java JRE версии 17 или новее (установите JAVA_HOME или убедитесь, что java находится в системном PATH)

После завершения проектирования модели данных используйте инструмент dynamodb_data_model_validation для автоматического тестирования вашей модели данных на DynamoDB Local. Инструмент валидации замыкает цикл между генерацией и выполнением, создавая итеративный цикл валидации.

Как это работает:

Инструмент автоматизирует традиционный ручной процесс валидации:

1. Настройка: Запускает среду DynamoDB Local (Docker/Podman/Finch/nerdctl или резервный вариант с Java)
2. Генерация спецификации тестирования: Создает dynamodb_data_model.json со списком таблиц, образцами данных и шаблонами доступа для тестирования
3. Развертывание схемы: Создает таблицы, индексы и вставляет образцы данных локально
4. Выполнение тестов: Запускает все операции чтения и записи, определенные в ваших шаблонах доступа
5. Проверка результатов: Проверяет, что каждый шаблон доступа работает корректно и эффективно
6. Итеративное уточнение: Если валидация не удалась (например, запрос возвращает неполные результаты из-за несовпадения ключа раздела), инструмент фиксирует проблему, перегенерирует затронутую схему и повторно запускает тесты, пока все шаблоны не пройдут проверку

Результаты валидации:

• dynamodb_model_validation.json: Подробные результаты валидации с ответами шаблонов
• validation_result.md: Сводка процесса валидации со статусом прохождения/непрохождения для каждого шаблона доступа
• Выявляет проблемы, такие как некорректные структуры ключей, отсутствующие индексы или неэффективные шаблоны запросов

Анализ исходной базы данных

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

Инструмент поддерживает два метода подключения для MySQL:

• Доступ через RDS Data API: Бессерверное подключение с использованием ARN кластера
• Доступ на основе подключения: Традиционное подключение с использованием имени хоста/порта

Поддерживаемые базы данных:

• MySQL / Aurora MySQL
• PostgreSQL
• SQL Server
• Oracle

Режимы выполнения:

• Режим самообслуживания: Генерация SQL-запросов, их самостоятельный запуск, предоставление результатов (MySQL, PostgreSQL, SQL Server, Oracle)
• Управляемый режим: Прямое подключение через AWS RDS Data API (только MySQL)

Рекомендуется запускать этот инструмент на непроизводственном экземпляре базы данных.

Режим самообслуживания (MySQL, PostgreSQL, SQL Server, Oracle)

Режим самообслуживания позволяет анализировать любую базу данных без подключения к AWS:

1. Генерация запросов: Инструмент записывает SQL-запросы (на основе выбранной базы данных) в файл
2. Запуск запросов: Вы выполняете запросы к своей базе данных
3. Предоставление результатов: Инструмент анализирует результаты и генерирует анализ

Управляемый режим (только MySQL)

Управляемый режим позволяет подключить инструмент к AWS RDS Data API для анализа существующих баз данных MySQL/Aurora с целью извлечения схемы и шаблонов доступа для моделирования DynamoDB.

Предварительные требования для интеграции с MySQL (управляемый режим)

Для доступа через RDS Data API:

1. Кластер MySQL с включенным RDS Data API
2. Учетные данные базы данных, хранящиеся в AWS Secrets Manager
3. Учетные данные AWS с разрешениями на доступ к RDS Data API и Secrets Manager

Для доступа на основе подключения:

1. Сервер MySQL, доступный из вашей среды

2. Учетные данные базы данных, хранящиеся в AWS Secrets Manager

3. Секрет Secrets Manager должен содержать поле host, соответствующее имени хоста вашей базы данных (в дополнение к username и password). Это гарантирует, что учетные данные используются только с предполагаемым хостом базы данных. Секреты, управляемые RDS, включают это поле автоматически. Если вы создали секрет вручную, убедитесь, что он соответствует стандартной структуре:

   aws secretsmanager create-secret \
       --name "my-db-secret" \
       --secret-string '{
           "engine": "mysql",
           "host": "my-db.cluster-xxx.us-east-1.rds.amazonaws.com",
           "username": "<username>",
           "password": "<password>",
           "dbname": "<database name>",
           "port": 3306
       }'
   

4. Учетные данные AWS с разрешениями на доступ к Secrets Manager

Для обоих методов подключения: 4. Включите Performance Schema для анализа шаблонов доступа (опционально, но рекомендуется):

• Установите параметр performance_schema в 1 в группе параметров БД
• Перезагрузите экземпляр БД после изменений
• Проверьте с помощью: SHOW GLOBAL VARIABLES LIKE '%performance_schema'
• Рассмотрите настройку:
  • performance_schema_digests_size - Максимальное количество строк в events_statements_summary_by_digest
  • performance_schema_max_digest_length - Максимальная длина в байтах для дайджеста оператора (по умолчанию: 1024)
• Без Performance Schema анализ основывается только на information schema

Переменные окружения MySQL

Добавьте эти переменные окружения для включения интеграции с MySQL:

Для доступа через RDS Data API:

• MYSQL_CLUSTER_ARN: ARN кластера MySQL
• MYSQL_SECRET_ARN: ARN секрета, содержащего учетные данные базы данных
• MYSQL_DATABASE: Имя базы данных для анализа
• AWS_REGION: Регион AWS кластера

Для доступа на основе подключения:

• MYSQL_HOSTNAME: Имя хоста или конечная точка сервера MySQL
• MYSQL_PORT: Порт сервера MySQL (опционально, по умолчанию: 3306)
• MYSQL_SECRET_ARN: ARN секрета, содержащего учетные данные базы данных
• MYSQL_DATABASE: Имя базы данных для анализа
• AWS_REGION: Регион AWS, где находится Secrets Manager

Общие параметры:

• MYSQL_MAX_QUERY_RESULTS: Максимальное количество строк в выходных файлах анализа (опционально, по умолчанию: 500)

Примечание: Явные параметры инструмента имеют приоритет над переменными окружения. Следует указывать только один метод подключения (ARN кластера или имя хоста).

Конфигурация MCP с MySQL

Для доступа через RDS Data API:

{
  "mcpServers": {
    "awslabs-dynamodb-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.dynamodb-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "default",
        "AWS_REGION": "us-west-2",
        "FASTMCP_LOG_LEVEL": "ERROR",
        "MYSQL_CLUSTER_ARN": "arn:aws:rds:$REGION:$ACCOUNT_ID:cluster:$CLUSTER_NAME",
        "MYSQL_SECRET_ARN": "arn:aws:secretsmanager:$REGION:$ACCOUNT_ID:secret:$SECRET_NAME",
        "MYSQL_DATABASE": "<DATABASE_NAME>",
        "MYSQL_MAX_QUERY_RESULTS": "500"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Для доступа на основе подключения:

{
  "mcpServers": {
    "awslabs.dynamodb-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.dynamodb-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "default",
        "AWS_REGION": "us-west-2",
        "FASTMCP_LOG_LEVEL": "ERROR",
        "MYSQL_HOSTNAME": "<MYSQL_HOST>",
        "MYSQL_PORT": "3306",
        "MYSQL_SECRET_ARN": "arn:aws:secretsmanager:$REGION:$ACCOUNT_ID:secret:$SECRET_NAME",
        "MYSQL_DATABASE": "<DATABASE_NAME>",
        "MYSQL_MAX_QUERY_RESULTS": "500"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Использование анализа исходной базы данных

1. Запустите source_db_analyzer для вашей базы данных (режим Self-service или Managed)
2. Изучите созданную папку анализа с меткой времени (database_analysis_YYYYMMDD_HHMMSS)
3. Сначала прочитайте файл manifest.md — в нём перечислены все файлы анализа и статистика
4. Прочитайте все файлы анализа, чтобы понять структуру схемы и шаблоны доступа
5. Используйте анализ вместе с dynamodb_data_modeling для проектирования схемы DynamoDB

Инструмент генерирует Markdown-файлы, содержащие:

• Структуру схемы (таблицы, столбцы, индексы, внешние ключи)
• Шаблоны доступа из Performance Schema (шаблоны запросов, RPS, частоты)
• Анализ с меткой времени для отслеживания изменений во времени

Преобразование схемы и генерация кода

После проектирования модели данных DynamoDB вы можете преобразовать её в структурированную схему и сгенерировать эталонный код на Python. При использовании инструментов MCP через LLM весь этот рабочий процесс происходит автоматически — LLM проведёт вас через преобразование схемы, валидацию и генерацию кода в рамках одного диалога, без необходимости ручного вызова инструментов.

Для автономного использования вы также можете вызывать эти инструменты напрямую через CLI или вручную редактировать файлы schema.json и перегенерировать код по мере необходимости.

Примечание: Валидация модели данных (dynamodb_data_model_validation) необязательна для генерации кода. Однако, если вы планируете тестировать сгенерированный код с помощью usage_examples.py на DynamoDB Local, рекомендуется сначала выполнить валидацию, так как она автоматически создаёт таблицы и тестовые данные в DynamoDB Local.

Преобразование модели данных в схему

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

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

Структура схемы:

Сгенерированный schema.json — это структурированное представление, содержащее:

• Таблицы: Одно или несколько определений таблиц DynamoDB с ключами партицирования/сортировки
• Определения GSI: Конфигурации глобальных вторичных индексов (опционально)
• Сущности: Доменные модели (User, Order, Product и т.д.) с типизированными полями
• Типы полей: string, integer, decimal, boolean, array, object, uuid
• Шаблоны доступа: Операции Query/Scan/GetItem с определениями параметров и шаблонами ключей
• Шаблоны ключей: Шаблоны для генерации ключей партицирования и сортировки (например, USER#{user_id})

Этот структурированный формат служит входными данными для инструментов генерации кода.

Валидация файлов схемы

Инструмент dynamodb_data_model_schema_validator проверяет ваш файл schema.json, чтобы убедиться, что он правильно отформатирован для генерации кода.

Проверки валидации:

• Наличие обязательных разделов (table_config, entities)
• Присутствие всех обязательных полей
• Корректность типов полей (string, integer, decimal, boolean, array, object, uuid)
• Правильность значений перечислений (типы операций, типы возврата)
• Уникальность идентификаторов шаблонов среди всех сущностей
• Соответствие имён GSI между gsi_list и gsi_mappings
• Существование полей, указанных в шаблонах, среди полей сущности
• Корректность условий диапазона с правильным количеством параметров
• Наличие у шаблонов доступа допустимых операций и типов возврата

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

Файлы схемы должны находиться в текущей рабочей директории или её поддиректориях. Попытки обхода пути блокируются в целях безопасности.

Примеры вывода валидации:

Успех:

✅ Schema validation passed!

Ошибка с предложениями:

❌ Schema validation failed:
  • entities.User.fields[0].type: Invalid type value 'strng'
    💡 Did you mean 'string'? Valid options: string, integer, decimal, boolean, array, object, uuid

Генерация слоя доступа к данным

Инструмент generate_data_access_layer генерирует типобезопасный код на Python из вашего проверенного файла schema.json.

Сгенерированный код:

• Классы сущностей: Модели Pydantic с валидацией полей и типобезопасностью
• Классы репозиториев: Операции CRUD (create, read, update, delete) для каждой сущности
• Шаблоны доступа: Полностью реализованные операции запросов и сканирования из вашей схемы
• Базовый репозиторий: Общая функциональность для всех репозиториев
• Примеры использования: Образцы кода, демонстрирующие использование сгенерированных классов (опционально)
• Конфигурация: ruff.toml для качества кода и форматирования

Необходимые условия для генерации кода:

Сгенерированный код на Python требует следующих зависимостей времени выполнения:

• pydantic>=2.0 — для валидации сущностей и типобезопасности
• boto3>=1.38 — для операций с DynamoDB

Установите их в свой проект:

uv add pydantic boto3
# or
pip install pydantic boto3

Опциональные зависимости для разработки:

Для линтинга и форматирования сгенерированного кода:

• ruff==0.15.8 — линтер и форматтер Python (рекомендуется)

Структура сгенерированных файлов:

generated_dal/
├── entities.py              # Pydantic entity models
├── repositories.py          # Repository classes with CRUD operations
├── base_repository.py       # Base repository functionality
├── transaction_service.py   # Cross-table transaction methods (if schema includes cross_table_access_patterns)
├── access_pattern_mapping.json  # Pattern ID to method mapping
├── usage_examples.py        # Sample usage code (if enabled)
└── ruff.toml               # Linting configuration

Использование сгенерированного кода:

Сгенерированный код предоставляет типобезопасные классы сущностей и методы репозиториев для всех ваших шаблонов доступа:

from generated_dal.repositories import UserRepository
from generated_dal.entities import User

# Initialize repository
repo = UserRepository(table_name="MyTable")

# Create a new user
user = User(user_id="123", username="username", name="John Doe")
repo.create(user)

# Query by access pattern
users = repo.get_user_by_username(username="username")

# Update user
user.name = "Jane Doe"
repo.update(user)

Для линтинга и форматирования сгенерированного кода с помощью ruff:

ruff check generated_dal/        # Check for issues
ruff check --fix generated_dal/  # Auto-fix issues
ruff format generated_dal/       # Format code