@aws/nx-plugin-mcp 1.0.0-rc.95 → 1.0.0-rc.97

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

@@ -43,16 +43,10 @@ Import entity factories from the DynamoDB package and use them inside your opera
 
 ```ts title="packages/api/src/operations/list-examples.ts"
 import { createExampleEntity } from '@my-scope/my-table';
-import {
-  ListExamplesOperationInput,
-  ListExamplesOperationOutput,
-} from '../generated/ssdk/index.js';
 import { ServiceContext } from '../context.js';
+import { ListExamples as ListExamplesOperation } from '../generated/ssdk/index.js';
 
-export const listExamples = async (
-  _input: ListExamplesOperationInput,
-  _ctx: ServiceContext,
-): Promise<ListExamplesOperationOutput> => {
+export const ListExamples: ListExamplesOperation<ServiceContext> = async () => {
   const entity = await createExampleEntity();
   const result = await entity.scan.go();
   return { items: result.data };

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

@@ -89,14 +89,11 @@ export const lambdaHandler = async (event: APIGatewayProxyEvent) => {
 
 Access `db` from the context in your operation implementations:
 
-```ts title="packages/api/src/operations/list-users.ts" {8}
-import { ListUsersOperationInput, ListUsersOperationOutput } from '../generated/ssdk/index.js';
+```ts title="packages/api/src/operations/list-users.ts" {5}
 import { ServiceContext } from '../context.js';
+import { ListUsers as ListUsersOperation } from '../generated/ssdk/index.js';
 
-export const listUsers = async (
-  input: ListUsersOperationInput,
-  ctx: ServiceContext,
-): Promise<ListUsersOperationOutput> => {
+export const ListUsers: ListUsersOperation<ServiceContext> = async (input, ctx) => {
   const users = await ctx.myDb.user.findMany();
   return { users };
 };

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

@@ -35,13 +35,14 @@ Select your tRPC API project as the source and your relational database project
 
 ## Generator Output
 
-The generator creates a middleware file in your tRPC API project:
+The generator creates a middleware file in your tRPC API project, and adds it to the tRPC context:
 
 <FileTree>
 
 - packages/api/src
   - middleware
     - \<db-name>.ts tRPC plugin exposing the Prisma client in procedure context
+  - init.ts The database's context interface added to `Context`
 
 </FileTree>
 
@@ -53,12 +54,11 @@ Additionally, it updates your tRPC API's `dev` target to start the database auto
 
 Add the generated plugin to your tRPC router so all procedures using it gain access to the database:
 
-```ts title="packages/api/src/router.ts" {2,5}
+```ts title="packages/api/src/router.ts" {2,4}
 import { t } from './init.js';
 import { createMyDbPlugin } from './middleware/my-db.js';
 
-export const authenticatedProcedure = t.procedure
-  .concat(createMyDbPlugin());
+export const dbProcedure = t.procedure.concat(createMyDbPlugin());
 ```
 
 ### Access the Database in Procedures
@@ -67,9 +67,9 @@ The plugin merges `IMyDbContext` into your procedure context, making `myDb` avai
 
 ```ts title="packages/api/src/procedures/users.ts" {7-8}
 import { z } from 'zod';
-import { authenticatedProcedure } from '../router.js';
+import { dbProcedure } from '../router.js';
 
-export const listUsers = authenticatedProcedure
+export const listUsers = dbProcedure
   .output(z.array(z.object({ id: z.string(), name: z.string() })))
   .query(async ({ ctx }) => {
     // ctx.myDb is the Prisma client — typed as Awaited<ReturnType<typeof getPrisma>>

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

@@ -73,8 +73,8 @@ import { Agent, tool } from '@strands-agents/sdk';
 import { RemoteAgentClientStrands } from '@my-scope/agent-connection';
 import { z } from 'zod';
 
-export const getAgent = async (sessionId: string) => {
-  const remoteAgent = await RemoteAgentClientStrands.create(sessionId);
+export const getAgent = async () => {
+  const remoteAgent = await RemoteAgentClientStrands.create();
   const remoteAgentTool = tool({
     name: 'askRemoteAgent',
     description: 'Delegate a question to the remote RemoteAgent A2A agent and return its reply.',
@@ -88,9 +88,9 @@ export const getAgent = async (sessionId: string) => {
 };
 ```
 
