@aws/nx-plugin-mcp 1.0.0-rc.9 → 1.0.0-rc.91

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

@@ -0,0 +1,175 @@
+---
+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 FastAPI project (generated with `py#api --framework=fastapi`), see the <Link path="guides/fastapi">`py#api`</Link> guide
+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 exposes the `database` namespace by default, so the database module's runtime configuration entry is deployed without further configuration.
+
+</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-dynamodb.mdx

@@ -0,0 +1,115 @@
+---
+title: Python MCP Server to DynamoDB
+description: Connect a Python MCP Server to a Python DynamoDB project
+when:
+  sourceType: py#mcp-server
+  targetType: py#dynamodb
+---
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
+
+The `connection` generator wires a <Link path="guides/py-mcp-server">Python MCP Server</Link> to a <Link path="guides/py-dynamodb">Python DynamoDB</Link> project, configuring local development so both start together automatically.
+
+## 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-dynamodb">`py#dynamodb`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your MCP server project as the source and your DynamoDB project as the target. If the project contains multiple MCP server components, specify `sourceComponent` to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator updates the MCP server's `<mcp-server-name>-dev` target in `project.json` to depend on the DynamoDB project's `dev` target, and adds the DynamoDB package as a workspace dependency. No source files are modified.
+
+## Using DynamoDB in Tools
+
+Import entity classes from the DynamoDB package and use them inside your MCP server tools:
+
+```python title="packages/my_project/my_project/my_mcp_server/server.py"
+from my_scope.my_table.entities.example import ExampleModel
+
+@mcp.tool()
+def list_examples() -> str:
+    """List all example items."""
+    items = list(ExampleModel.scan())
+    return str([item.attribute_values for item in items])
+```
+
+## Infrastructure
+
+To allow the MCP server's Lambda function to access the DynamoDB table, grant the necessary permissions in your infrastructure.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyTable } from '@my-scope/common-constructs';
+
+const table = new MyTable(this, 'Table');
+const myMcpServer = new MyMcpServer(this, 'MyMcpServer');
+
+table.grantReadWriteData(myMcpServer);
+```
+
+`grantReadWriteData` grants both the DynamoDB and KMS permissions to the MCP server's execution role.
+</Fragment>
+<Fragment slot="terraform">
+
+Grant the MCP server's runtime role access to the table and its KMS encryption key via `additional_iam_policy_statements`:
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source = "../../common/terraform/src/app/dynamodb/my-table"
+}
+
+module "my_mcp_server" {
+  source = "../../common/terraform/src/app/mcp-servers/my-mcp-server"
+
+  additional_iam_policy_statements = [
+    {
+      Effect = "Allow"
+      Action = [
+        "dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:UpdateItem",
+        "dynamodb:DeleteItem", "dynamodb:Query", "dynamodb:Scan",
+        "dynamodb:BatchGetItem", "dynamodb:BatchWriteItem",
+      ]
+      Resource = [
+        module.my_table.table_arn,
+        "${module.my_table.table_arn}/index/*",
+      ]
+    },
+    {
+      Effect = "Allow"
+      Action = [
+        "kms:Encrypt",
+        "kms:Decrypt",
+        "kms:ReEncrypt*",
+        "kms:GenerateDataKey*",
+        "kms:DescribeKey",
+      ]
+      Resource = [module.my_table.kms_key_arn]
+    },
+  ]
+}
+```
+</Fragment>
+</Infrastructure>
+
+## Local Development
+
+<Snippet name="connection/py-dynamodb-local-development" />

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

@@ -0,0 +1,178 @@
+---
+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. That application exposes the `database` namespace by default, so the database module's runtime configuration entry is deployed without further configuration.
+
+</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/react-agentcore-gateway.mdx

