AWS DynamoDB

officiel

L'expérience développeur officielle du serveur MCP pour Amazon DynamoDB. Ce serveur fournit des conseils d'experts en conception DynamoDB et une assistance pour la modélisation des données.

GitHub
9.4k

Documentation

Serveur MCP AWS DynamoDB

Le serveur MCP officiel d'expérience développeur pour Amazon DynamoDB. Ce serveur fournit des conseils d'expert en conception DynamoDB et une assistance à la modélisation de données.

[!IMPORTANT] L'IA générative peut commettre des erreurs. Vous devriez envisager de réviser toutes les sorties générées par le modèle d'IA et l'assistant de codage agentique que vous avez choisis. Consultez la Politique d'IA responsable d'AWS.

Outils disponibles

Le serveur MCP DynamoDB fournit huit outils pour la modélisation de données, la validation, l'analyse des coûts et la génération de code :

  • dynamodb_data_modeling - Récupère l'invite complète de l'expert en modélisation de données DynamoDB avec des patrons de conception de niveau entreprise, des stratégies d'optimisation des coûts et la philosophie de conception multi-tables. Guide à travers la collecte des exigences, l'analyse des patrons d'accès et la conception du schéma.

    Exemple d'invocation : « Concevoir un modèle de données pour mon application e-commerce en utilisant le serveur MCP de modélisation de données DynamoDB »

  • dynamodb_data_model_validation - Valide votre modèle de données DynamoDB en chargeant dynamodb_data_model.json, en configurant DynamoDB Local, en créant des tables avec des données de test et en exécutant tous les patrons d'accès définis. Enregistre les résultats de validation détaillés dans dynamodb_model_validation.json.

    Exemple d'invocation : « Valider mon modèle de données DynamoDB »

  • source_db_analyzer - Analyse les bases de données existantes (MySQL, PostgreSQL, SQL Server, Oracle) pour extraire la structure du schéma, les patrons d'accès et génère des fichiers d'analyse horodatés à utiliser avec dynamodb_data_modeling. Prend en charge à la fois l'accès basé sur l'API RDS Data et l'accès basé sur la connexion pour MySQL.

    Exemple d'invocation : « Analyser ma base de données MySQL et m'aider à concevoir un modèle de données DynamoDB »

  • generate_resources - Génère diverses ressources à partir du fichier JSON du modèle de données DynamoDB (dynamodb_data_model.json). Actuellement, seul le type de ressource cdk est pris en charge. Passer cdk comme paramètre resource_type génère une application CDK pour déployer les tables DynamoDB. L'application CDK lit le fichier dynamodb_data_model.json pour créer les tables avec la configuration appropriée.

    Exemple d'invocation : « Générer les ressources pour déployer mon modèle de données DynamoDB en utilisant CDK »

  • dynamodb_data_model_schema_converter - Convertit votre modèle de données (dynamodb_data_model.md) en un fichier schema.json structuré représentant vos tables DynamoDB, index, entités, champs et patrons d'accès. Ce format lisible par machine est utilisé pour la génération de code et peut être étendu à d'autres fins comme la génération de documentation ou le provisionnement d'infrastructure. Valide automatiquement le schéma avec jusqu'à 8 itérations pour garantir l'exactitude.

    Exemple d'invocation : « Convertir mon modèle de données en schema.json pour la génération de code »

  • dynamodb_data_model_schema_validator - Valide les fichiers schema.json pour la compatibilité avec la génération de code. Vérifie les types de champs, les opérations, les mappages GSI, les identifiants de patron et fournit des messages d'erreur détaillés avec des suggestions de correction. S'assure que votre schéma est prêt pour l'outil generate_data_access_layer.

    Exemple d'invocation : « Valider mon fichier schema.json situé dans /chemin/vers/schema.json »

  • generate_data_access_layer - Génère du code Python typé à partir de schema.json, incluant des classes d'entité avec validation des champs, des classes de dépôt avec opérations CRUD, des patrons d'accès entièrement implémentés et des exemples d'utilisation optionnels. Le code généré utilise Pydantic pour la validation et boto3 pour les opérations DynamoDB.

    Exemple d'invocation : « Générer du code Python à partir de mon schema.json »

  • compute_performances_and_costs - Calcule les unités de capacité DynamoDB (RCU/WCU) et les coûts mensuels à partir des patrons d'accès. Analyse toutes les opérations DynamoDB (GetItem, Query, Scan, PutItem, UpdateItem, DeleteItem, BatchGetItem, BatchWriteItem, TransactGetItems, TransactWriteItems), suit les écritures supplémentaires des GSI et calcule les coûts de stockage. Ajoute un rapport de coûts complet à dynamodb_data_model.md.

    Exemple d'invocation : « Calculer le coût et les performances de mon modèle de données DynamoDB »

