@aws/nx-plugin-mcp 1.0.0-rc.20 → 1.0.0-rc.22

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';
@@ -472,3 +474,73 @@ 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>
+
+## 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>

package/docs/guides/ts-dynamodb.mdx

@@ -4,7 +4,9 @@ description: Create a TypeScript DynamoDB project
 generator: ts#dynamodb
 ---
 
-import { FileTree } from '@astrojs/starlight/components';
+import { FileTree, 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';
@@ -144,15 +146,42 @@ const result = await entity.query.primary({ id: '123' }).go();
 When running in AWS, `resolveTableName()` fetches the table name from AWS AppConfig using the `RUNTIME_CONFIG_APP_ID` environment variable. Projects built with this plugin (tRPC APIs, Smithy APIs, agents, MCP servers) already have this variable configured automatically. For other TypeScript projects, ensure `RUNTIME_CONFIG_APP_ID` is set in the runtime environment with the AppConfig application ID provisioned by your infrastructure. For more information, see the <Link path="guides/runtime-config">Runtime Configuration guide</Link>.
 :::
 
-### Connection Generators
-
-For specific project types, use the `connection` generator to automatically wire up local development dependencies so DynamoDB Local starts automatically alongside your project:
-
-- <Link path="guides/connection/trpc-dynamodb">tRPC API → DynamoDB</Link>
-- <Link path="guides/connection/smithy-dynamodb">Smithy API → DynamoDB</Link>
-- <Link path="guides/connection/ts-agent-dynamodb">TypeScript Agent → DynamoDB</Link>
-- <Link path="guides/connection/ts-mcp-server-dynamodb">MCP Server → DynamoDB</Link>
-
 ## Deploying your Table
 
 <Snippet name="dynamodb/deploying-table" parentHeading="Deploying your Table" />
+
+## 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="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"
+  />
+</CardGrid>

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

@@ -4,7 +4,9 @@ description: Generate a TypeScript Model Context Protocol (MCP) server for provi
 generator: ts#mcp-server
 ---
 
-import { FileTree } from '@astrojs/starlight/components';
+import { FileTree, 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';
@@ -171,3 +173,47 @@ A `docker` target is also generated which prepares the docker context for all MC
 
 <Snippet name="mcp/observability" parentHeading="Observability" />
 </OptionFilter>
+
+## 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="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="Python Agent to MCP"
+    description="Connect a Python Agent to an MCP server"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-agent-mcp`}
+    source="strands"
+    sourceBadge="python"
+    target="mcp"
+  />
+  <ConnectionCard
+    title="MCP Server to Relational Database"
+    description="Connect a TypeScript MCP Server to an Aurora relational database"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-mcp-server-rdb`}
+    source="mcp"
+    target="aurora"
+  />
+  <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="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"
+  />
+</CardGrid>

package/docs/guides/ts-rdb.mdx

@@ -4,7 +4,9 @@ description: Create a relational database project
 generator: ts#rdb
 ---
 
-import { FileTree } from '@astrojs/starlight/components';
+import { FileTree, 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';
@@ -243,15 +245,6 @@ const users = await prisma.user.findMany({ orderBy: { id: 'asc' } });
 
 The Prisma client exposes fully typed models derived from your `prisma/models/` schema, giving you end-to-end type safety from the database all the way through to your API response.
 
-### Connection Generators
-
-For specific project types, use the `connection` generator to automatically wire up the database — it handles imports, context injection, and local development dependencies:
-
-- <Link path="guides/connection/trpc-rdb">tRPC API → Relational Database</Link>
-- <Link path="guides/connection/smithy-rdb">Smithy API → Relational Database</Link>
-- <Link path="guides/connection/ts-agent-rdb">TypeScript Agent → Relational Database</Link>
-- <Link path="guides/connection/ts-mcp-server-rdb">MCP Server → Relational Database</Link>
-
 ## Deploying your Database
 
 The relational database generator creates CDK or Terraform infrastructure based on your selected `iacProvider`.
@@ -805,3 +798,39 @@ Be cautious with tasks running longer than 15 minutes. If the MySQL client needs
 For long-running tasks such as batch jobs or data migrations, call `getPrisma()` at the start of each unit of work rather than once for the entire operation. Because `getPrisma()` always creates a fresh client and fetches a new IAM token for MySQL, this ensures each connection authenticates with a valid token.
 
 </OptionFilter>
+
+## 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="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="Smithy API to Relational Database"
+    description="Connect a Smithy API to an Aurora relational database"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/smithy-rdb`}
+    source="smithy"
+    target="aurora"
+  />
+  <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="MCP Server to Relational Database"
+    description="Connect a TypeScript MCP Server to an Aurora relational database"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-mcp-server-rdb`}
+    source="mcp"
+    target="aurora"
+  />
+</CardGrid>

package/docs/guides/ts-smithy-api.mdx

@@ -7,7 +7,9 @@ when:
   infra: [rest-lambda]
 ---
 
-import { FileTree } from '@astrojs/starlight/components';
+import { FileTree, 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';
@@ -401,6 +403,151 @@ export const MyOperation: MyOperationHandler<ServiceContext> = async (input) =>
 };
 ```
 
+### Accessing the Calling User
+
+When your API is protected by authentication, your operations often need to know who is calling. The recommended approach is to resolve the caller's identity once in the handler and pass it through the [service context](#service-context) for consumption by specific operations.
+
+We'll model the unauthorized case as a Smithy error so it serializes to a proper `403` response. Add it to your model, for example in `model/src/operations/errors.smithy`, and reference it on any operation that requires identity:
+
+```smithy
+$version: "2.0"
+
+namespace your.namespace
+
+/// Thrown when the calling user cannot be determined
+@error("client")
+@httpError(403)
+structure UnauthorizedError {
+    @required
+    message: String
+}
+```
+
+First, expose the resolved identity on the service context in `src/context.ts`. We provide it as a function so that the `UnauthorizedError` is thrown from within an operation (where the Server SDK serializes it to a `403`), rather than from the handler:
+
+```ts {4-7,15} ins={4-7,15}
+import { Logger } from '@aws-lambda-powertools/logger';
+import { Metrics } from '@aws-lambda-powertools/metrics';
+import { Tracer } from '@aws-lambda-powertools/tracer';
+
+export interface Identity {
+  sub: string;
+  username: string;
+}
+
+/**
+ * Context provided to all operations.
+ */
+export interface ServiceContext {
+  tracer: Tracer;
+  logger: Logger;
+  metrics: Metrics;
+  getIdentity: () => Promise<Identity>;
+}
+```
+
+Next, write the resolver in `src/identity.ts`. It throws `UnauthorizedError` when the caller cannot be determined. The implementation depends on your selected `auth` method:
+
+<OptionFilter when={{ auth: 'iam' }} description="Identity resolution for IAM-authenticated APIs">
+For `IAM` authentication, we look up the caller in Cognito using the sub extracted from the API Gateway event:
+
+```ts
+import { CognitoIdentityProvider } from '@aws-sdk/client-cognito-identity-provider';
+import type { APIGatewayProxyEvent } from 'aws-lambda';
+import { Identity } from './context.js';
+import { UnauthorizedError } from './generated/ssdk/index.js';
+
+const cognito = new CognitoIdentityProvider();
+
+export const getIdentity = async (
+  event: APIGatewayProxyEvent,
+): Promise<Identity> => {
+  const cognitoAuthenticationProvider =
+    event.requestContext?.identity?.cognitoAuthenticationProvider;
+
+  let sub: string | undefined = undefined;
+  if (cognitoAuthenticationProvider) {
+    const providerParts = cognitoAuthenticationProvider.split(':');
+    sub = providerParts[providerParts.length - 1];
+  }
+
+  if (!sub) {
+    throw new UnauthorizedError({ message: 'Unable to determine calling user' });
+  }
+
+  const { Users } = await cognito.listUsers({
+    // Assumes user pool id is configured in lambda environment
+    UserPoolId: process.env.USER_POOL_ID!,
+    Limit: 1,
+    Filter: `sub="${sub}"`,
+  });
+
+  if (!Users || Users.length !== 1) {
+    throw new UnauthorizedError({ message: `No user found with subjectId ${sub}` });
+  }
+
+  return { sub, username: Users[0].Username! };
+};
+```
+</OptionFilter>
+
+<OptionFilter when={{ auth: 'cognito' }} description="Identity resolution for Cognito-authenticated APIs">
+With `auth: 'cognito'`, the API Gateway Cognito User Pools authorizer verifies the JWT that the caller supplies in the `Authorization` header and places the verified claims on the event at `event.requestContext.authorizer.claims`:
+
+```ts
+import type { APIGatewayProxyEvent } from 'aws-lambda';
+import { Identity } from './context.js';
+import { UnauthorizedError } from './generated/ssdk/index.js';
+
+export const getIdentity = async (
+  event: APIGatewayProxyEvent,
+): Promise<Identity> => {
+  const claims = event.requestContext?.authorizer?.claims as
+    | Record<string, string>
+    | undefined;
+
+  const sub = claims?.sub;
+  const username = claims?.username;
+
+  if (!sub || !username) {
+    throw new UnauthorizedError({ message: 'Unable to determine calling user' });
+  }
+
+  return { sub, username };
+};
+```
+
+:::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>
+
+Then wire the resolver into the context in `src/handler.ts`:
+
+```ts {2,8} ins={2,8}
+import { Service } from './service.js';
+import { getIdentity } from './identity.js';
+// ...
+const httpResponse = await serviceHandler.handle(httpRequest, {
+  tracer,
+  logger,
+  metrics,
+  getIdentity: () => getIdentity(event),
+});
+```
+
+We can now use the resolved identity in an operation, for example in `src/operations/echo.ts`:
+
+```ts
+import { ServiceContext } from '../context.js';
+import { Echo as EchoOperation } from '../generated/ssdk/index.js';
+
+export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
+  const identity = await ctx.getIdentity();
+  return { message: `${identity.username} says ${input.message}` };
+};
+```
+
 ## Building and Code Generation
 
 The Smithy model project uses [Docker](https://www.docker.com/) to build the Smithy artifacts and generate the TypeScript Server SDK:
@@ -662,3 +809,31 @@ resource "aws_iam_role_policy_attachment" "api_invoke_access" {
 ## Invoking your Smithy API
 
 To invoke your API from a React website, you can use the <Link path="guides/connection/react-smithy">`connection`</Link> generator, which provides type-safe client generation from your Smithy model.
+
+## 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 Smithy API"
+    description="Call a Smithy API from a React website"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-smithy`}
+    source="react"
+    target="smithy"
+  />
+  <ConnectionCard
+    title="Smithy API to Relational Database"
+    description="Connect a Smithy API to an Aurora relational database"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/smithy-rdb`}
+    source="smithy"
+    target="aurora"
+  />
+  <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"
+  />
+</CardGrid>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin-mcp",
-  "version": "1.0.0-rc.20",
+  "version": "1.0.0-rc.22",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",

package/src/py/agent/schema.json

@@ -19,7 +19,7 @@
       "type": "string",
       "description": "The agent SDK to use.",
       "x-prompt": "Which agent SDK would you like to use?",
-      "enum": ["strands"],
+      "enum": ["strands", "langchain"],
       "default": "strands",
       "x-priority": "important"
     },