@aws/nx-plugin-mcp 1.0.0-rc.33 → 1.0.0-rc.35

package/bin/aws-nx-mcp.js

@@ -20204,6 +20204,33 @@ var generators$1 = {
 		"description": "Connect a py#mcp-server to a py#dynamodb project",
 		"metric": "g55",
 		"hidden": true
+	},
+	"py#rdb": {
+		"factory": "./src/py/rdb/generator",
+		"schema": "./src/py/rdb/schema.json",
+		"description": "Create a Python relational database project",
+		"metric": "g56"
+	},
+	"py#rdb#fast-api-connection": {
+		"factory": "./src/py/rdb/fast-api-connection/generator",
+		"schema": "./src/py/rdb/fast-api-connection/schema.json",
+		"description": "Connect a py#fast-api project to a py#rdb project",
+		"metric": "g57",
+		"hidden": true
+	},
+	"py#rdb#agent-connection": {
+		"factory": "./src/py/rdb/agent-connection/generator",
+		"schema": "./src/py/rdb/agent-connection/schema.json",
+		"description": "Connect a py#agent to a py#rdb project",
+		"metric": "g58",
+		"hidden": true
+	},
+	"py#rdb#mcp-server-connection": {
+		"factory": "./src/py/rdb/mcp-server-connection/generator",
+		"schema": "./src/py/rdb/mcp-server-connection/schema.json",
+		"description": "Connect a py#mcp-server to a py#rdb project",
+		"metric": "g59",
+		"hidden": true
 	}
 };
 //#endregion

package/docs/guides/connection/py-agent-rdb.mdx

