@aws/nx-plugin-mcp 1.0.0-rc.3 → 1.0.0-rc.30

package/docs/guides/connection/ts-agent-gateway.mdx

@@ -0,0 +1,141 @@
+---
+title: TypeScript Agent to Gateway
+description: Connect a TypeScript Agent to an AgentCore Gateway
+when:
+  sourceType: ts#agent
+  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 your <Link path="guides/ts-agent">TypeScript Agent</Link> to an <Link path="guides/agentcore-gateway">AgentCore Gateway</Link>.
+
+The generator wires the agent so it authenticates to the Gateway with IAM SigV4 when deployed, and connects to the local gateway started by the Gateway project when running locally.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A TypeScript project with a <Link path="guides/ts-agent">Agent</Link> component (`infra: agentcore`)
+2. A <Link path="guides/agentcore-gateway">`agentcore-gateway`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select the agent project as the source and the Gateway project as the target.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator emits shared core client files into your `agent-connection` package, plus a per-Gateway wrapper, and modifies your agent:
+
+<FileTree>
+
+- packages/common/agent-connection
+  - src
+    - core/
+      - agentcore-endpoints.ts Framework-agnostic ARN/URL resolution
+      - agentcore-gateway-mcp-transport.ts Framework-agnostic Gateway MCP transport
+      - agentcore-gateway-mcp-client-strands.ts Strands MCP client for the deployed Gateway
+    - app/
+      - \<gateway-kebab>-client-strands.ts Per-Gateway Strands client wrapper
+    - index.ts Re-exports the Gateway client
+
+</FileTree>
+
+Additionally, the generator:
+
+- Modifies your agent's `agent.ts` to import the Gateway client class, call `<Gateway>ClientStrands.create()`, and register the returned client in the `tools` array
+- Wires the agent's `<agent>-dev` target to depend on the Gateway's `dev` target
+- Installs the required SigV4 / MCP dependencies
+
+## Using the connected Gateway
+
+The generator transforms your agent's `agent.ts` to use the Gateway client:
+
+```ts title="packages/example/src/my-agent/agent.ts" {2,5,8}
+import { Agent } from '@strands-agents/sdk';
+import { MyGatewayClientStrands } from ':my-scope/agent-connection';
+
+export const getAgent = async () => {
+  const myGateway = await MyGatewayClientStrands.create();
+  return new Agent({
+    systemPrompt: '...',
+    tools: [myGateway],
+  });
+};
+```
+
+When deployed (`LOCAL_DEV` unset), the client points at the Gateway's MCP endpoint and authenticates with SigV4. When `LOCAL_DEV=true`, it points at the local gateway started by the Gateway project's `dev` target, so the same `agent.ts` works uniformly in both modes.
+
+The session ID is propagated to downstream MCP servers automatically via the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header.
+
+## Infrastructure
+
+After running the generator you must grant the agent permission to invoke the Gateway.
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts title="packages/infra/src/stacks/application-stack.ts" {5}
+const gateway = new MyGateway(this, 'MyGateway');
+const myAgent = new MyAgent(this, 'MyAgent');
+
+// Grant the agent permissions to invoke the Gateway
+gateway.grantInvokeAccess(myAgent);
+```
+
+The Gateway URL is automatically registered in the `agentcore.gateways.<ClassName>` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link> by the generated CDK construct, so the agent can discover it at runtime.
+</Fragment>
+<Fragment slot="terraform">
+```hcl title="packages/infra/src/main.tf" {6-13}
+module "my_gateway" {
+  source = "../../common/terraform/src/app/gateways/my-gateway"
+}
+
+module "my_agent" {
+  source = "../../common/terraform/src/app/agents/my-agent"
+
+  # Grant the agent permission to invoke the Gateway
+  additional_iam_policy_statements = [{
+    Effect   = "Allow"
+    Action   = ["bedrock-agentcore:InvokeGateway"]
+    Resource = [module.my_gateway.gateway_arn]
+  }]
+}
+```
+
+The Gateway URL is automatically registered in the `agentcore.gateways.<ClassName>` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link> by the generated Terraform module, so the agent can discover it at runtime.
+</Fragment>
+</Infrastructure>
+
+## Local Development
+
+The generator configures the agent's `dev` target to:
+
+1. Start the connected Gateway's local gateway and every attached MCP server
+2. Set `LOCAL_DEV=true` so the generated client points at the local gateway instead of the deployed Gateway
+
+Run the agent locally with:
+
+<NxCommands commands={["<agent-name>-dev <project-name>"]} />
+
+To run the agent locally **against the deployed Gateway** instead (for example, to exercise Cedar policies), use the agent's `serve` target. Without `LOCAL_DEV` set, the client resolves the deployed Gateway URL from runtime configuration and SigV4-signs requests with your local AWS credentials:
+
+<NxCommands commands={["<agent-name>-serve <project-name>"]} />
+
+### Local fidelity
+
+The local gateway stands in for the deployed Gateway, so:
+
+- **No Cedar policy evaluation.** Every tool is visible to the agent regardless of policies. Use the `serve` target to exercise policies against the deployed Gateway.
+- **Tool-name prefixing is preserved.** Each local MCP server's tools are wrapped to expose names of the form `<target-name>___<tool-name>`, matching what the deployed Gateway emits. This keeps an agent's system prompt and the Cedar action names you reference consistent across local and deployed runs.

package/docs/guides/connection/ts-agent-mcp.mdx

@@ -47,9 +47,12 @@ The generator creates a shared `agent-connection` package and modifies your agen
 - packages/common/agent-connection
   - src
     - app
-      - \<mcp-server-name>-client.ts High-level client for the connected MCP server
+      - \<mcp-server-name>-client-strands.ts High-level Strands client for the connected MCP server
     - core
-      - agentcore-mcp-client.ts Low-level AgentCore MCP client with SigV4/JWT authentication
+      - agentcore-endpoints.ts Framework-agnostic ARN/URL resolution
+      - agentcore-fetch.ts Framework-agnostic SigV4 / JWT / session-forwarding fetch
+      - agentcore-mcp-transport.ts Framework-agnostic MCP transport
+      - agentcore-mcp-client-strands.ts Strands MCP client wrapping the transport
     - index.ts Exports all clients
   - project.json
   - tsconfig.json
@@ -58,7 +61,7 @@ The generator creates a shared `agent-connection` package and modifies your agen
 
 Additionally, it:
 - Transforms your agent's `agent.ts` to import and use the MCP server's tools
-- Updates the agent's `serve-local` target to depend on the MCP server's serve target
+- Updates the agent's `dev` target to depend on the MCP server's serve target
 - Installs required dependencies
 
 ## Using the Connected MCP Server
@@ -67,10 +70,10 @@ The generator transforms your agent's `agent.ts` to use the MCP server's tools:
 
 ```ts title="packages/example/src/my-agent/agent.ts" {2,5,8}
 import { Agent, tool } from '@strands-agents/sdk';
