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:

1. Un progetto py#mcp-server
2. Un progetto py#rdb

Utilizzo

Esegui il Generatore

Esegui questo generatore@aws/nx-plugin:connection

CLI

pnpm

$ pnpm nx g @aws/nx-plugin:connection

yarn

$ yarn nx g @aws/nx-plugin:connection

npm

$ npx nx g @aws/nx-plugin:connection

bun

$ bunx nx g @aws/nx-plugin:connection

VSCode

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

Componi il tuo comando5

sourceProjectObbligatorio

targetProjectObbligatorio

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runPuoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Opzioni del generatore5 opzioni

sourceProjectObbligatoriostring

Il progetto sorgente

targetProjectObbligatoriostring

Il progetto di destinazione a cui connettersi

sourceComponentstring

Il componente sorgente da cui connettersi (nome del componente, percorso relativo alla radice del progetto sorgente, o id del generatore). Usa '.' per selezionare esplicitamente il progetto come sorgente.

targetComponentstring

Il componente destinazione a cui connettersi (nome del componente, percorso relativo alla radice del progetto destinazione, o id del generatore). Usa '.' per selezionare esplicitamente il progetto come destinazione.

preferInstallDependenciesbooleanPredefinito: 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 (solo quando l’infra dell’MCP server è agentcore-ecr)

Utilizzo del Database negli Strumenti MCP

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

packages/my_service/my_service/my_mcp_server/server.py

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))).scalars().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:

packages/my_service/my_service/my_mcp_server/server.py

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

packages/infra/src/stacks/application-stack.ts

import { SecurityGroup } from 'aws-cdk-lib/aws-ec2';
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 },
    securityGroups: [
      new SecurityGroup(this, 'MyMcpServerSecurityGroup', { vpc, allowAllOutbound: true }),
    ],
  }),
});

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

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

Terraform

Esegui l’MCP server all’interno dello stesso VPC del database, concedigli rds-db:connect tramite additional_iam_policy_statements e apri il percorso di rete con una coppia di regole di security group. Le risorse aws_vpc.main e aws_subnet sono definite nella guida di deployment del database:

packages/infra/src/main.tf

module "my_database" {
  source              = "../../common/terraform/src/app/dbs/my-database"
  vpc_id              = aws_vpc.main.id
  database_subnet_ids = aws_subnet.database[*].id
  lambda_subnet_ids   = aws_subnet.private[*].id
}

module "my_mcp_server" {
  source     = "../../common/terraform/src/app/mcp-servers/my-mcp-server"
  enable_vpc = true
  vpc_id     = aws_vpc.main.id
  subnet_ids = aws_subnet.private[*].id

  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" {
  description                  = "Allow the MCP server runtime to connect to the 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" {
  description                  = "Allow outbound traffic from the MCP server runtime to the 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. Tale applicazione espone il namespace database per impostazione predefinita, quindi l’entry di configurazione runtime del modulo del database viene distribuita senza ulteriori configurazioni.

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 dell’MCP server generato per installare il bundle CA Amazon RDS nel trust store del 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

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

yarn

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

npm

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

bun

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.