@aws/nx-plugin-mcp 1.0.0-rc.3 → 1.0.0-rc.30

package/docs/guides/ts-dynamodb.mdx

@@ -0,0 +1,187 @@
+---
+title: TypeScript DynamoDB
+description: Create a TypeScript DynamoDB project
+generator: ts#dynamodb
+---
+
+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 Snippet from '@components/snippet.astro';
+
+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 TypeScript DynamoDB Project
+
+<RunGenerator generator="ts#dynamodb" />
+
+### Options
+
+<GeneratorParameters generator="ts#dynamodb" />
+
+## Generator Output
+
+The generator creates the following project structure in the `<directory>/<name>` directory:
+
+<FileTree>
+  - src
+    - index.ts Project entry point and exports
+    - 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="dynamodb/infrastructure" />
+
+## Local Development
+
+### Starting Local DynamoDB
+
+<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, 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:
+
+```ts title="packages/my-table/src/entities/example.ts"
+import { Entity } from 'electrodb';
+import { getDynamoDBClient, resolveTableName } from '../client.js';
+
+export const createExampleEntity = async () =>
+  new Entity(
+    {
+      model: {
+        entity: 'example',
+        version: '1',
+        service: 'MyTable',
+      },
+      attributes: {
+        id: {
+          type: 'string',
+          required: true,
+        },
+        createdAt: {
+          type: 'string',
+          required: true,
+          default: () => new Date().toISOString(),
+          readOnly: true,
+        },
+        updatedAt: {
+          type: 'string',
+          required: true,
+          default: () => new Date().toISOString(),
+          watch: '*',
+          set: () => new Date().toISOString(),
+        },
+      },
+      indexes: {
+        primary: {
+          pk: {
+            field: 'pk',
+            composite: ['id'],
+          },
+          sk: {
+            field: 'sk',
+            composite: [],
+          },
+        },
+      },
+    },
+    { client: getDynamoDBClient(), table: await resolveTableName() },
+  );
+```
+
+For more details, see the [ElectroDB entity documentation](https://electrodb.dev/en/modeling/entities/).
+
+### Using the DynamoDB Client
+
+The generated `src/client.ts` exports two key utilities:
+
+- `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
+
+<Snippet name="dynamodb/local-dev-windows" />
+
+## Adding/Removing Global Secondary Indexes
+
+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:
+
+<Snippet name="dynamodb/gsi-config" parentHeading="Adding/Removing Global Secondary Indexes" />
+
+## Connecting to the Table
+
+In any TypeScript project, import entity factories from your DynamoDB package and use them directly:
+
+```ts
+import { createExampleEntity } from ':my-scope/my-table';
+
+const entity = await createExampleEntity();
+const result = await entity.query.primary({ id: '123' }).go();
+```
+
+:::note[Runtime config]
+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>.
+:::
+
+## 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';
@@ -120,14 +122,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).
@@ -167,3 +183,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';
@@ -37,23 +39,29 @@ The generator will create the following project structure in the `<directory>/<n
     - models
       - example.prisma Example model definition
     - schema.prisma Main Prisma schema (references models)
-  - scripts
-    - docker-pull.ts Pulls the database Docker image for local development
-    - docker-start.ts Starts a local database container
-    - wait-for-db.ts Waits for the local database to be ready
   - src
     - index.ts Project entry point
-    - constants.ts Local development connection details and runtime config key
     - prisma.ts Prisma runtime client wrapper
     - utils.ts Runtime config and secret helpers
     - create-db-user-handler.ts Lambda handler used to create the application database user during deployment
     - migration-handler.ts Lambda handler used to run database migrations during deployment
   - .gitignore Git ignore entries including generated Prisma client output
+  - config.json Local development connection details and runtime config key
   - Dockerfile Container image definition for the migration handler
   - project.json Project configuration and build targets
   - prisma.config.ts Configuration for Prisma CLI
 </FileTree>
 
+Local development scripts are shared across all database projects and generated into `packages/common/scripts/`:
+
+<FileTree>
+  - packages/common/scripts/src/rdb
+    - pull-image.ts Pulls the database container image
+    - start-container.ts Starts a local database container
+    - wait-for-postgres-db.ts Waits for the local database to be ready (PostgreSQL)
+    - wait-for-mysql-db.ts Waits for the local database to be ready (MySQL)
+</FileTree>
+
 ### Infrastructure
 
 <Snippet name="shared-constructs" />
@@ -156,7 +164,6 @@ Use the `prisma` target to run Prisma CLI commands from the workspace root:
 
 The runtime wrapper in `src/prisma.ts` exports:
 
-- `DB_PACKAGE_NAME` - the key used under the `database` runtime config namespace in AWS AppConfig
 - `getPrisma()` - loads database connection settings from AWS AppConfig and creates a Prisma client using IAM authentication
 
 The client automatically:
@@ -169,7 +176,7 @@ The client automatically:
 
 After adding or updating models under `prisma/models/`, use `migrate dev` to generate migration files and apply them to your local database at the same time.
 
-The generated `prisma` target automatically starts a local database via Docker before running:
+The generated `prisma` target automatically starts a local database container before running:
 
 <NxCommands commands={['run <project>:prisma migrate dev']} />
 
@@ -204,12 +211,26 @@ The generated `prisma` target exposes the Prisma CLI, so you can use it to run a
 
 <NxCommands commands={['run <project>:prisma <prisma-command>']} />
 
-### Prisma Studio
+### Using Prisma Studio
 
 [Prisma Studio](https://www.prisma.io/studio) is a visual editor for your local database. Use it to browse tables, inspect and edit records, filter data, follow relations, and run raw SQL via the built-in SQL console. It is useful for verifying migrations and seeding test data during development. Launch it with:
 
 <NxCommands commands={['run <project>:prisma studio']} />
 
+### Stopping the Local Database
+
+Stopping `dev` (e.g. with `Ctrl+C`) automatically removes the local database 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 `dev` is stopped. You will need to remove it manually:
+
+```bash
+<engine> rm -f <scope>-<db-name>
+```
+
+Replace `<engine>` with your container engine (`docker` or `finch`), `<scope>` with your Nx workspace scope (e.g. `proj`), and `<db-name>` with your database project name (e.g. `my-db`).
+:::
+
 ## Connecting to the Database
 
 In any TypeScript project, import `getPrisma` from your database package and call it to get a type-safe Prisma client:
@@ -225,15 +246,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`.
@@ -524,9 +536,9 @@ module "my_database" {
 
 Pin a specific Aurora engine version.
 
-By default, the generated local Docker database image matches the default Aurora engine version. If you change the Aurora engine version, it's recommended to also use a matching local Docker database version for maximum compatibility. See the AWS release notes for [Aurora PostgreSQL versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraPostgreSQLReleaseNotes/aurorapostgresql-release-calendar.html) and [Aurora MySQL versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraMySQLReleaseNotes/AuroraMySQL.Updates.30Updates.html) to identify the corresponding community database version.
+By default, the generated local database container image matches the default Aurora engine version. If you change the Aurora engine version, it's recommended to also use a matching local container image version for maximum compatibility. See the AWS release notes for [Aurora PostgreSQL versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraPostgreSQLReleaseNotes/aurorapostgresql-release-calendar.html) and [Aurora MySQL versions](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraMySQLReleaseNotes/AuroraMySQL.Updates.30Updates.html) to identify the corresponding community database version.
 
-The local database image is configured in the generated database project's `serve-local` target in `project.json`. Update the image argument passed to `scripts/docker-start.ts` when you change engine versions.
+The local database image is configured in the `localDev.image` field of the generated `config.json` file in your database project root. Update that value when you change engine versions.
 
 <OptionFilter when={{ engine: 'postgres' }}>
 <Infrastructure>
@@ -659,6 +671,36 @@ module "my_database" {
 </Fragment>
 </Infrastructure>
 
+### Logging and Monitoring
+
+Performance Insights is enabled on the Aurora writer instance by default (encrypted with the cluster's KMS key). You can also export the Aurora engine logs to [CloudWatch Logs](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_LogAccess.html) (`postgresql` for [Aurora PostgreSQL](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.CloudWatch.html); `audit`, `error`, `general` and `slowquery` for [Aurora MySQL](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Integrating.CloudWatch.html)). Enable log export per database:
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from ':my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', {
+  ...
+  enableCloudwatchLogs: true,
+  enablePerformanceInsights: false, // disable if not required
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source = "../../common/terraform/src/app/dbs/my-database"
+  ...
+  enable_cloudwatch_logs      = true
+  enable_performance_insights = false # disable if not required
+}
+```
+</Fragment>
+</Infrastructure>
+
 ### Encryption Key Rotation
 
 The KMS key used to encrypt the Aurora cluster and its credentials secret has automatic key rotation enabled by default. Disable it if your security policy manages rotation externally.
@@ -757,3 +799,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>