-import { MyMcpServerClient } from ':my-scope/agent-connection';
+import { MyMcpServerClientStrands } from ':my-scope/agent-connection';
 
 export const getAgent = async (sessionId: string) => {
-  const myMcpServerClient = await MyMcpServerClient.create(sessionId);
+  const myMcpServerClient = await MyMcpServerClientStrands.create(sessionId);
   return new Agent({
     systemPrompt: '...',
     tools: [myMcpServerClient],
@@ -133,12 +136,12 @@ The MCP server's AgentCore runtime ARN is automatically registered in the `agent
 
 ## Local Development
 
-The generator configures the agent's `serve-local` target to:
+The generator configures the agent's `dev` target to:
 1. Start the connected MCP server(s) automatically
-2. Set `SERVE_LOCAL=true` so the generated client uses direct HTTP transport instead of AgentCore
+2. Set `LOCAL_DEV=true` so the generated client uses direct HTTP transport instead of AgentCore
 
 Run the agent locally with:
 
-<NxCommands commands={["<agent-name>-serve-local <project-name>"]} />
+<NxCommands commands={["<agent-name>-dev <project-name>"]} />
 
 This will start both the agent and all connected MCP servers, with the agent connecting to the MCP servers directly via HTTP on their assigned local ports.

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

@@ -46,7 +46,7 @@ The generator modifies two files in your agent's source directory:
 
 </FileTree>
 
-Additionally, the agent's `<agent-name>-serve-local` target is updated to depend on the database's `serve-local` target.
+Additionally, the agent's `<agent-name>-dev` target is updated to depend on the database's `dev` target.
 
 ## How It Works
 
@@ -136,6 +136,6 @@ Ensure the agent's execution role has `rds-db:connect` permission and that its s
 
 ## Local Development
 
-<NxCommands commands={["<agent-name>-serve-local <project-name>"]} />
+<NxCommands commands={["<agent-name>-dev <project-name>"]} />
 
-This starts the agent and all connected databases. The `SERVE_LOCAL=true` environment variable causes each Prisma client to connect to its local Docker database instead of Aurora.
+This starts the agent and all connected databases. The `LOCAL_DEV=true` environment variable causes each Prisma client to connect to its local Docker database instead of Aurora.

package/docs/guides/connection/ts-mcp-server-dynamodb.mdx

@@ -0,0 +1,125 @@
+---
+title: MCP Server to DynamoDB
+description: Connect a TypeScript MCP Server to a TypeScript DynamoDB project
+when:
+  sourceType: ts#mcp-server
+  targetType: ts#dynamodb
+---
+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';
+import Snippet from '@components/snippet.astro';
+
+The `connection` generator wires a <Link path="guides/ts-mcp-server">TypeScript MCP Server</Link> to a <Link path="guides/ts-dynamodb">TypeScript DynamoDB</Link> project, configuring local development so both start together automatically.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/ts-mcp-server">`ts#mcp-server`</Link> project
+2. A <Link path="guides/ts-dynamodb">`ts#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. No source files are modified.
+
+## Using DynamoDB in Tools
+
+Import entity factories from the DynamoDB package and use them inside `createServer`:
+
+```ts title="packages/my-service/src/my-mcp/server.ts"
+import { createExampleEntity } from ':my-scope/my-table';
+
+export const createServer = async () => {
+  const server = new McpServer({ name: 'my-service', version: '1.0.0' });
+
+  server.tool('list_examples', 'List all example items', {}, async () => {
+    const entity = await createExampleEntity();
+    const result = await entity.scan.go();
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result.data) }],
+    };
+  });
+
+  return server;
+};
+```
+
+## Infrastructure
+
+To allow the MCP server 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">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source = "../../common/terraform/src/app/dynamodb/my-table"
+}
+
+resource "aws_iam_role_policy" "dynamodb_access" {
+  role = module.my_mcp_server.lambda_role_name
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        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/dynamodb-local-development" />

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

@@ -46,7 +46,7 @@ The generator modifies two files in your MCP server's source directory:
 
 </FileTree>
 
-Additionally, the `<mcp-server-name>-serve-local` target is updated to depend on the database's `serve-local` target.
+Additionally, the `<mcp-server-name>-dev` target is updated to depend on the database's `dev` target.
 
 ## How It Works
 
@@ -130,6 +130,6 @@ Ensure the MCP server's execution role has `rds-db:connect` permission and that
 
 ## Local Development
 
-<NxCommands commands={["<mcp-server-name>-serve-local <project-name>"]} />
+<NxCommands commands={["<mcp-server-name>-dev <project-name>"]} />
 
-This starts the MCP server and all connected databases. The `SERVE_LOCAL=true` environment variable causes each Prisma client to connect to its local Docker database instead of Aurora.
+This starts the MCP server and all connected databases. The `LOCAL_DEV=true` environment variable causes each Prisma client to connect to its local Docker database instead of Aurora.

package/docs/guides/connection.mdx

@@ -6,9 +6,21 @@ import Astro from '@astrojs/react';
 import { CardGrid, LinkButton } from '@astrojs/starlight/components';
 import Link from '@components/link.astro';
 import ConnectionCard from '@components/connection-card.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
 
 This generator is used to connect projects together, such as websites calling APIs. Simply select the source project (for example the project that will call your API) and target project (for example your API project), and this generator will handle integrating the two.
 
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
 ### Supported Connections
 
 The Connection generator supports the following connections:
@@ -119,8 +131,97 @@ The Connection generator supports the following connections:
     source="mcp"
     target="aurora"
   />
+  <ConnectionCard
+    title="tRPC API to TypeScript DynamoDB"
+    description="Connect a tRPC API to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/trpc-dynamodb`}
+    source="trpc"
+    target="dynamodb"
+  />
+  <ConnectionCard
+    title="Smithy API to TypeScript DynamoDB"
+    description="Connect a Smithy API to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/smithy-dynamodb`}
+    source="smithy"
+    target="dynamodb"
+  />
+  <ConnectionCard
+    title="TypeScript Agent to TypeScript DynamoDB"
+    description="Connect a TypeScript Agent to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-dynamodb`}
+    source="strands"
+    sourceBadge="typescript"
+    target="dynamodb"
+  />
+  <ConnectionCard
+    title="MCP Server to TypeScript DynamoDB"
+    description="Connect a TypeScript MCP Server to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-mcp-server-dynamodb`}
+    source="mcp"
+    target="dynamodb"
+  />
+  <ConnectionCard
+    title="FastAPI to Python DynamoDB"
+    description="Connect a FastAPI to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-fast-api-dynamodb`}
+    source="fastapi"
+    target="dynamodb"
+    targetBadge="python"
+  />
+  <ConnectionCard
+    title="Python Agent to Python DynamoDB"
+    description="Connect a Python Agent to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-agent-dynamodb`}
+    source="strands"
+    sourceBadge="python"
+    target="dynamodb"
+    targetBadge="python"
+  />
+  <ConnectionCard
+    title="Python MCP Server to Python DynamoDB"
+    description="Connect a Python MCP Server to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-mcp-server-dynamodb`}
+    source="mcp"
+    sourceBadge="python"
+    target="dynamodb"
+    targetBadge="python"
+  />
+  <ConnectionCard
+    title="AgentCore Gateway to MCP Server"
+    description="Aggregate an MCP server behind an AgentCore Gateway"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/agentcore-gateway-mcp`}
+    source="agentcore"
+    target="mcp"
+  />
+  <ConnectionCard
+    title="AgentCore Gateway to AgentCore Gateway"
+    description="Aggregate an AgentCore Gateway behind another AgentCore Gateway"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/agentcore-gateway-gateway`}
+    source="agentcore"
+    target="agentcore"
+  />
+  <ConnectionCard
+    title="TypeScript Agent to AgentCore Gateway"
+    description="Connect a TypeScript Agent to an AgentCore Gateway"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-gateway`}
+    source="strands"
+    sourceBadge="typescript"
+    target="agentcore"
+  />
+  <ConnectionCard
+    title="Python Agent to AgentCore Gateway"
+    description="Connect a Python Agent to an AgentCore Gateway"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-agent-gateway`}
+    source="strands"
+    sourceBadge="python"
+    target="agentcore"
+  />
 </CardGrid>
 
 :::note[Runtime Configuration]
 The connection generator makes use of <Link path="guides/runtime-config">Runtime Configuration</Link> to pass deploy-time values (such as API URLs, Cognito settings, and agent runtime ARNs) between generated projects and components at runtime so they can discover and connect to one another.
 :::