Prérequis

  1. Installer uv depuis Astral ou le README GitHub
  2. Installer Python en utilisant uv python install 3.10
  3. Configurer les informations d'identification AWS avec accès aux services AWS

Installation

KiroCursorVS Code
KiroCursorVS Code

Remarque : Les boutons d'installation ci-dessus configurent AWS_REGION sur us-west-2 par défaut. Mettez à jour cette valeur dans votre configuration MCP après l'installation si vous avez besoin d'une région différente.

Ajoutez le serveur MCP à votre fichier de configuration (pour Kiro, ajoutez à .kiro/settings/mcp.json - voir le chemin de configuration) :

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

Installation Windows

Pour les utilisateurs Windows, le format de configuration du serveur MCP est légèrement différent :

{
  "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"
      }
    }
  }
}

Installation Docker

Après un docker build -t awslabs/dynamodb-mcp-server . réussi :

{
  "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": []
    }
  }
}

Modélisation de données

Modélisation de données en langage naturel

Utilisez l'outil dynamodb_data_modeling pour concevoir des modèles de données DynamoDB via une conversation en langage naturel avec votre agent IA. Demandez simplement : « utiliser mon MCP DynamoDB pour m'aider à concevoir un modèle de données DynamoDB. »

L'outil fournit un flux de travail structuré qui traduit les exigences applicatives en modèles de données DynamoDB :

Phase de collecte des exigences :

  • Capture les patrons d'accès via une conversation en langage naturel
  • Documente les entités, les relations et les patrons de lecture/écriture
  • Enregistre les requêtes estimées par seconde (RPS) pour chaque patron
  • Crée le fichier dynamodb_requirements.md qui se met à jour en temps réel
  • Identifie les patrons mieux adaptés à d'autres services AWS (OpenSearch pour la recherche textuelle, Redshift pour l'analytique)
  • Signale les considérations de conception spéciales (par exemple, les patrons de diffusion massive nécessitant DynamoDB Streams et Lambda)

Phase de conception :

  • Génère des conceptions optimisées de tables et d'index
  • Crée dynamodb_data_model.md avec une justification détaillée de la conception
  • Fournit une estimation des coûts mensuels
  • Documente comment chaque patron d'accès est pris en charge
  • Inclut des recommandations d'optimisation pour la mise à l'échelle et les performances

L'outil s'appuie sur un contexte conçu par des experts qui aide les modèles de raisonnement à vous guider à travers des techniques de modélisation avancées. Les meilleurs résultats sont obtenus avec des modèles capables de raisonnement tels qu'Anthropic Claude 4/4.5 Sonnet, OpenAI o3 et Google Gemini 2.5.

Validation du modèle de données

Prérequis pour la validation du modèle de données : Pour utiliser l'outil de validation du modèle de données, vous avez besoin de l'un des éléments suivants :

  • Environnement d'exécution de conteneurs : Docker, Podman, Finch ou nerdctl avec un démon en cours d'exécution
  • Environnement d'exécution Java : Java JRE version 17 ou plus récente (définissez JAVA_HOME ou assurez-vous que java est dans votre PATH système)

