@aws/nx-plugin-mcp 1.0.0-rc.4 → 1.0.0-rc.41

package/docs/guides/terraform-project.mdx

@@ -108,7 +108,7 @@ You can start writing your Terraform infrastructure inside `src/main.tf`, for ex
 
 ### Cross project dependencies
 
-If you wanted to execute a module from a seperate project (lib), you could do so as follows:
+If you wanted to execute a module from a separate project (lib), you could do so as follows:
 
 ```
 module "lib_module" {

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" />
 
@@ -138,7 +140,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 +480,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 +505,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,8 +543,8 @@ 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>
 
@@ -726,6 +728,12 @@ 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" />
@@ -817,3 +825,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';
@@ -261,19 +263,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 +336,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`.
@@ -318,7 +366,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 +400,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 +423,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 +482,95 @@ 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"
+  />
+</CardGrid>