+
+:::tip[Local Development]
+Connected projects can be run on your machine with the `serve` and `dev` targets. See the <Link path="guides/local-development">Local Development</Link> guide for details.
+:::

package/docs/guides/docker-bundling.mdx

@@ -8,7 +8,7 @@ import NxCommands from '@components/nx-commands.astro';
 import Link from '@components/link.astro';
 import Infrastructure from '@components/infrastructure.astro';
 
-Several generators (such as <Link path="/guides/ts-agent">`ts#agent`</Link> and <Link path="/guides/py-agent">`py#agent`</Link>) produce a Docker image that is pushed to Amazon ECR and consumed by AWS infrastructure. This guide describes the pattern they follow so that you can apply it to other use cases — for example, running a <Link path="/guides/fastapi">`py#fast-api`</Link> project on Amazon ECS, or deploying a containerised Express server.
+Several generators (such as <Link path="/guides/ts-agent">`ts#agent`</Link> and <Link path="/guides/py-agent">`py#agent`</Link>) produce a Docker image that is pushed to Amazon ECR and consumed by AWS infrastructure. This guide describes the pattern they follow so that you can apply it to other use cases — for example, running a <Link path="/guides/fastapi">FastAPI</Link> project on Amazon ECS, or deploying a containerised Express server.
 
 :::tip[Docker or Finch]
 The container engine used to build images is chosen at workspace creation time via the `--containerEngine` flag (`docker`, `finch`, or `infer` — the default — which auto-detects what's installed). [Finch](https://runfinch.com/) is an open-source, drop-in alternative to Docker. The selection is recorded in `aws-nx-plugin.config.mts` and applied to every generator that emits container build commands. CDK image asset builds honour the choice via the `CDK_DOCKER` environment variable.
@@ -318,8 +318,8 @@ Terraform's AWS provider does not have a first-class "build and push a Docker im
 
 1. The project's `build` target runs `docker build`, producing a local image tagged `my-scope-my-project:latest`.
 2. An `aws_ecr_repository` to hold the image.
-3. A `null_resource` with a `local-exec` provisioner that authenticates to ECR, re-tags the locally-built image, and pushes it.
-4. The downstream resource (e.g. `aws_ecs_task_definition`) references `"${aws_ecr_repository.repo.repository_url}:latest"`.
+3. A `null_resource` with a `local-exec` provisioner that authenticates to ECR, re-tags the locally-built image with its content digest, and pushes it.
+4. The downstream resource (e.g. `aws_ecs_task_definition`) references the image by its immutable, digest-based tag.
 
 ```d2
 direction: down
@@ -361,7 +361,7 @@ infra.repo -> ecr
 ```hcl
 resource "aws_ecr_repository" "repo" {
   name                 = "my-project-repository"
-  image_tag_mutability = "MUTABLE"
+  image_tag_mutability = "IMMUTABLE"
   force_delete         = true
 }
 
@@ -370,24 +370,30 @@ data "external" "docker_digest" {
   program = ["sh", "-c", "echo '{\"digest\":\"'$(docker inspect my-scope-my-project:latest --format '{{.Id}}')'\"}'"]
 }
 
+locals {
+  # Content-based, immutable image tag derived from the local image digest
+  image_tag = replace(data.external.docker_digest.result.digest, "sha256:", "")
+}
+
 resource "null_resource" "docker_publish" {
   triggers = {
     docker_digest  = data.external.docker_digest.result.digest
     repository_url = aws_ecr_repository.repo.repository_url
+    image_tag      = local.image_tag
   }
 
   provisioner "local-exec" {
     command = <<-EOT
       aws ecr get-login-password --region ${data.aws_region.current.id} \
         | docker login --username AWS --password-stdin ${self.triggers.repository_url}
-      docker tag my-scope-my-project:latest ${self.triggers.repository_url}:latest
-      docker push ${self.triggers.repository_url}:latest
+      docker tag my-scope-my-project:latest ${self.triggers.repository_url}:${self.triggers.image_tag}
+      docker push ${self.triggers.repository_url}:${self.triggers.image_tag}
     EOT
   }
 }
 ```
 
-The `data.external.docker_digest` block ensures the `null_resource` re-runs whenever the local image hash changes, triggering a new push on every meaningful code change.
+The `data.external.docker_digest` block ensures the `null_resource` re-runs whenever the local image hash changes, triggering a new push on every meaningful code change. The image is pushed under an immutable, content-based tag derived from its digest, so the ECR repository can use `IMMUTABLE` tag mutability and reject any attempt to overwrite an existing tag.
 
 :::note[Running bundle before apply]
 `nx apply <project>` requires the image tag `my-scope-my-project:latest` to already exist locally. Run `nx build my-project` (or `nx docker my-project`) before `nx apply <project>`.