Python MCP Server a Database Relazionale

Il generatore connection collega un Python MCP Server a un progetto Python Relational Database, rendendo la sessione del database disponibile a tutti gli strumenti registrati nel server.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

Un progetto py#mcp-server
Un progetto py#rdb

Utilizzo

Installa il Nx Console VSCode Plugin se non l'hai già fatto
Apri la console Nx in VSCode
Clicca su Generate (UI) nella sezione "Common Nx Commands"
Cerca @aws/nx-plugin - connection
Compila i parametri richiesti
Clicca su Generate

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn nx g @aws/nx-plugin:connection --dry-run

npx nx g @aws/nx-plugin:connection --dry-run

bunx nx g @aws/nx-plugin:connection --dry-run

Seleziona il tuo progetto MCP server come sorgente e il tuo progetto database relazionale come destinazione. Se il progetto contiene più componenti MCP server, specifica sourceComponent per disambiguare.

Opzioni

Parametro	Tipo	Predefinito	Descrizione
sourceProject Obbligatorio	string	-	Il progetto sorgente
targetProject Obbligatorio	string	-	Il progetto di destinazione a cui connettersi
sourceComponent	string	-	Il componente sorgente da cui connettersi (nome del componente, percorso relativo alla radice del progetto sorgente, o id del generatore). Usare '.' per selezionare esplicitamente il progetto come sorgente.
targetComponent	string	-	Il componente di destinazione a cui connettersi (nome del componente, percorso relativo alla radice del progetto di destinazione, o id del generatore). Usare '.' per selezionare esplicitamente il progetto come destinazione.
preferInstallDependencies	boolean	true	Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

Directorypackages/my_service
- project.json Aggiunge una dipendenza da my_mcp_server-dev al target dev del database
- pyproject.toml Aggiunge il pacchetto del database come dipendenza del workspace
- Directorymy_service
  - Directorymy_mcp_server
    Dockerfile Aggiunge il bundle CA RDS utilizzato per le connessioni dirette ad Aurora

Utilizzo del Database negli Strumenti MCP

Importa session_context dal tuo pacchetto del database e utilizzalo all’interno dei tuoi strumenti MCP server:

from sqlmodel import select
from my_scope.my_db import session_context
from my_scope.my_db.models.example import ExampleModel

@mcp.tool()
async def list_examples() -> str:
    """List all example records."""
    async with session_context() as session:
        items = (await session.execute(select(ExampleModel))).all()
        return str([item.model_dump() for item in items])

Database Multipli

Eseguire nuovamente il generatore con una destinazione diversa aggiunge il secondo database accanto al primo. Entrambi i contesti di sessione sono disponibili per tutti gli strumenti:

from my_scope.my_db import session_context as my_db_session_context
from my_scope.other_db import session_context as other_db_session_context

Infrastruttura

Il costrutto MCP server generato implementa IGrantable e IConnectable, quindi puoi concedere l’accesso di rete e IAM al database direttamente sul costrutto.

CDK
Terraform

import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';
import { MyDatabase } from ':my-scope/common-constructs';

const db = new MyDatabase(this, 'Db', { vpc, ... });

const myMcpServer = new MyMcpServer(this, 'MyMcpServer', {
  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(this, {
    vpc,
    vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
  }),
});

db.allowDefaultPortFrom(myMcpServer);
db.grantConnect(myMcpServer);

allowDefaultPortFrom apre la regola del security group in modo che il runtime dell’MCP server possa raggiungere la porta del database. grantConnect concede il permesso IAM rds-db:connect al ruolo di esecuzione del server.

Esegui l’MCP server all’interno della stessa VPC del database, concedigli rds-db:connect tramite additional_iam_policy_statements e apri il percorso di rete con una coppia di regole del security group:

module "my_database" {
  source              = "../../common/terraform/src/app/dbs/my-database"
  vpc_id              = module.vpc.vpc_id
  database_subnet_ids = module.vpc.private_isolated_subnet_ids
  lambda_subnet_ids   = module.vpc.private_subnet_ids
}

module "my_mcp_server" {
  source     = "../../common/terraform/src/app/mcp-servers/my-mcp-server"
  enable_vpc = true
  vpc_id     = module.vpc.vpc_id
  subnet_ids = module.vpc.private_subnet_ids

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = ["rds-db:connect"]
      Resource = [
        "arn:aws:rds-db:${data.aws_region.current.region}:${data.aws_caller_identity.current.account_id}:dbuser:${module.my_database.connect_resource_id}/${module.my_database.database_runtime_user}"
      ]
    }
  ]
}

resource "aws_vpc_security_group_ingress_rule" "mcp_server_to_database" {
  security_group_id            = module.my_database.security_group_id
  referenced_security_group_id = module.my_mcp_server.security_group_id
  from_port                    = module.my_database.cluster_port
  to_port                      = module.my_database.cluster_port
  ip_protocol                  = "tcp"
}

resource "aws_vpc_security_group_egress_rule" "mcp_server_to_database" {
  security_group_id            = module.my_mcp_server.security_group_id
  referenced_security_group_id = module.my_database.security_group_id
  from_port                    = module.my_database.cluster_port
  to_port                      = module.my_database.cluster_port
  ip_protocol                  = "tcp"
}

appconfig_application_id/appconfig_application_arn provengono dall’applicazione AppConfig di configurazione runtime condivisa dichiarata una volta nel tuo modulo root, non dal modulo del database.

Requisiti SSL per la Connessione Senza RDS Proxy

Quando l’MCP server si connette direttamente al cluster Aurora (senza RDS Proxy), il generatore di connessione aggiorna il Dockerfile generato dell’MCP server per installare il bundle CA Amazon RDS nel trust store di sistema:

ADD https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem /usr/local/share/ca-certificates/rds-global-bundle.crt
RUN update-ca-certificates

Quando si utilizza RDS Proxy, non è necessario configurare il bundle CA RDS nel runtime dell’MCP server.

Sviluppo Locale

pnpm nx <mcp-server-name>-dev <project-name>

yarn nx <mcp-server-name>-dev <project-name>

npx nx <mcp-server-name>-dev <project-name>

bunx nx <mcp-server-name>-dev <project-name>

Questo avvia l’MCP server e tutti i database connessi. La variabile d’ambiente LOCAL_DEV=true fa sì che il client del database si connetta al suo database Docker locale invece che ad Aurora.