Après avoir terminé la conception de votre modèle de données, utilisez l'outil dynamodb_data_model_validation pour tester automatiquement votre modèle de données par rapport à DynamoDB Local. L'outil de validation boucle la boucle entre la génération et l'exécution en créant un cycle de validation itératif.

Fonctionnement :

L'outil automatise le processus de validation manuelle traditionnel :

  1. Configuration : Démarre l'environnement DynamoDB Local (Docker/Podman/Finch/nerdctl ou solution de repli Java)
  2. Générer la spécification de test : Crée dynamodb_data_model.json listant les tables, les données d'exemple et les patrons d'accès à tester
  3. Déployer le schéma : Crée les tables, les index et insère les données d'exemple localement
  4. Exécuter les tests : Exécute toutes les opérations de lecture et d'écriture définies dans vos patrons d'accès
  5. Valider les résultats : Vérifie que chaque patron d'accès se comporte correctement et efficacement
  6. Raffinement itératif : Si la validation échoue (par exemple, une requête retourne des résultats incomplets en raison d'une clé de partition mal alignée), l'outil enregistre le problème, régénère le schéma affecté et réexécute les tests jusqu'à ce que tous les patrons réussissent

Sortie de validation :

  • dynamodb_model_validation.json : Résultats de validation détaillés avec les réponses des patrons
  • validation_result.md : Résumé du processus de validation avec le statut de réussite/échec pour chaque patron d'accès
  • Identifie les problèmes tels que les structures de clés incorrectes, les index manquants ou les patrons de requête inefficaces

Analyse de la base de données source

L'outil source_db_analyzer extrait le schéma et les patrons d'accès de votre base de données existante pour vous aider à concevoir votre modèle DynamoDB. Ceci est utile lors de la migration depuis des bases de données relationnelles.

L'outil prend en charge deux méthodes de connexion pour MySQL :

  • Accès basé sur l'API RDS Data : Connexion sans serveur utilisant l'ARN du cluster
  • Accès basé sur la connexion : Connexion traditionnelle utilisant le nom d'hôte/port

Bases de données prises en charge :

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

Modes d'exécution :

  • Mode libre-service : Générer des requêtes SQL, les exécuter vous-même, fournir les résultats (MySQL, PostgreSQL, SQL Server, Oracle)
  • Mode géré : Connexion directe via l'API AWS RDS Data (MySQL uniquement)

Nous recommandons d'exécuter cet outil sur une instance de base de données hors production.

Mode libre-service (MySQL, PostgreSQL, SQL Server, Oracle)

Le mode libre-service vous permet d'analyser n'importe quelle base de données sans connectivité AWS :

  1. Générer des requêtes : L'outil écrit les requêtes SQL (basées sur la base de données sélectionnée) dans un fichier
  2. Exécuter les requêtes : Vous exécutez les requêtes sur votre base de données
  3. Fournir les résultats : L'outil analyse les résultats et génère l'analyse

Mode géré (MySQL uniquement)

Le mode géré vous permet de connecter l'outil à l'API AWS RDS Data pour analyser les bases de données MySQL/Aurora existantes afin d'extraire le schéma et les patrons d'accès pour la modélisation DynamoDB.

Prérequis pour l'intégration MySQL (Mode géré)

Pour l'accès basé sur l'API RDS Data :

  1. Cluster MySQL avec l'API RDS Data activée
  2. Informations d'identification de la base de données stockées dans AWS Secrets Manager
  3. Informations d'identification AWS avec les autorisations d'accès à l'API RDS Data et à Secrets Manager

Pour l'accès basé sur la connexion :

  1. Serveur MySQL accessible depuis votre environnement

  2. Informations d'identification de la base de données stockées dans AWS Secrets Manager

  3. Le secret Secrets Manager doit contenir un champ host correspondant au nom d'hôte de votre base de données (en plus de username et password). Cela garantit que les informations d'identification ne sont utilisées qu'avec l'hôte de base de données prévu. Les secrets gérés par RDS incluent ce champ automatiquement. Si vous avez créé votre secret manuellement, assurez-vous qu'il suit la structure standard :

    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. Informations d'identification AWS avec les autorisations d'accès à Secrets Manager

Pour les deux méthodes de connexion : 4. Activer le schéma de performance pour l'analyse des patrons d'accès (optionnel mais recommandé) :

  • Définissez le paramètre performance_schema à 1 dans votre groupe de paramètres DB
  • Redémarrez l'instance DB après les modifications
  • Vérifiez avec : SHOW GLOBAL VARIABLES LIKE '%performance_schema'
  • Envisagez d'ajuster :
    • performance_schema_digests_size - Nombre maximum de lignes dans events_statements_summary_by_digest
    • performance_schema_max_digest_length - Longueur maximale en octets par résumé de déclaration (par défaut : 1024)
  • Sans le schéma de performance, l'analyse est basée uniquement sur le schéma d'information

Variables d'environnement MySQL

Ajoutez ces variables d'environnement pour activer l'intégration MySQL :

Pour l'accès basé sur l'API RDS Data :

  • MYSQL_CLUSTER_ARN : ARN du cluster MySQL
  • MYSQL_SECRET_ARN : ARN du secret contenant les informations d'identification de la base de données
  • MYSQL_DATABASE : Nom de la base de données à analyser
  • AWS_REGION : Région AWS du cluster

Pour l'accès basé sur la connexion :

  • MYSQL_HOSTNAME : Nom d'hôte ou point de terminaison du serveur MySQL
  • MYSQL_PORT : Port du serveur MySQL (optionnel, par défaut : 3306)
  • MYSQL_SECRET_ARN : ARN du secret contenant les informations d'identification de la base de données
  • MYSQL_DATABASE : Nom de la base de données à analyser
  • AWS_REGION : Région AWS où se trouve Secrets Manager

Options communes :

  • MYSQL_MAX_QUERY_RESULTS : Nombre maximum de lignes dans les fichiers de sortie d'analyse (optionnel, par défaut : 500)

Remarque : Les paramètres explicites de l'outil prennent le pas sur les variables d'environnement. Une seule méthode de connexion (ARN du cluster ou nom d'hôte) doit être spécifiée.

Configuration MCP avec MySQL

Pour l'accès basé sur l'API RDS Data :

{
  "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": []
    }
  }
}