@@ -0,0 +1,178 @@
+---
+title: Python Agent to Relational Database
+description: Connect a Python Agent to a Relational Database
+when:
+  sourceType: py#agent
+  targetType: py#rdb
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Infrastructure from '@components/infrastructure.astro';
+
+The `connection` generator wires a <Link path="guides/py-agent">Python Agent</Link> to a <Link path="guides/py-rdb">Python Relational Database</Link> project, making the database session available inside your agent tools.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/py-agent">`py#agent`</Link> project
+2. A <Link path="guides/py-rdb">`py#rdb`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your Agent project as the source and your relational database project as the target. If the project contains multiple agent components, specify `sourceComponent` to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+<FileTree>
+
+- packages/my\_service
+  - project.json Adds a dependency from `my_agent-dev` on the database's `dev` target
+  - pyproject.toml Adds the database package as a workspace dependency
+  - my\_service
+    - my\_agent
+      - Dockerfile Adds the RDS CA bundle used for direct Aurora connections
+
+</FileTree>
+
+## Using the Database in Agent Tools
+
+Import `session_context` from your database package and use it inside your agent tools:
+
+```python title="packages/my_service/my_service/my_agent/agent.py"
+from sqlmodel import select
+from my_scope.my_db import session_context
+from my_scope.my_db.models.example import ExampleModel
+from strands import tool
+
+@tool
+async def list_examples() -> list:
+    """List all example records."""
+    async with session_context() as session:
+        return [item.model_dump() for item in (await session.execute(select(ExampleModel))).all()]
+```
+
+## Infrastructure
+
+The generated agent construct implements `IGrantable` and `IConnectable`, so you can grant network and IAM access to the database directly on the construct.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="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 myAgent = new MyAgent(this, 'MyAgent', {
+  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(this, {
+    vpc,
+    vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
+    securityGroups: [
+      new SecurityGroup(this, 'MyAgentSecurityGroup', { vpc, allowAllOutbound: true }),
+    ],
+  }),
+});
+
+db.allowDefaultPortFrom(myAgent);
+db.grantConnect(myAgent);
+```
+
+`allowDefaultPortFrom` opens the security group rule so the agent runtime can reach the database port. `grantConnect` grants IAM `rds-db:connect` permission to the agent's execution role.
+
+
+</Fragment>
+<Fragment slot="terraform">
+
+Run the agent inside the same VPC as the database, grant it `rds-db:connect` via `additional_iam_policy_statements`, and open the network path with a pair of security group rules. The `aws_vpc.main` and `aws_subnet` resources are defined in the database deployment guide:
+
+```hcl title="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_agent" {
+  source     = "../../common/terraform/src/app/agents/my-agent"
+  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" "agent_to_database" {
+  description                  = "Allow the agent runtime to connect to the database"
+  security_group_id            = module.my_database.security_group_id
+  referenced_security_group_id = module.my_agent.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" "agent_to_database" {
+  description                  = "Allow outbound traffic from the agent runtime to the database"
+  security_group_id            = module.my_agent.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` come from the shared <Link path="guides/runtime-config">runtime configuration</Link> AppConfig application declared once in your root module, not from the database module. Include the `database` namespace when instantiating it so the database module's runtime configuration entry is deployed:
+
+```hcl title="packages/infra/src/main.tf"
+module "runtime_config_appconfig" {
+  source = "../../common/terraform/src/core/runtime-config/appconfig"
+
+  application_name = "my-app-runtime-config"
+  namespaces       = ["connection", "agentcore", "database"]
+}
+```
+
+</Fragment>
+</Infrastructure>
+
+### SSL Requirements When Connecting Without RDS Proxy
+
+When the agent connects directly to the Aurora cluster (without RDS Proxy), the connection generator updates the generated agent Dockerfile to install the Amazon RDS CA bundle into the system trust store:
+
+```dockerfile
+ADD https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem /usr/local/share/ca-certificates/rds-global-bundle.crt
+RUN update-ca-certificates
+```
+
+When using RDS Proxy, you do not need to configure the RDS CA bundle in the agent runtime.
+
+## Local Development
+
+<NxCommands commands={["<agent-name>-dev <project-name>"]} />
+
+This starts the agent and all connected databases. The `LOCAL_DEV=true` environment variable causes the database client to connect to its local Docker database instead of Aurora.

package/docs/guides/connection/py-fast-api-rdb.mdx

@@ -0,0 +1,184 @@
+---
+title: FastAPI to Relational Database
+description: Connect a FastAPI to a Python Relational Database
+when:
+  sourceType: py#fast-api
+  targetType: py#rdb
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Infrastructure from '@components/infrastructure.astro';
+
+The `connection` generator wires a <Link path="guides/fastapi">FastAPI</Link> to a <Link path="guides/py-rdb">Python Relational Database</Link> project, injecting a typed SQLModel session into your route handlers via a FastAPI dependency.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/fastapi">`py#fast-api`</Link> project
+2. A <Link path="guides/py-rdb">`py#rdb`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your FastAPI project as the source and your relational database project as the target.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator modifies your FastAPI project:
+
+<FileTree>
+
+- packages/my_api
+  - project.json Adds a dependency from `dev` on the database's `dev` target
+  - pyproject.toml Adds the database package as a workspace dependency
+  - my_api
+    - dependencies
+      - my_db.py FastAPI `MyDbSession` dependency for the database session
+
+</FileTree>
+
+## Using the Database in Route Handlers
+
+This generator configures an injectable [FastAPI Dependency](https://fastapi.tiangolo.com/tutorial/dependencies/) which you can use in your route handlers:
+
+```python title="packages/my_api/my_api/api.py" {2,6,10}
+from sqlmodel import select
+from my_api.dependencies.my_db import MyDbSession
+from my_scope.my_db.models.example import ExampleModel
+
+@app.get("/examples")
+async def list_examples(my_db: MyDbSession):
+    return (await my_db.execute(select(ExampleModel))).all()
+
+@app.post("/examples")
+async def create_example(name: str, my_db: MyDbSession):
+    item = ExampleModel(name=name)
+    my_db.add(item)
+    await my_db.commit()
+    await my_db.refresh(item)
+    return item
+```
+
+FastAPI automatically opens a new session per request and closes it when the handler returns.
+
+## Infrastructure
+
+To allow the FastAPI Lambda function to connect to the database at runtime, it must be deployed into the same VPC as the database and granted network and IAM access.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+In your application stack, deploy the API into the same VPC as the database, then call `allowDefaultPortFrom` and `grantConnect` to open the network path and grant IAM `rds-db:connect` permission to the Lambda handler:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from ':my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', { vpc, ... });
+
+const api = new MyApi(this, 'Api', {
+  integrations: MyApi.defaultIntegrations(this)
+    .withDefaultOptions({
+      vpc,
+      vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
+    })
+    .build(),
+});
+
+Object.entries(api.integrations).forEach(([operation, integration]) => {
+  db.allowDefaultPortFrom(integration.handler, `Allow ${operation} to connect to the database`);
+  db.grantConnect(integration.handler);
+});
+```
+
+Deploy the API Lambda functions into a **private subnet with egress**, not a private isolated subnet. At runtime, `session_context()` retrieves database configuration from AWS AppConfig, which is a public AWS service endpoint that requires outbound internet access.
+
+:::note
+This example grants every handler in your API access, but if only some handlers need access it's better to configure individually.
+:::
+
+</Fragment>
+<Fragment slot="terraform">
+
+Deploy the API into the same VPC as the database, grant it `rds-db:connect` via `additional_iam_policy_statements`, and open the network path with a pair of security group rules:
+
+The example below references the VPC resources from the <Link path="guides/py-rdb">Python Relational Database</Link> deployment guide: `aws_subnet.database` subnets have no internet route, while `aws_subnet.private` subnets have NAT egress.
+
+```hcl title="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 "api" {
+  source     = "../../common/terraform/src/app/apis/my-api"
+  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" "api_to_database" {
+  description                  = "Allow the API Lambda functions to connect to the database"
+  security_group_id            = module.my_database.security_group_id
+  referenced_security_group_id = module.api.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" "api_to_database" {
+  description                  = "Allow outbound traffic from the API Lambda functions to the database"
+  security_group_id            = module.api.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"
+}
+```
+
+Deploy the API Lambda functions into **private subnets with egress**, not private isolated subnets. `appconfig_application_id`/`appconfig_application_arn` come from the shared <Link path="guides/runtime-config">runtime configuration</Link> AppConfig application declared once in your root module, not from the database module — passing them sets `RUNTIME_CONFIG_APP_ID` on the Lambda functions and grants them read access to the application.
+
+The AppConfig application must expose the `database` namespace so the database module's runtime configuration entry is deployed. Include it in the `namespaces` when instantiating the `runtime-config/appconfig` module:
+
+```hcl title="packages/infra/src/main.tf"
+module "runtime_config_appconfig" {
+  source = "../../common/terraform/src/core/runtime-config/appconfig"
+
+  application_name = "my-app-runtime-config"
+  namespaces       = ["connection", "agentcore", "database"]
+}
+```
+
+</Fragment>
+</Infrastructure>
+
+## Local Development
+
+<NxCommands commands={["dev <project-name>"]} />
+
+This starts the FastAPI and all connected databases. The `LOCAL_DEV=true` environment variable causes the database client to connect to its local Docker database instead of Aurora.

package/docs/guides/connection/py-mcp-server-rdb.mdx

@@ -0,0 +1,187 @@
+---
+title: Python MCP Server to Relational Database
+description: Connect a Python MCP Server to a Relational Database
+when:
+  sourceType: py#mcp-server
+  targetType: py#rdb
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Infrastructure from '@components/infrastructure.astro';
+
+The `connection` generator wires a <Link path="guides/py-mcp-server">Python MCP Server</Link> to a <Link path="guides/py-rdb">Python Relational Database</Link> project, making the database session available to all tools registered in the server.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/py-mcp-server">`py#mcp-server`</Link> project
+2. A <Link path="guides/py-rdb">`py#rdb`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your MCP server project as the source and your relational database project as the target. If the project contains multiple MCP server components, specify `sourceComponent` to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+<FileTree>
+
+- packages/my\_service
+  - project.json Adds a dependency from `my_mcp_server-dev` on the database's `dev` target
+  - pyproject.toml Adds the database package as a workspace dependency
+  - my\_service
+    - my\_mcp\_server
+      - Dockerfile Adds the RDS CA bundle used for direct Aurora connections
+
+</FileTree>
+
+## Using the Database in MCP Tools
+
+Import `session_context` from your database package and use it inside your MCP server tools:
+
+```python title="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))).all()
+        return str([item.model_dump() for item in items])
+```
+
+## Multiple Databases
+
+Running the generator again with a different target adds the second database alongside the first. Both session contexts are available to all tools:
+
+```python title="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
+```
+
+## Infrastructure
+
+The generated MCP server construct implements `IGrantable` and `IConnectable`, so you can grant network and IAM access to the database directly on the construct.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="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` opens the security group rule so the MCP server runtime can reach the database port. `grantConnect` grants IAM `rds-db:connect` permission to the server's execution role.
+
+
+</Fragment>
+<Fragment slot="terraform">
+
+Run the MCP server inside the same VPC as the database, grant it `rds-db:connect` via `additional_iam_policy_statements`, and open the network path with a pair of security group rules. The `aws_vpc.main` and `aws_subnet` resources are defined in the database deployment guide:
+
+```hcl title="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` come from the shared <Link path="guides/runtime-config">runtime configuration</Link> AppConfig application declared once in your root module, not from the database module. Include the `database` namespace when instantiating it so the database module's runtime configuration entry is deployed:
+
+```hcl title="packages/infra/src/main.tf"
+module "runtime_config_appconfig" {
+  source = "../../common/terraform/src/core/runtime-config/appconfig"
+
+  application_name = "my-app-runtime-config"
+  namespaces       = ["connection", "agentcore", "database"]
+}
+```
+
+</Fragment>
+</Infrastructure>
+
+### SSL Requirements When Connecting Without RDS Proxy
+
+When the MCP server connects directly to the Aurora cluster (without RDS Proxy), the connection generator updates the generated MCP server Dockerfile to install the Amazon RDS CA bundle into the system trust store:
+
+```dockerfile
+ADD https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem /usr/local/share/ca-certificates/rds-global-bundle.crt
+RUN update-ca-certificates
+```
+
+When using RDS Proxy, you do not need to configure the RDS CA bundle in the MCP server runtime.
+
+## Local Development
+
+<NxCommands commands={["<mcp-server-name>-dev <project-name>"]} />
+
+This starts the MCP server and all connected databases. The `LOCAL_DEV=true` environment variable causes the database client to connect to its local Docker database instead of Aurora.

package/docs/guides/connection/smithy-rdb.mdx

@@ -134,7 +134,7 @@ const httpResponse = await serviceHandler.handle(httpRequest, {
 
 ### SSL Requirements When Connecting Without RDS Proxy
 
-<Snippet name="connection/lambda-rdb-ssl-requirements" parentHeading="SSL Requirements When Connecting Without RDS Proxy" />
+<Snippet name="connection/ts-lambda-rdb-ssl-requirements" parentHeading="SSL Requirements When Connecting Without RDS Proxy" />
 
 ## Local Development
 

package/docs/guides/connection/trpc-rdb.mdx

@@ -116,7 +116,7 @@ export const dbProcedure = t.procedure
 
 ### SSL Requirements When Connecting Without RDS Proxy
 
-<Snippet name="connection/lambda-rdb-ssl-requirements" parentHeading="SSL Requirements When Connecting Without RDS Proxy" />
+<Snippet name="connection/ts-lambda-rdb-ssl-requirements" parentHeading="SSL Requirements When Connecting Without RDS Proxy" />
 
 ## Local Development