@aws/nx-plugin-mcp 1.0.0-rc.7 → 1.0.0-rc.71

package/docs/guides/trpc.mdx

@@ -1,12 +1,14 @@
 ---
 title: tRPC
 description: Reference documentation for tRPC
-generator: ts#trpc-api
+generator: ts#api
 when:
   framework: [trpc]
   infra: [rest-lambda, http-lambda]
 ---
-import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
+import { FileTree, Tabs, TabItem, CardGrid } from '@astrojs/starlight/components';
+import Astro from '@astrojs/react';
+import ConnectionCard from '@components/connection-card.astro';
 import Link from '@components/link.astro';
 import RunGenerator from '@components/run-generator.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
@@ -25,11 +27,11 @@ The tRPC API generator creates a new tRPC API with AWS CDK or Terraform infrastr
 
 You can generate a new tRPC API in two ways:
 
-<RunGenerator generator="ts#trpc-api" />
+<RunGenerator generator="ts#api" requiredParameters={{ framework: 'trpc' }} />
 
 ### Options
 
-<GeneratorParameters generator="ts#trpc-api" />
+<GeneratorParameters generator="ts#api" />
 
 <Snippet name="api/api-choice-note" />
 
@@ -64,6 +66,7 @@ The generator will create the following project structure in the `<directory>/<a
     - client
       - index.ts Type-safe client for machine-to-machine API calls
   - tsconfig.json TypeScript configuration
+  - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
 
 </FileTree>
@@ -138,7 +141,7 @@ The example `echo` procedure is generated for you in `src/procedures/echo.ts`:
 export const echo = publicProcedure
   .input(EchoInputSchema)
   .output(EchoOutputSchema)
-  .query((opts) => ({ result: opts.input.message }));
+  .query((opts) => ({ message: opts.input.message }));
 ```
 
 To break down the above:
@@ -478,7 +481,7 @@ export interface IIdentityContext {
 
 Note that we define an additional _optional_ property on the context. tRPC manages ensuring that this is defined in procedures which have correctly configured this middleware.
 
-Next, the middleware itself. The generator wires the authorizer to accept ID tokens, so `cognito:username` is the canonical username claim; we fall back to `username` for access tokens in case you reconfigure the authorizer:
+Next, the middleware itself:
 
 ```ts
 import { initTRPC, TRPCError } from '@trpc/server';
@@ -503,7 +506,7 @@ export const createIdentityPlugin = () => {
       | undefined;
 
     const sub = claims?.sub;
-    const username = claims?.['cognito:username'] ?? claims?.username;
+    const username = claims?.username;
 
     if (!sub || !username) {
       throw new TRPCError({
@@ -541,14 +544,14 @@ export const me = publicProcedure
   }));
 ```
 
-:::tip[Verifying the token]
-You don't need `aws-jwt-verify` or any other JWT-verification library here — the API Gateway Cognito User Pools authorizer has already verified the signature, issuer, audience, and expiry by the time your Lambda runs. If any of those checks fail, API Gateway returns `401 Unauthorized` and your handler is never invoked.
+:::tip[No token verification required]
+You don't need `aws-jwt-verify` or any other JWT-verification library here — the API Gateway Cognito User Pools authorizer has already verified the signature, issuer, scopes, and expiry by the time your Lambda runs. If any of those checks fail, API Gateway returns `401 Unauthorized` and your handler is never invoked.
 :::
 </OptionFilter>
 
 ## Deploying your tRPC API
 
-The tRPC API generator creates CDK or Terraform infrastructure as code based on your selected `iacProvider`. You can use this to deploy your tRPC API.
+The tRPC API generator creates CDK or Terraform infrastructure as code based on your selected `iac`. You can use this to deploy your tRPC API.
 
 <Infrastructure>
 <Fragment slot="cdk">
@@ -556,7 +559,7 @@ The CDK construct for deploying your API lives in the `common/constructs` folder
 
 <OptionFilter when={{ auth: ['iam', 'custom'] }} description="CDK usage for IAM or Custom authentication">
 ```ts {6-8}
-import { MyApi } from ':my-scope/common-constructs';
+import { MyApi } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -574,8 +577,8 @@ When using `Custom` auth, the construct creates a Lambda Authorizer internally f
 </OptionFilter>
 
 <OptionFilter when={{ auth: 'cognito' }} description="CDK usage with Cognito authentication — pass the identity construct">
-```ts {6,9}
-import { MyApi, UserIdentity } from ':my-scope/common-constructs';
+```ts {6,10}
+import { MyApi, UserIdentity } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -630,7 +633,7 @@ module "my_api" {
 </OptionFilter>
 
 <OptionFilter when={{ auth: 'cognito' }} description="Terraform usage with Cognito authentication — supply user pool and client">
-```hcl {1-3, 8-9}
+```hcl {1-3, 8, 10-11}
 module "asset_bucket" {
   source = "../../common/terraform/src/core/asset-bucket"
 }
@@ -726,12 +729,18 @@ When using `Custom` auth, your API is protected by a Lambda Authorizer that **de
 <Snippet name="api/waf-configuration" parentHeading="WAF" />
 </OptionFilter>
 
+<OptionFilter when={{ infra: 'rest-lambda' }} description="Access logging — REST APIs log requests to CloudWatch by default">
+### Access logging
+
+<Snippet name="api/access-logging" parentHeading="Access logging" />
+</OptionFilter>
+
 ### Integrations
 
 <Snippet name="api/type-safe-api-integrations" parentHeading="Integrations" />
 
 :::tip[CDK Type-Safe Integrations]
-If you selected CDK for your `iacProvider`, when you add or remove a procedure in your tRPC API, these changes will be reflected immediately in the CDK construct without the need to rebuild.
+If you selected CDK for your `iac`, when you add or remove a procedure in your tRPC API, these changes will be reflected immediately in the CDK construct without the need to rebuild.
 :::
 
 <OptionFilter when={{ auth: 'iam' }} description="Granting API invoke access — IAM-authenticated APIs only">
@@ -805,7 +814,7 @@ This will automatically reload when you make changes to your API.
 You can create a tRPC client to invoke your API in a type-safe manner. If you are calling your tRPC API from another backend, you can use the client in `src/client/index.ts`, for example:
 
 ```ts
-import { createMyApiClient } from ':my-scope/my-api';
+import { createMyApiClient } from '@my-scope/my-api';
 
 const client = createMyApiClient({ url: 'https://my-api-url.example.com/' });
 
@@ -817,3 +826,31 @@ If you are calling your API from a React website, consider using the <Link path=
 ## More Information
 
 For more information about tRPC, please refer to the [tRPC documentation](https://trpc.io/docs).
+
+## Connections
+
+Use the <Link path="guides/connection">`connection`</Link> generator to integrate this project with others in your workspace. The following connections involve this project:
+
+<CardGrid>
+  <ConnectionCard
+    title="React to tRPC"
+    description="Call a tRPC API from a React website"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-trpc`}
+    source="react"
+    target="trpc"
+  />
+  <ConnectionCard
+    title="tRPC API to Relational Database"
+    description="Connect a tRPC API to an Aurora relational database"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/trpc-rdb`}
+    source="trpc"
+    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"
+  />
+</CardGrid>

package/docs/guides/ts-agent.mdx

@@ -4,7 +4,9 @@ description: Generate a TypeScript Agent for building AI agents with tools and d
 generator: ts#agent
 ---
 
-import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
+import { FileTree, Tabs, TabItem, CardGrid } from '@astrojs/starlight/components';
+import Astro from '@astrojs/react';
+import ConnectionCard from '@components/connection-card.astro';
 import RunGenerator from '@components/run-generator.astro';
 import NxCommands from '@components/nx-commands.astro';
 import Link from '@components/link.astro';
@@ -58,6 +60,7 @@ The generator will add the following files to your existing TypeScript project.
         - init.ts tRPC initialization
         - router.ts tRPC router with agent procedures
         - agent.ts Main agent definition with sample tools
+        - session.ts Resolves the SessionManager used to persist conversation state
         - client.ts Vended client for invoking your agent
         - agent-core-trpc-client.ts Client factory for connecting to agents on AgentCore Runtime
         - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
@@ -77,6 +80,7 @@ The entry point uses the [Strands A2A Express Server](https://strandsagents.com/
       - agent/ (or custom name if specified)
         - index.ts A2A Express server entry point
         - agent.ts Main agent definition with sample tools
+        - session.ts Resolves the SessionManager used to persist conversation state
         - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
     - package.json Updated with Strands and Express dependencies
     - project.json Updated with agent serve targets
@@ -94,6 +98,7 @@ The entry point uses [`@ag-ui/aws-strands`](https://www.npmjs.com/package/@ag-ui
       - agent/ (or custom name if specified)
         - index.ts AG-UI server entry point (Express + SSE)
         - agent.ts Main agent definition with sample tools
+        - session.ts Resolves the SessionManager used to persist conversation state
         - Dockerfile Entry point for hosting your agent (excluded when `infra` is set to `None`)
     - package.json Updated with Strands and AG-UI dependencies
     - project.json Updated with agent serve targets
@@ -183,7 +188,7 @@ const letterCounter = tool({
 });
 
 // Add tools to your agent
-export const getAgent = async (sessionId: string) => {
+export const getAgent = async () => {
   return new Agent({
     systemPrompt: 'You are a helpful assistant with access to various tools.',
     tools: [letterCounter],
@@ -261,19 +266,61 @@ Most users will not need to modify `index.ts` — edit `agent.ts` to change tool
 
 ### Local Development
 
-The generator configures a target named `<your-agent-name>-serve`, which starts your Agent locally for development and testing.
+To run your Agent (and everything connected to it) locally, use the project's `dev` target:
 
-<NxCommands commands={['agent-serve your-project']} />
+<NxCommands commands={['dev your-project']} />
 
-This command uses `tsx --watch` to automatically restart the server when files change. The agent will be available at `http://localhost:8081` (or the assigned port if you have multiple agents).
+If you have added multiple components to your project (agents, MCP servers, etc.), this starts them all. To run just this agent, target its `<your-agent-name>-dev` target:
+
+<NxCommands commands={['agent-dev your-project']} />
+
+This uses `tsx --watch` to automatically restart the server when files change. The agent will be available at `http://localhost:8081` (or the assigned port if you have multiple agents).
 
 ### Chat with Your Agent
 
-The generator configures a `<your-agent-name>-chat` Nx target that depends on `<your-agent-name>-serve-local`. Running it starts the agent locally and drops you into an interactive terminal chat:
+The generator configures a `<your-agent-name>-chat` Nx target that drops you into an interactive terminal chat with your agent.
+
+The chat target runs standalone. By default it connects to your locally running agent, so start the agent's `<your-agent-name>-dev` target first (in a separate terminal):
+
+<NxCommands commands={['agent-dev your-project']} />
+
+Then, in another terminal, start the chat:
 
 <NxCommands commands={['run your-project:agent-chat']} />
 
-For **HTTP** (tRPC over WebSocket) agents, the generator also emits a tiny `scripts/<your-agent-name>/chat.ts` that wraps the generated `<Agent>Client.local({ url })` so you can customize it as you evolve the agent's input shape.
+The generator emits a `scripts/<your-agent-name>/chat.ts` for every protocol. You can customize it as you evolve the agent's input shape. It connects to the local agent by default, or to your deployed agent when `RUNTIME_CONFIG_APP_ID` is set (see [Chat with your deployed agent](#chat-with-your-deployed-agent) below).
+
+<OptionFilter when={{ infra: 'agentcore' }} description="Deployed agent chat details">
+#### Chat with your deployed agent
+
+To chat with your agent deployed to Bedrock AgentCore, set the `RUNTIME_CONFIG_APP_ID` environment variable to the AppConfig application id of the deployment (output as `RuntimeConfigApplicationId` by the deployed stack). The chat script resolves your agent's runtime ARN from runtime configuration and connects to the deployed endpoint:
+
+<Tabs syncKey="auth">
+<TabItem label="IAM" _filter={{ auth: 'iam' }}>
+For IAM-authenticated agents, requests are signed with [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) using your default AWS credentials. Ensure the environment has AWS credentials with permission to invoke the runtime:
+
+<NxCommands commands={['run your-project:agent-chat']} env={{ RUNTIME_CONFIG_APP_ID: '<app-id>' }} />
+</TabItem>
+
+<TabItem label="Cognito" _filter={{ auth: 'cognito' }}>
+For Cognito-authenticated agents, provide a Cognito access token via the `AGENT_ACCESS_TOKEN` environment variable, which is sent as a bearer token:
+
+<NxCommands commands={['run your-project:agent-chat']} env={{ RUNTIME_CONFIG_APP_ID: '<app-id>', AGENT_ACCESS_TOKEN: '<access-token>' }} />
+
+You can obtain an access token using the AWS CLI's `cognito-idp admin-initiate-auth` command, for example:
+
+```bash
+aws cognito-idp admin-initiate-auth \
+  --user-pool-id <user-pool-id> \
+  --client-id <user-pool-client-id> \
+  --auth-flow ADMIN_NO_SRP_AUTH \
+  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
+  --query 'AuthenticationResult.AccessToken' \
+  --output text
+```
+</TabItem>
+</Tabs>
+</OptionFilter>
 
 <OptionFilter when={{ infra: 'agentcore' }} description="Bedrock AgentCore Runtime deployment details">
 ## Deploying Your Agent to Bedrock AgentCore Runtime
@@ -292,6 +339,10 @@ The generator configures a `<your-agent-name>-docker` target which copies the `D
 
 A `docker` target is also generated which prepares the docker context for all agents if you have multiple defined.
 
+### Image Scanning
+
+<Snippet name="trivy-image-scan" parentHeading="Image Scanning" />
+
 ### Observability
 
 Your agent is automatically configured with observability using the [AWS Distro for Open Telemetry](https://aws.amazon.com/otel/) (ADOT), by configuring auto-instrumentation in your `Dockerfile`.
@@ -299,6 +350,29 @@ Your agent is automatically configured with observability using the [AWS Distro
 You can find traces in the CloudWatch AWS Console, by selecting "GenAI Observability" in the menu. Note that for traces to be populated you will need to enable [Transaction Search](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html).
 
 For more details, refer to the [AgentCore documentation on observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html).
+
+### Session Management
+
+The `session` option controls how your agent persists conversation state (message history, tool state, etc.) across invocations, using the Strands SDK's [SessionManager](https://strandsagents.com/docs/user-guide/concepts/agents/session-management/):
+
+- **`s3`** (default): The CDK/Terraform infrastructure provisions a dedicated S3 bucket for session data, encrypted with a dedicated KMS key and with all public access blocked; server access logs are delivered to a CloudWatch Logs log group via the same key. The agent's IAM role is granted read/write/list/delete access to the bucket and decrypt/generate-data-key access to the key, and the bucket name is registered alongside the agent's ARN in AppConfig runtime configuration.
+- **`in-memory`**: No bucket is provisioned. Conversation state is kept in memory only for the lifetime of the running process and does not survive restarts or scale-in.
+
+This is implemented in the generated `session.ts`, which exports a `getSessionManager()` function resolving a `SessionManager` for the current session.
+
+<OptionFilter when={{ protocol: 'ag-ui' }} description="AG-UI session wiring">
+Since AG-UI clones a template agent per conversation thread, `getSessionManager` is wired in as a `sessionManagerProvider` on the `StrandsAgent` config in `index.ts`, so a fresh `SessionManager` is resolved for each thread rather than baked into the shared template agent.
+</OptionFilter>
+
+<OptionFilter when={{ protocol: ['http', 'a2a'] }} description="HTTP/A2A session wiring">
+Since `withSessionId` already caches one `Agent` instance per session, `getSessionManager` is called directly inside `getAgent`'s `new Agent({ sessionManager: await getSessionManager() })` call in `agent.ts`.
+</OptionFilter>
+
+The session ID itself comes from the AgentCore Runtime session (propagated via the `x-amzn-bedrock-agentcore-runtime-session-id` header for A2A/AG-UI, or the WebSocket connection context for HTTP/tRPC) and is bound to an [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage)-based context so `getCurrentSessionId()` can resolve it anywhere in the request — including in any downstream MCP or A2A clients wired up via the <Link path="/guides/connection">`connection` generator</Link>, so the whole call chain shares a consistent session.
+
+:::note[Local Development]
+When running locally (`LOCAL_DEV=true`, set automatically by the `-dev` target), session data is always stored on disk under `tmp/agents/strands/<agent-name>` at the workspace root, regardless of the configured `session` option, for convenience.
+:::
 </OptionFilter>
 
 ## Invoking your Agent
@@ -318,7 +392,7 @@ import { AgentClient } from '../packages/<project>/src/agent/client.js';
 
 const client = AgentClient.local({ url: 'http://localhost:8081/ws' });
 
-client.invoke.subscribe({ message: 'what is 1 plus 1?' }, { onData: console.log });
+client.invoke.subscribe({ prompt: 'what is 1 plus 1?' }, { onData: console.log });
 ```
 
 :::tip[Quick Testing]
@@ -352,7 +426,7 @@ const client = AgentClient.withIamAuth({
   agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
 });
 
-client.invoke.subscribe({ message: 'what is 1 plus 1?' }, {
+client.invoke.subscribe({ prompt: 'what is 1 plus 1?' }, {
   onData: (message) => console.log(message),
   onError: (error) => console.error(error),
   onComplete: () => console.log('Done'),
@@ -375,7 +449,7 @@ const client = AgentClient.withJwtAuth({
   accessTokenProvider: async () => `<access-token>`,
 });
 
-client.invoke.subscribe({ message: 'what is 1 plus 1?' }, {
+client.invoke.subscribe({ prompt: 'what is 1 plus 1?' }, {
   onData: console.log,
 });
 ```
@@ -434,3 +508,102 @@ To invoke your AG-UI agent from a React website, use the <Link path="/guides/con
 
 Refer to the <Link path="/guides/connection/react-agui">`connection` generator guide</Link> for details about how the connection is set up.
 </OptionFilter>
+
+## Securing your Agent
+
+<Snippet name="agent/securing-your-agent" parentHeading="Securing your Agent" />
+
+```typescript
+// agent.ts
+import { Agent } from '@strands-agents/sdk';
+import { BedrockModel } from '@strands-agents/sdk/models/bedrock';
+
+const model = new BedrockModel({
+  modelId: process.env.MODEL_ID,
+  guardrailConfig: {
+    guardrailIdentifier: process.env.GUARDRAIL_ID!,
+    guardrailVersion: process.env.GUARDRAIL_VERSION ?? 'DRAFT',
+  },
+});
+
+const agent = new Agent({ model, /* ... */ });
+```
+
+See the Strands [Guardrails](https://strandsagents.com/docs/user-guide/safety-security/guardrails/) guide for more detail.
+
+## Connections
+
+Use the <Link path="guides/connection">`connection`</Link> generator to integrate this project with others in your workspace. The following connections involve this project:
+
+<CardGrid>
+  <ConnectionCard
+    title="React to TypeScript Agent"
+    description="Call a TypeScript Agent from a React website"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-ts-agent`}
+    source="react"
+    target="strands"
+    targetBadge="typescript"
+  />
+  <ConnectionCard
+    title="React to AG-UI Agent"
+    description="Call an Agent exposing the AG-UI protocol from a React website via CopilotKit"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-agui`}
+    source="react"
+    target="copilotkit"
+  />
+  <ConnectionCard
+    title="TypeScript Agent to MCP"
+    description="Connect a TypeScript Agent to an MCP server"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-mcp`}
+    source="strands"
+    sourceBadge="typescript"
+    target="mcp"
+  />
+  <ConnectionCard
+    title="TypeScript Agent to A2A Agent"
+    description="Connect a TypeScript Agent to a remote A2A agent"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-a2a`}
+    source="strands"
+    sourceBadge="typescript"
+    target="a2a"
+  />
+  <ConnectionCard
+    title="Python Agent to A2A Agent"
+    description="Connect a Python Agent to a remote A2A agent"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-agent-a2a`}
+    source="strands"
+    sourceBadge="python"
+    target="a2a"
+  />
+  <ConnectionCard
+    title="TypeScript Agent to Relational Database"
+    description="Connect a TypeScript Agent to an Aurora relational database"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-rdb`}
+    source="strands"
+    sourceBadge="typescript"
+    target="aurora"
+  />
+  <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="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="AgentCore Gateway to Agent"
+    description="Front an agent with an AgentCore Gateway as a runtime target"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/agentcore-gateway-agent`}
+    source="agentcore"
+    target="strands"
+  />
+</CardGrid>