-The `sessionId` parameter is plumbed through from the caller, ensuring consistency for [Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html).
+The AgentCore session ID is propagated to the remote agent automatically via the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header, so `create()` takes no arguments: the agent server binds the inbound request's session into an [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) context (`enterSessionContext` in the generated `router.ts`, or `runWithSessionId` in the A2A/AG-UI session middleware), and the connection client's fetch in `agentcore-fetch.ts` stamps it on every outbound call — ensuring consistency for [Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html).
 
-Under the hood, `RemoteAgentClientStrands.create(sessionId)` returns a Strands `A2AAgent` configured with a SigV4-signing `clientFactory` when deployed to AWS, and a plain `http://localhost:<port>/` endpoint when `LOCAL_DEV=true`. The signing and endpoint resolution live in the framework-agnostic `agentcore-a2a-client-config.ts`; only the thin `agentcore-a2a-client-strands.ts` depends on Strands.
+Under the hood, `RemoteAgentClientStrands.create()` returns a Strands `A2AAgent` configured with a SigV4-signing `clientFactory` when deployed to AWS, and a plain `http://localhost:<port>/` endpoint when `LOCAL_DEV=true`. The signing and endpoint resolution live in the framework-agnostic `agentcore-a2a-client-config.ts`; only the thin `agentcore-a2a-client-strands.ts` depends on Strands.
 
 ## Infrastructure
 

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

@@ -43,21 +43,23 @@ Import entity factories from the DynamoDB package and use them inside your agent
 
 ```ts title="packages/my-service/src/my-agent/agent.ts"
 import { createExampleEntity } from '@my-scope/my-table';
+import { z } from 'zod';
+
+const listExamples = tool({
+  name: 'list_examples',
+  description: 'List all example items',
+  inputSchema: z.object({}),
+  callback: async () => {
+    const entity = await createExampleEntity();
+    const result = await entity.scan.go();
+    return result.data;
+  },
+});
 
 export const getAgent = async () => {
   // ...
   return new Agent({
-    tools: [
-      tool({
-        name: 'list_examples',
-        description: 'List all example items',
-        func: async () => {
-          const entity = await createExampleEntity();
-          const result = await entity.scan.go();
-          return result.data;
-        },
-      }),
-    ],
+    tools: [listExamples],
   });
 };
 ```

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

@@ -51,6 +51,8 @@ The generator emits shared core client files into your `agent-connection` packag
   - src
     - core/
       - agentcore-endpoints.ts Framework-agnostic ARN/URL resolution
+      - agentcore-fetch.ts Framework-agnostic SigV4 / JWT / session-forwarding fetch
+      - agentcore-transport.ts Shared AgentCore transport plumbing
       - agentcore-gateway-mcp-transport.ts Framework-agnostic Gateway MCP transport
       - agentcore-gateway-mcp-client-strands.ts Strands MCP client for the deployed Gateway
     - app/

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

@@ -13,6 +13,7 @@ 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 can connect your <Link path="guides/ts-agent">TypeScript Agent</Link> to an MCP server (either <Link path="guides/ts-mcp-server">TypeScript</Link> or <Link path="guides/py-mcp-server">Python</Link>).
 
@@ -51,6 +52,7 @@ The generator creates a shared `agent-connection` package and modifies your agen
     - core
       - agentcore-endpoints.ts Framework-agnostic ARN/URL resolution
       - agentcore-fetch.ts Framework-agnostic SigV4 / JWT / session-forwarding fetch
+      - agentcore-transport.ts Shared AgentCore transport plumbing
       - agentcore-mcp-transport.ts Framework-agnostic MCP transport
       - agentcore-mcp-client-strands.ts Strands MCP client wrapping the transport
     - index.ts Exports all clients
@@ -72,8 +74,8 @@ The generator transforms your agent's `agent.ts` to use the MCP server's tools:
 import { Agent, tool } from '@strands-agents/sdk';
 import { MyMcpServerClientStrands } from '@my-scope/agent-connection';
 
