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 dentro de createServer e seus pontos de entrada de transporte.

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.

Saída do Gerador

O gerador modifica três arquivos no diretório de origem do seu servidor MCP:

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

  • server.ts createServer atualizado para aceitar o parâmetro { db }
  • http.ts Cliente Prisma criado acima de const server = createServer({ db })
  • stdio.ts Cliente Prisma criado antes de await createServer({ db }).connect(transport)

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

Como Funciona

Definição do Servidor

createServer recebe o cliente Prisma como parâmetro para que permaneça síncrono e possa passar o cliente para ferramentas e recursos:

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

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

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

Transporte HTTP

O cliente Prisma é criado dentro do manipulador de requisição, acima da chamada createServer:

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

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

app.post('/mcp', async (req, res) => {
  try {
    const myDb = await getMyDb();
    const server = createServer({ myDb });
    // ...
  }
});

Transporte Stdio

O mesmo padrão se aplica ao ponto de entrada do transporte stdio:

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

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

export const startMcpServer = async () => {
  const transport = new StdioServerTransport();
  const myDb = await getMyDb();
  await createServer({ myDb }).connect(transport);
};

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 passados para createServer juntos:

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

const postgresDb = await getPostgresDb();
const mySqlDb = await getMySqlDb();
const server = createServer({ postgresDb, mysqlDb });

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 { MyDatabase } from ':my-scope/common-constructs';

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

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

Passe as saídas do módulo do banco de dados para o módulo do seu servidor MCP para que ele possa alcançar o banco de dados e ler sua configuração de runtime:

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
}

module "my_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-mcp-server"

  appconfig_application_id     = module.my_database.appconfig_application_id
  database_cluster_resource_id = module.my_database.cluster_resource_id
  database_runtime_user        = module.my_database.database_runtime_user
  database_security_group_id   = module.my_database.security_group_id
  database_port                = module.my_database.cluster_port
}

Certifique-se de que o papel de execução do servidor MCP tenha a permissão rds-db:connect e que seu grupo de segurança possa alcançar o grupo de segurança do banco de dados na porta do banco de dados.

Desenvolvimento Local

pnpm

pnpm nx <mcp-server-name>-serve-local <project-name>

yarn

yarn nx <mcp-server-name>-serve-local <project-name>

npm

npx nx <mcp-server-name>-serve-local <project-name>

bun

bunx nx <mcp-server-name>-serve-local <project-name>

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