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

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,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

@@ -1,23 +1,22 @@
 ---
-title: DynamoDB
-description: Create a DynamoDB project
+title: TypeScript DynamoDB
+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';
-import Infrastructure from '@components/infrastructure.astro';
-import NxCommands from '@components/nx-commands.astro';
 import Snippet from '@components/snippet.astro';
-import OptionFilter from '@components/option-filter.astro';
 
-This generator creates a new TypeScript project backed by [Amazon DynamoDB](https://aws.amazon.com/dynamodb/), using [ElectroDB](https://electrodb.dev/) for type-safe entity modelling. It generates the application code and infrastructure needed to provision and manage a DynamoDB table using AWS CDK or Terraform, with single-table design support and built-in local development via DynamoDB Local.
+This generator creates a new TypeScript DynamoDB project backed by [Amazon DynamoDB](https://aws.amazon.com/dynamodb/), using [ElectroDB](https://electrodb.dev/) for type-safe entity modelling. It generates the application code and infrastructure needed to provision and manage a DynamoDB table using AWS CDK or Terraform, with single-table design support and built-in local development via DynamoDB Local.
 
 ## Usage
 
-### Generate a DynamoDB Project
+### Generate a TypeScript DynamoDB Project
 
 <RunGenerator generator="ts#dynamodb" />
 
@@ -30,65 +29,38 @@ This generator creates a new TypeScript project backed by [Amazon DynamoDB](http
 The generator creates the following project structure in the `<directory>/<name>` directory:
 
 <FileTree>
-  - scripts
-    - create-local-table.ts Creates the DynamoDB table in the local DynamoDB Local instance
-    - pull-image.ts Pulls the DynamoDB Local image
-    - start-container.ts Starts the DynamoDB Local container
   - src
     - index.ts Project entry point and exports
-    - constants.ts Local development constants and runtime config key
     - client.ts DynamoDB client singleton and table name resolution
     - entities
       - example.ts Example ElectroDB entity definition
       - index.ts Entity exports
+  - config.json Table configuration including GSI definitions and local development settings
   - project.json Project configuration and build targets
 </FileTree>
 
+The local development scripts are shared across all DynamoDB projects (both TypeScript and Python) and generated once into:
+
+<FileTree>
+  - packages/common/scripts/src/dynamodb
+    - create-local-table.ts Creates the DynamoDB table in the local DynamoDB Local instance
+    - pull-image.ts Pulls the DynamoDB Local image
+    - start-container.ts Starts the DynamoDB Local container
+</FileTree>
+
 ### Infrastructure
 
-<Snippet name="shared-constructs" />
-
-<Infrastructure>
-  <Fragment slot="cdk">
-    <FileTree>
-      - packages/common/constructs/src
-        - app
-          - dynamodb
-            - \<name>.ts Infrastructure specific to your table
-        - core
-          - dynamodb.ts Generic DynamoDB table construct
-    </FileTree>
-  </Fragment>
-  <Fragment slot="terraform">
-    <FileTree>
-      - packages/common/terraform/src
-        - app
-          - dynamodb
-            - \<name>
-              - \<name>.tf Module specific to your table
-        - core
-          - dynamodb
-            - dynamodb.tf Generic DynamoDB module
-    </FileTree>
-  </Fragment>
-</Infrastructure>
+<Snippet name="dynamodb/infrastructure" />
 
 ## Local Development
 
 ### Starting Local DynamoDB
 
-The generator configures a `serve-local` target that starts a [DynamoDB Local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html) instance and creates the table:
-
-<NxCommands commands={['run <project-name>:serve-local']} />
-
-This automatically:
-1. Pulls the DynamoDB Local image (`pull-image` target)
-2. Starts a container
-3. Creates a local table with pre-defined indexes
+<Snippet name="dynamodb/local-dev-start" />
 
 ### Data Modelling
 
-The generated project uses [ElectroDB](https://electrodb.dev/) for type-safe entity modelling on a single DynamoDB table. Add or update entity files under `src/entities/`, using the generated example entity as a starting point.
+The generated project uses [ElectroDB](https://electrodb.dev/) for type-safe entity modelling on a single DynamoDB table, following [DynamoDB's single-table design](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/data-modeling-foundations.html). Add or update entity files under `src/entities/`, using the generated example entity as a starting point.
 
 Example entity definition:
 
@@ -146,30 +118,18 @@ For more details, see the [ElectroDB entity documentation](https://electrodb.dev
 
 The generated `src/client.ts` exports two key utilities:
 
-- `getDynamoDBClient()` — returns a cached singleton `DynamoDBClient`. When `SERVE_LOCAL=true`, connects to the local DynamoDB Local instance; otherwise creates an AWS client using the default credential chain.
-- `resolveTableName()` — returns the DynamoDB table name. When `SERVE_LOCAL=true`, returns the local table name constant; otherwise fetches the name from AWS AppConfig using the `RUNTIME_CONFIG_APP_ID` environment variable and caches it for subsequent calls.
+- `getDynamoDBClient()` — returns a cached singleton `DynamoDBClient`. When `LOCAL_DEV=true`, connects to the local DynamoDB Local instance; otherwise creates an AWS client using the default credential chain.
+- `resolveTableName()` — returns the DynamoDB table name. When `LOCAL_DEV=true`, returns the local table name constant; otherwise fetches the name from AWS AppConfig using the `RUNTIME_CONFIG_APP_ID` environment variable and caches it for subsequent calls.
 
 ### Stopping Local DynamoDB
 
-Stopping `serve-local` (e.g. with `Ctrl+C`) automatically removes the DynamoDB Local container, but preserves the named volume so your data persists across restarts.
-
-:::caution[Windows]
-Due to limitations with signal handling on Windows, the container is not automatically removed when `serve-local` is stopped. You will need to remove it manually:
-
-```bash
-<engine> rm -f <scope>-dynamodb
-```
-
-Replace `<engine>` with your container engine (`docker` or `finch`) and `<scope>` with your Nx workspace scope (e.g. `proj`).
-:::
+<Snippet name="dynamodb/local-dev-windows" />
 
 ## Adding/Removing Global Secondary Indexes
 
-Start by updating `GLOBAL_SECONDARY_INDEXES` in `src/gsi.ts` — this is the source of truth for your GSI definitions, and on the next `serve-local` run the script will automatically add or remove indexes on the local table to reflect the new list. When using CDK, these changes are also automatically reflected in your AWS table on the next deployment.
+GSIs are defined in `config.json` at the project root under the `tableConfig.globalSecondaryIndexes` key. Add an entry for each GSI, following the [single-table design](https://electrodb.dev/en/core-concepts/single-table-relationships/) naming convention for GSI keys:
 
-<OptionFilter when={{ iac: 'terraform' }}>
-  Unlike CDK, changes to `src/gsi.ts` are not automatically reflected in your Terraform module. You must also manually update your Terraform module to add or remove the corresponding GSI definitions before deploying.
-</OptionFilter>
+<Snippet name="dynamodb/gsi-config" parentHeading="Adding/Removing Global Secondary Indexes" />
 
 ## Connecting to the Table
 
@@ -186,179 +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
 
-The DynamoDB generator creates CDK or Terraform infrastructure based on your selected `iac`.
-
-<Infrastructure>
-<Fragment slot="cdk">
-The CDK construct is created in `common/constructs`. Example usage:
-
-```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyTable } from ':my-scope/common-constructs';
-
-export class ApplicationStack extends Stack {
-  constructor(scope: Construct, id: string, props?: StackProps) {
-    super(scope, id, props);
-
-    const table = new MyTable(this, 'Table');
-  }
-}
-```
-
-This provisions a DynamoDB table with:
-- `pk` (partition key) and `sk` (sort key), both `String` type
-- 2 Global Secondary Indexes by default, as defined in `src/gsi.ts`
-- On-demand (`PAY_PER_REQUEST`) billing
-- Customer-managed KMS encryption with automatic key rotation
-- Point-in-time recovery enabled
-- Deletion protection enabled
-- Table name registered in Runtime Config under the `dynamodb` namespace in AWS AppConfig
-</Fragment>
-<Fragment slot="terraform">
-The Terraform module is created in `common/terraform`. Example usage:
-
-```hcl title="packages/infra/src/main.tf"
-module "my_table" {
-  source = "../../common/terraform/src/app/dynamodb/my-table"
-}
-```
-
-This provisions a DynamoDB table with:
-- `pk` (partition key) and `sk` (sort key), both `String` type
-- 2 Global Secondary Indexes by default, as defined in `src/gsi.ts`
-- On-demand (`PAY_PER_REQUEST`) billing
-- Customer-managed KMS encryption with automatic key rotation
-- Point-in-time recovery enabled
-- Deletion protection enabled
-- Table name registered in Runtime Config
-</Fragment>
-</Infrastructure>
-
-### Granting Access
-
-<Snippet name="connection/lambda-dynamodb-access" />
-
-### Deletion Protection
-
-Deletion protection is enabled by default to prevent accidental table deletion.
-
-#### Disable Deletion Protection
-
-Disable it for environments where table deletion is expected, such as short-lived development or preview stacks.
-
-<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', {
-  deletionProtection: false,
-});
-```
-</Fragment>
-<Fragment slot="terraform">
-
-```hcl title="packages/infra/src/main.tf"
-module "my_table" {
-  source                      = "../../common/terraform/src/app/dynamodb/my-table"
-  deletion_protection_enabled = false
-}
-```
-</Fragment>
-</Infrastructure>
-
-### Billing Mode
-
-The table defaults to on-demand (`PAY_PER_REQUEST`) billing. Switch to provisioned capacity for predictable, high-throughput workloads.
-
-<Infrastructure>
-<Fragment slot="cdk">
-
-```ts title="packages/infra/src/stacks/application-stack.ts"
-import { BillingMode } from 'aws-cdk-lib/aws-dynamodb';
-import { MyTable } from ':my-scope/common-constructs';
-
-const table = new MyTable(this, 'Table', {
-  billingMode: BillingMode.PROVISIONED,
-  readCapacity: 5,
-  writeCapacity: 5,
-});
-```
-</Fragment>
-<Fragment slot="terraform">
-
-```hcl title="packages/infra/src/main.tf"
-module "my_table" {
-  source       = "../../common/terraform/src/app/dynamodb/my-table"
-  billing_mode = "PROVISIONED"
-}
-```
-</Fragment>
-</Infrastructure>
-
-### Point-in-time Recovery
-
-[Point-in-time recovery](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Point-in-time-recovery.html) is enabled by default, allowing you to restore the table to any point in the last 35 days.
-
-#### Disable Point-in-time Recovery
-
-<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', {
-  pointInTimeRecoverySpecification: { pointInTimeRecoveryEnabled: false },
-});
-```
-</Fragment>
-<Fragment slot="terraform">
-
-```hcl title="packages/infra/src/main.tf"
-module "my_table" {
-  source                         = "../../common/terraform/src/app/dynamodb/my-table"
-  point_in_time_recovery_enabled = false
-}
-```
-</Fragment>
-</Infrastructure>
-
-### Encryption Key Rotation
-
-The KMS key used to encrypt the table has automatic key rotation enabled by default. Disable it if your security policy manages rotation externally.
-
-#### Disable Encryption Key Rotation
-
-<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', {
-  enableKeyRotation: false,
-});
-```
-</Fragment>
-<Fragment slot="terraform">
-
-```hcl title="packages/infra/src/main.tf"
-module "my_table" {
-  source              = "../../common/terraform/src/app/dynamodb/my-table"
-  enable_key_rotation = false
-}
-```
-</Fragment>
-</Infrastructure>
+<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';
@@ -54,7 +56,6 @@ The generator will add the following files to your existing TypeScript project:
         - resources/
           - sample-guidance.ts Sample resource
         - Dockerfile Entry point for hosting your MCP server (excluded when `infra` is set to `None`)
-    - package.json Updated with bin entry and MCP dependencies
     - project.json Updated with MCP server serve target
 </FileTree>
 
@@ -120,14 +121,28 @@ server.registerResource('dynamic-resource', 'dynamic://resource', {}, async (uri
 
 ## Running Your MCP Server
 
+### Local Development
+
+To run your MCP server (and everything connected to it, such as a local database) locally, use the project's `dev` target:
+
+<NxCommands commands={['dev your-project']} />
+
+If you have added multiple components to your project (MCP servers, agents, etc.), this starts them all. To run just this MCP server, target its `<your-server-name>-dev` target:
+
+<NxCommands commands={['your-server-name-dev your-project']} />
+
 ### Inspector
 
-The generator configures a target named `<your-server-name>-inspect`, which starts the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) with the configuration to connect to your MCP server using STDIO transport.
+The generator configures a target named `<your-server-name>-inspect`, which starts your MCP server locally (via the `<your-server-name>-dev` target, including any connected dependencies such as a local database) and launches the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) pre-configured to connect to it over Streamable HTTP transport.
 
 <NxCommands commands={['your-server-name-inspect your-project']} />
 
 This will start the inspector at `http://localhost:6274`. Get started by clicking on the "Connect" button.
 
+:::tip
+To inspect the server using STDIO transport instead, use the `<your-server-name>-inspect-stdio` target, which launches the inspector against a STDIO instance of your server.
+:::
+
 ### STDIO
 
 The easiest way to test and use an MCP server is by using the inspector or configuring it with an AI assistant (as above).
@@ -163,7 +178,55 @@ The generator configures a `<your-server-name>-docker` target which copies the `
 
 A `docker` target is also generated which prepares the docker context for all MCP servers if you have multiple defined.
 
+### Image Scanning
+
+<Snippet name="trivy-image-scan" parentHeading="Image Scanning" />
+
 ### Observability
 
 <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-nx-plugin.mdx

@@ -46,7 +46,7 @@ The generator will create the following project structure:
         - generator-guide.ts Tool for detailed generator information
       - utils.ts Utility functions for the MCP server
   - generators.json Nx generator configuration (initially empty)
-  - package.json Plugin package configuration with MCP server binary
+  - package.json Plugin package configuration
   - tsconfig.json TypeScript configuration (CommonJS for Nx compatibility)
   - project.json Nx project configuration with build and package targets
 </FileTree>