-export const getAgent = async (sessionId: string) => {
-  const myMcpServerClient = await MyMcpServerClientStrands.create(sessionId);
+export const getAgent = async () => {
+  const myMcpServerClient = await MyMcpServerClientStrands.create();
   return new Agent({
     systemPrompt: '...',
     tools: [myMcpServerClient],
@@ -81,10 +83,12 @@ export const getAgent = async (sessionId: string) => {
 };
 ```
 
-The `sessionId` parameter is plumbed through from the caller, ensuring consistency for [Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html).
+The AgentCore session ID is propagated to the MCP server automatically via the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header, so `create()` takes no arguments: the agent server binds the inbound request's session into an [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) context (`enterSessionContext` in the generated `router.ts`, or `runWithSessionId` in the A2A/AG-UI session middleware), and the connection client's fetch in `agentcore-fetch.ts` stamps it on every outbound call — ensuring consistency for [Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html).
 
 ## Infrastructure
 
+<Snippet name="connection/infra-project-prerequisite" />
+
 <Infrastructure>
 <Fragment slot="cdk">
 After running the connection generator, you need to grant the agent permission to invoke the MCP server:
@@ -97,12 +101,14 @@ const myAgent = new MyAgent(this, 'MyAgent');
 mcpServer.grantInvokeAccess(myAgent);
 ```
 
+`grantInvokeAccess` wires up the AgentCore invoke actions (`InvokeAgentRuntime`, `InvokeAgentRuntimeForUser` and `InvokeAgentRuntimeWithWebSocketStream`) on the MCP server's runtime ARN.
+
 The MCP server's AgentCore runtime ARN is automatically registered in the `agentcore` 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">
 After running the connection generator, you need to grant the agent permission to invoke the MCP server in your Terraform configuration:
 
-```hcl title="packages/infra/src/main.tf" {9-25}
+```hcl title="packages/infra/src/main.tf" {9-31}
 module "inventory_mcp_server" {
   source = "../../common/terraform/src/app/mcp-servers/inventory-mcp"
 }
@@ -117,9 +123,15 @@ resource "aws_iam_policy" "agent_invoke_mcp" {
   policy = jsonencode({
     Version = "2012-10-17"
     Statement = [{
-      Effect   = "Allow"
-      Action   = "bedrock-agentcore:InvokeAgent"
-      Resource = module.inventory_mcp_server.agent_core_runtime_arn
+      Effect = "Allow"
+      Action = [
+        "bedrock-agentcore:InvokeAgentRuntime",
+        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
+      ]
+      Resource = [
+        module.inventory_mcp_server.agent_core_runtime_arn,
+        "${module.inventory_mcp_server.agent_core_runtime_arn}/*",
+      ]
     }]
   })
 }

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

@@ -36,13 +36,13 @@ Select your Agent project as the source and your relational database project as
 
 ## Generator Output
 
-The generator modifies two files in your agent's source directory:
+The generator modifies the following files in your agent's source directory:
 
 <FileTree>
 
 - packages/my-service/src/my-agent
   - agent.ts Prisma client fetched inside `getAgent` and available to tools
-  - Dockerfile RDS CA bundle installed for SSL connections to Aurora
+  - Dockerfile RDS CA bundle installed for SSL connections to Aurora (only when the agent's `infra` is `agentcore-ecr`)
 
 </FileTree>
 

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

@@ -47,13 +47,17 @@ 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) }],
-    };
-  });
+  server.registerTool(
+    'list_examples',
+    { description: 'List all example items', inputSchema: {} },
+    async () => {
+      const entity = await createExampleEntity();
+      const result = await entity.scan.go();
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(result.data) }],
+      };
+    },
+  );
 
   return server;
 };

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

@@ -36,13 +36,13 @@ Select your MCP server project as the source and your relational database projec
 
 ## Generator Output
 
-The generator modifies two files in your MCP server's source directory:
+The generator modifies the following files in your MCP server's source directory:
 
 <FileTree>
 
 - packages/my-service/src/my-mcp
   - server.ts Prisma client fetched and available to all tools registered inside `createServer`