Pour l'accès basé sur la connexion :

{
  "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": []
    }
  }
}

Utilisation de l'analyse de la base de données source

  1. Exécutez source_db_analyzer sur votre base de données (mode Libre-service ou Géré)
  2. Consultez le dossier d'analyse horodaté généré (database_analysis_YYYYMMDD_HHMMSS)
  3. Lisez d'abord le fichier manifest.md - il répertorie tous les fichiers d'analyse et les statistiques
  4. Lisez tous les fichiers d'analyse pour comprendre la structure du schéma et les modèles d'accès
  5. Utilisez l'analyse avec dynamodb_data_modeling pour concevoir votre schéma DynamoDB

L'outil génère des fichiers Markdown avec :

  • La structure du schéma (tables, colonnes, index, clés étrangères)
  • Les modèles d'accès issus du Schéma de Performance (modèles de requêtes, RPS, fréquences)
  • Une analyse horodatée pour suivre les évolutions dans le temps

Conversion de schéma et génération de code

Après avoir conçu votre modèle de données DynamoDB, vous pouvez le convertir en un schéma structuré et générer du code Python de référence. Lors de l'utilisation des outils MCP via un LLM, ce flux de travail complet se déroule automatiquement - le LLM vous guide à travers la conversion du schéma, la validation et la génération de code en une seule conversation, sans nécessiter d'invocation manuelle des outils.

Pour une utilisation autonome, vous pouvez également invoquer ces outils directement via la CLI ou modifier manuellement les fichiers schema.json et régénérer le code selon vos besoins.

Remarque : La validation du modèle de données (dynamodb_data_model_validation) est facultative pour la génération de code. Cependant, si vous prévoyez de tester le code généré avec usage_examples.py sur DynamoDB Local, il est recommandé d'exécuter d'abord la validation, car elle configure automatiquement les tables et les données de test dans DynamoDB Local.

