Servidor MCP para Banco de Dados Relacional

O gerador connection conecta um Servidor MCP TypeScript a um projeto de Banco de Dados Relacional, disponibilizando um cliente Prisma para todas as ferramentas registradas dentro de createServer.

Pré-requisitos

Antes de usar este gerador, certifique-se de ter:

1. Um projeto ts#mcp-server
2. Um projeto ts#rdb

Uso

Executar o Gerador

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - connection
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

pnpm

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

yarn

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

npm

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

bun

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

Selecione seu projeto de servidor MCP como origem e seu projeto de banco de dados relacional como destino. Se o projeto contiver múltiplos componentes de servidor MCP, especifique sourceComponent para desambiguar.

Opções

Parâmetro	Tipo	Padrão	Descrição
sourceProject Obrigatório	string	-	O projeto de origem
targetProject Obrigatório	string	-	O projeto de destino para conectar
sourceComponent	string	-	O componente de origem para conectar (nome do componente, caminho relativo à raiz do projeto de origem, ou id do gerador). Use '.' para selecionar explicitamente o projeto como origem.
targetComponent	string	-	O componente de destino para conectar (nome do componente, caminho relativo à raiz do projeto de destino, ou id do gerador). Use '.' para selecionar explicitamente o projeto como destino.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que os geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

O gerador modifica dois arquivos no diretório de origem do seu servidor MCP:

• Directorypackages/my-service/src/my-mcp

  • server.ts Cliente Prisma buscado e disponível para todas as ferramentas registradas dentro de createServer
  • Dockerfile Pacote CA do RDS instalado para conexões SSL com Aurora

Além disso, o target <mcp-server-name>-dev é atualizado para depender do target dev do banco de dados.

Usando o Banco de Dados em Ferramentas MCP

O cliente Prisma é buscado dentro de createServer e disponível para todas as ferramentas e recursos registrados lá:

packages/my-service/src/my-mcp/server.ts

import { getPrisma as getMyDb } from ':my-scope/my-db';

export const createServer = async () => {
  const myDb = await getMyDb();
  const server = new McpServer({ name: 'my-service', version: '1.0.0' });
  // register tools/resources that use myDb
  return server;
};

Múltiplos Bancos de Dados

Executar o gerador novamente com um destino diferente adiciona o segundo banco de dados junto ao primeiro. Ambos são buscados dentro de createServer:

packages/my-service/src/my-mcp/server.ts

export const createServer = async () => {
  const postgresDb = await getPostgresDb();
  const mysqlDb = await getMysqlDb();
  const server = new McpServer({ ... });
  // register tools using both clients
  return server;
};

Infraestrutura

O construtor do servidor MCP gerado implementa IGrantable e IConnectable, então você pode conceder acesso de rede e IAM ao banco de dados diretamente no construtor.

CDK

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

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 abre a regra do grupo de segurança para que o runtime do servidor MCP possa alcançar a porta do banco de dados. grantConnect concede a permissão IAM rds-db:connect ao papel de execução do servidor.

Terraform

Execute o servidor MCP dentro da mesma VPC que o banco de dados, conceda a ele rds-db:connect via additional_iam_policy_statements, e abra o caminho de rede com um par de regras de grupo de segurança:

packages/infra/src/main.tf

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 vêm da configuração de runtime compartilhada da aplicação AppConfig declarada uma vez no seu módulo raiz, não do módulo do banco de dados.

Requisitos SSL ao Conectar Sem RDS Proxy

O gerador de conexão atualiza o Dockerfile para instalar o pacote de CA do Amazon RDS em /usr/local/share/ca-certificates/rds-bundle.crt. Defina NODE_EXTRA_CA_CERTS para esse caminho para que o Node.js confie no certificado ao conectar sem RDS Proxy:

CDK

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

new MyMcpServer(this, 'MyMcpServer', {
  ...
  environmentVariables: {
    NODE_EXTRA_CA_CERTS: '/usr/local/share/ca-certificates/rds-bundle.crt',
  },
});

Terraform

packages/infra/src/main.tf

module "my_mcp_server" {
  ...
  environment_variables = {
    NODE_EXTRA_CA_CERTS = "/usr/local/share/ca-certificates/rds-bundle.crt"
  }
}

Para mais detalhes, consulte a documentação SSL/TLS do Amazon RDS. Ao usar RDS Proxy, você não precisa configurar NODE_EXTRA_CA_CERTS.

Desenvolvimento Local

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>

Isso inicia o servidor MCP e todos os bancos de dados conectados. A variável de ambiente LOCAL_DEV=true faz com que cada cliente Prisma se conecte ao seu banco de dados Docker local em vez do Aurora.