-  - Dockerfile RDS CA bundle installed for SSL connections to Aurora
+  - Dockerfile RDS CA bundle installed for SSL connections to Aurora (only when the MCP server's `infra` is `agentcore-ecr`)
 
 </FileTree>
 
@@ -52,11 +52,12 @@ Additionally, the `<mcp-server-name>-dev` target is updated to depend on the dat
 
 The Prisma client is fetched inside `createServer` and available to all tools and resources registered there:
 
-```ts title="packages/my-service/src/my-mcp/server.ts" {1,4}
+```ts title="packages/my-service/src/my-mcp/server.ts" {1,4,5}
 import { getPrisma as getMyDb } from '@my-scope/my-db';
 
 export const createServer = async () => {
   const myDb = await getMyDb();
+  myDb.$on('error', console.error);
   const server = new McpServer({ name: 'my-service', version: '1.0.0' });
   // register tools/resources that use myDb
   return server;

package/docs/guides/docker-bundling.mdx

@@ -133,11 +133,18 @@ Some npm packages cannot be bundled because they rely on dynamic `require`, nati
 
 ### Dockerfile
 
-Create a `Dockerfile` in your project source directory. The file does nothing more than `COPY` the bundle into a Node base image, plus `npm install` any `external` packages that could not be bundled. Place the `RUN npm install` step **before** the `COPY`, so Docker can cache the installed `node_modules` layer and only re-run it when the dependency list actually changes:
+Create a `Dockerfile` in your project source directory. The file does nothing more than [apply the base image's security updates](#apply-the-distributions-security-updates), `COPY` the bundle into a Node base image, plus `npm install` any `external` packages that could not be bundled. Place the `RUN npm install` step **before** the `COPY`, so Docker can cache the installed `node_modules` layer and only re-run it when the dependency list actually changes:
 
 ```dockerfile
 FROM public.ecr.aws/docker/library/node:lts
 
+# Apply the distribution's security updates: base image tags lag behind the
+# security suite, so their OS packages carry vulnerabilities that already have a
+# published fix.
+RUN apt-get update && \
+    apt-get upgrade -y --no-install-recommends && \
+    rm -rf /var/lib/apt/lists/*
+
 WORKDIR /app
 
 # Install packages that cannot be bundled (declared as "external" in rolldown.config.ts).
@@ -236,11 +243,18 @@ Running `nx bundle my-project` produces `dist/packages/my-project/bundle-arm/` c
 
 ### Dockerfile
 
-The `Dockerfile` simply copies the bundle into a Python base image. Because `uv` already installed all dependencies into the bundle directory, you do not need to run `pip install` inside the image:
+The `Dockerfile` [applies the base image's security updates](#apply-the-distributions-security-updates), then copies the bundle into a Python base image. Because `uv` already installed all dependencies into the bundle directory, you do not need to run `pip install` inside the image:
 
 ```dockerfile
 FROM public.ecr.aws/docker/library/python:3.14-slim
 
+# Apply the distribution's security updates: base image tags lag behind the
+# security suite, so their OS packages carry vulnerabilities that already have a
+# published fix.
+RUN apt-get update && \
+    apt-get upgrade -y --no-install-recommends && \
+    rm -rf /var/lib/apt/lists/*
+
 WORKDIR /app
 
 # Copy bundled package (source + installed dependencies)
@@ -288,7 +302,13 @@ This clears the output directory, then copies both the bundle contents and the `
 
 It's good practice to scan your images for known vulnerabilities. The generators that follow this pattern add a `trivy` target which scans the built image with [Trivy](https://trivy.dev/), running from the [ECR-hosted Trivy image](https://gallery.ecr.aws/aquasecurity/trivy), and exits non-zero on `HIGH` or `CRITICAL` findings.
 
-Add a `trivy` target which `dependsOn` your `docker` target. It saves the built image to a tarball and scans it via a workspace-relative bind mount, so the same command works under both `docker` and `finch`:
+The target copies a `.trivyignore` from the root of your project into the scan directory and passes it to Trivy with `--ignorefile`, so create that file first — an empty one is fine, and it is where you [suppress findings](#suppressing-findings) later:
+
+```bash
+touch packages/my-project/.trivyignore
+```
+
+Then add a `trivy` target which `dependsOn` your `docker` target. It saves the built image to a tarball and scans it via a workspace-relative bind mount, so the same command works under both `docker` and `finch`:
 
 <Code lang="json" code={trivyTarget} />
 

package/docs/guides/fastapi.mdx

@@ -17,6 +17,7 @@ import PackageManagerShortCommand from '@components/package-manager-short-comman
 import Infrastructure from '@components/infrastructure.astro';
 import Snippet from '@components/snippet.astro';
 import OptionFilter from '@components/option-filter.astro';
+import { PY_VERSIONS } from '../../../../../../packages/nx-plugin/src/utils/versions';
 
 [FastAPI](https://fastapi.tiangolo.com/) is a framework for building APIs in Python.
 
@@ -86,12 +87,12 @@ class Item(BaseModel):
 @app.get("/items/{item_id}")
 @tracer.capture_method
 def get_item(item_id: int) -> Item:
-    return Item(name=...)
+    return Item(name=f"Item {item_id}")
 
 @app.post("/items")
 @tracer.capture_method
-def create_item(item: Item):
-    return ...
+def create_item(item: Item) -> Item:
+    return item
 ```
 
 The generator sets up several features automatically:
@@ -191,7 +192,11 @@ When your API is protected by authentication, your route handlers often need to
 As an example, let's add a `/me` endpoint that returns details about the calling user. We'll implement the extraction as a [FastAPI dependency](https://fastapi.tiangolo.com/tutorial/dependencies/) so it can be reused across routes. The shape of the request context — and therefore how you extract the identity — depends on both your selected `auth` method and whether you deployed a REST or HTTP API.
 
 <OptionFilter when={{ auth: 'iam' }} description="Identity extraction for IAM-authenticated APIs">
-For `IAM` authentication, we look up the caller in Cognito using the sub extracted from the API Gateway request context. Create `identity.py` alongside `main.py`:
+For `IAM` authentication, we look up the caller in Cognito using the sub extracted from the API Gateway request context, which requires `boto3`. Add it to your API project:
+
+<NxCommands commands={[`run my-api:add boto3${PY_VERSIONS.boto3}`]} />
+
+Create `identity.py` alongside `main.py`:
 
 <Tabs syncKey="http-rest">
 <TabItem label="REST API" _filter={{ infra: 'rest-lambda' }}>
@@ -652,6 +657,8 @@ If you are actively working on both your CDK infrastructure and FastAPI together
     'run @<scope>/common-constructs:"generate:<ApiName>-metadata"',
   ]}
 />
+
+`nx watch` requires the [Nx daemon](https://nx.dev/concepts/nx-daemon), which is enabled by default but switched off inside CI, Docker containers and sandboxed environments. Where it is off, the command exits with `Daemon is not running` — set `NX_DAEMON=true` to enable it.
 :::
 </Fragment>
 <Fragment slot="terraform">
@@ -717,7 +724,7 @@ The key outputs from the API module that you can use for IAM policies are:
 
 The generator configures a local development server that you can run with:
 
-<NxCommands commands={['serve my-api']} />
+<NxCommands commands={['serve <project-name>']} />
 
 This starts a local FastAPI development server with:
 
@@ -725,6 +732,10 @@ This starts a local FastAPI development server with:
 - Interactive API documentation at `/docs` or `/redoc`
 - OpenAPI schema at `/openapi.json`
 
+:::note[Project Names]
+Python project names use underscores, so an API generated with `--name=MyApi` is addressed as `my_api` (or by its fully qualified name, `<scope>.my_api`). The port the server listens on is assigned per project — read it from the `serve` target in your project's `project.json`.
+:::
+
 ## Invoking your FastAPI
 
 To invoke your API from a React website, you can use the <Link path="guides/connection/react-fastapi">`connection` generator</Link>.