Conversion du modèle de données en schéma

L'outil dynamodb_data_model_schema_converter convertit votre modèle de données lisible par l'humain (dynamodb_data_model.md) en un schéma JSON structuré représentant vos tables DynamoDB, index, entités et modèles d'accès. Ce format lisible par machine permet la génération de code et peut être étendu pour la documentation ou le provisionnement d'infrastructure.

L'outil valide automatiquement le schéma généré, en fournissant des messages d'erreur détaillés et des suggestions de correction en cas d'échec de validation. La sortie est enregistrée dans un dossier horodaté pour l'isolation.

Structure du schéma :

Le fichier schema.json généré est une représentation structurée contenant :

  • Tables : Une ou plusieurs définitions de tables DynamoDB avec clés de partition/tri
  • Définitions GSI : Configurations d'index secondaires globaux (facultatif)
  • Entités : Modèles de domaine (Utilisateur, Commande, Produit, etc.) avec champs typés
  • Types de champs : string, integer, decimal, boolean, array, object, uuid
  • Modèles d'accès : Opérations Query/Scan/GetItem avec définitions de paramètres et modèles de clés
  • Modèles de clés : Modèles pour générer les clés de partition et de tri (par exemple, USER#{user_id})

Ce format structuré sert d'entrée pour les outils de génération de code.

Validation des fichiers de schéma

L'outil dynamodb_data_model_schema_validator valide votre fichier schema.json pour s'assurer qu'il est correctement formaté pour la génération de code.

Contrôles de validation :

  • Les sections requises (table_config, entities) existent
  • Tous les champs obligatoires sont présents
  • Les types de champs sont valides (string, integer, decimal, boolean, array, object, uuid)
  • Les valeurs d'énumération sont correctes (types d'opération, types de retour)
  • Les identifiants de modèle sont uniques parmi toutes les entités
  • Les noms GSI correspondent entre gsi_list et gsi_mappings
  • Les champs référencés dans les modèles existent dans les champs d'entité
  • Les conditions de plage sont valides avec un nombre correct de paramètres
  • Les modèles d'accès ont des opérations et des types de retour valides

Sécurité :

Les fichiers de schéma doivent se trouver dans le répertoire de travail actuel ou ses sous-répertoires. Les tentatives de traversée de chemin sont bloquées pour des raisons de sécurité.

Exemples de sortie de validation :

Succès :

✅ Schema validation passed!

Erreur avec suggestions :

❌ 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

Génération de la couche d'accès aux données

L'outil generate_data_access_layer génère du code Python type-safe à partir de votre fichier schema.json validé.

Code généré :

  • Classes d'entité : Modèles Pydantic avec validation des champs et sécurité de type
  • Classes de dépôt : Opérations CRUD (créer, lire, mettre à jour, supprimer) pour chaque entité
  • Modèles d'accès : Opérations de requête et d'analyse entièrement implémentées à partir de votre schéma
  • Dépôt de base : Fonctionnalités partagées pour tous les dépôts
  • Exemples d'utilisation : Exemple de code montrant comment utiliser les classes générées (facultatif)
  • Configuration : ruff.toml pour la qualité et le formatage du code

Prérequis pour la génération de code :

Le code Python généré nécessite ces dépendances d'exécution :

  • pydantic>=2.0 - Pour la validation des entités et la sécurité de type
  • boto3>=1.38 - Pour les opérations DynamoDB

Installez-les dans votre projet :

uv add pydantic boto3
# or
pip install pydantic boto3

Dépendances de développement facultatives :

Pour le linting et le formatage du code généré :

  • ruff==0.15.8 - Linter et formateur Python (recommandé)

Structure des fichiers générés :

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

Utilisation du code généré :

Le code généré fournit des classes d'entité type-safe et des méthodes de dépôt pour tous vos modèles d'accès :

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)

Pour le linting et le formatage du code généré avec ruff :

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