Server MCP a Database Relazionale

Il generatore connection collega un Server MCP TypeScript a un progetto Database Relazionale, rendendo disponibile un client Prisma all’interno di createServer e dei suoi punti di ingresso di trasporto.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

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

Utilizzo

Eseguire il Generatore

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

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Seleziona il tuo progetto server MCP come sorgente e il tuo progetto database relazionale come destinazione. Se il progetto contiene più componenti server MCP, 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.

Output del Generatore

Il generatore modifica tre file nella directory sorgente del tuo server MCP:

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

  • server.ts createServer aggiornato per accettare il parametro { db }
  • http.ts Client Prisma creato sopra const server = createServer({ db })
  • stdio.ts Client Prisma creato prima di await createServer({ db }).connect(transport)

Inoltre, il target <mcp-server-name>-serve-local viene aggiornato per dipendere dal target serve-local del database.

Come Funziona

Definizione del Server

createServer riceve il client Prisma come parametro in modo da rimanere sincrono e poter passare il client a strumenti e risorse:

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;
};

Trasporto HTTP

Il client Prisma viene creato all’interno del gestore delle richieste, sopra la chiamata a 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 });
    // ...
  }
});

Trasporto Stdio

Lo stesso schema si applica al punto di ingresso del trasporto 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);
};

Database Multipli

Eseguire nuovamente il generatore con una destinazione diversa aggiunge il secondo database accanto al primo. Entrambi vengono passati a createServer insieme:

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

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

Infrastruttura

Il costrutto del server MCP 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 { 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 apre la regola del security group in modo che il runtime del server MCP possa raggiungere la porta del database. grantConnect concede il permesso IAM rds-db:connect al ruolo di esecuzione del server.

Terraform

Passa gli output del modulo database nel tuo modulo server MCP in modo che possa raggiungere il database e leggere la sua configurazione di 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
}

Assicurati che il ruolo di esecuzione del server MCP abbia il permesso rds-db:connect e che il suo security group possa raggiungere il security group del database sulla porta del database.

Sviluppo Locale

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>

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