@@ -0,0 +1,112 @@
+---
+title: React Website to AgentCore Gateway
+description: Connect a React website to agents through an AgentCore Gateway
+when:
+  sourceType: ts#react-website
+  targetType: agentcore-gateway
+---
+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 can connect a <Link path="guides/react-website">React website</Link> to the agents fronted by an <Link path="guides/agentcore-gateway">AgentCore Gateway</Link> generated with `protocol: http`.
+
+The browser talks only to the Gateway — requests to `<gatewayUrl>/<targetName>/invocations` are proxied to the agent runtime behind it. Because the website never needs to reach the runtimes directly, the agents can be deployed inside a VPC, with the Gateway as the single governed entry point providing authentication and observability.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/react-website">React website</Link> project
+2. An <Link path="guides/agentcore-gateway">`agentcore-gateway`</Link> project generated with `protocol: http`
+3. At least one AG-UI or HTTP agent attached to the Gateway via the <Link path="guides/connection/agentcore-gateway-agent">Gateway to agent connection generator</Link>
+
+The generator creates a website client for **each** AG-UI or HTTP agent attached to the Gateway (A2A targets are skipped — they speak agent-to-agent JSON-RPC, not a browser protocol). It generates the same clients as connecting the website to each agent directly (<Link path="guides/connection/react-agui">AG-UI/CopilotKit</Link> for AG-UI agents, an <Link path="guides/connection/react-py-agent">OpenAPI client</Link> for Python HTTP agents), routed through the Gateway rather than at the runtime.
+
+:::note[Authentication]
+The browser authenticates with the **Gateway**, not the agents: SigV4 for an IAM Gateway (via the website's Cognito identity pool), or a JWT bearer token for a Cognito Gateway.
+:::
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select the website project as the source and the Gateway project as the target.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+For each fronted AG-UI agent, the same files as the <Link path="guides/connection/react-agui">React to AG-UI agent connection</Link> are generated (an `AguiProvider`, a `useAgui<Agent>` hook and a themed CopilotKit component module), with the hook reading the Gateway's URL from runtime configuration:
+
+<FileTree>
+
+- packages/\<website>/src
+  - components
+    - AguiProvider.tsx CopilotKit provider registering each agent
+    - copilot/ Themed chat components
+  - hooks
+    - useAgui\<Agent>.tsx Connects to the agent via the Gateway's `/<targetName>/invocations` route
+
+</FileTree>
+
+For each fronted Python HTTP agent, the same files as the <Link path="guides/connection/react-py-agent">React to Python agent connection</Link> are generated (a type-safe OpenAPI client, hooks, and a provider), with the client's base URL routed through the Gateway.
+
+The Gateway's URL is registered in the `connection.gateways.<GatewayClassName>` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link>, so it is published to the website's `runtime-config.json`.
+
+## Granting website users access
+
+For an **IAM** Gateway, grant the website's authenticated users permission to invoke it (a **Cognito** Gateway needs no grant — the browser authenticates with its JWT bearer token instead):
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts title="packages/infra/src/stacks/application-stack.ts" {6}
+const identity = new UserIdentity(this, 'UserIdentity');
+new Website(this, 'Website');
+
+const myGateway = new MyGateway(this, 'MyGateway');
+myGateway.addAgent(myAgent);
+myGateway.grantInvokeAccess(identity.identityPool.authenticatedRole);
+```
+</Fragment>
+<Fragment slot="terraform">
+```hcl title="packages/infra/src/main.tf"
+resource "aws_iam_policy" "gateway_invoke_policy" {
+  name = "GatewayInvokePolicy"
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect   = "Allow"
+        Action   = ["bedrock-agentcore:InvokeGateway"]
+        Resource = [module.my_gateway.gateway_arn]
+      }
+    ]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "authenticated_gateway_access" {
+  role       = module.user_identity.authenticated_role_name
+  policy_arn = aws_iam_policy.gateway_invoke_policy.arn
+}
+```
+</Fragment>
+</Infrastructure>
+
+## Local Development
+
+The website's `dev` target gains a dependency on the Gateway project's `dev` target, which starts the local gateway plus every attached agent. The website's runtime configuration is overridden in `local-dev` mode to point the Gateway's URL at the local gateway, so the browser exercises the same `/<targetName>/invocations` routes locally:
+
+<NxCommands commands={["dev <website-name>"]} />
+
+## Connecting new agents
+
+The generator connects the website to the agents attached to the Gateway **at the time it runs**. After attaching another agent to the Gateway, re-run the connection generator to generate its website client — existing clients are left untouched.