@aws/nx-plugin-mcp 1.0.0-rc.2 → 1.0.0-rc.21

package/docs/snippets/connection/lambda-dynamodb-access.mdx

@@ -0,0 +1,80 @@
+---
+title: Lambda DynamoDB Access
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+To allow Lambda functions to access the DynamoDB table, grant the necessary permissions in your infrastructure.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+Call `grantReadWriteData` on the table construct. This grants both the DynamoDB and KMS permissions required by the Lambda execution role:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyTable } from ':my-scope/common-constructs';
+
+const table = new MyTable(this, 'Table');
+
+const api = new Api(this, 'Api', {
+  integrations: Api.defaultIntegrations(this).build(),
+});
+
+Object.entries(api.integrations).forEach(([, integration]) => {
+  table.grantReadWriteData(integration.handler);
+});
+```
+
+:::note
+This example grants every handler in your API access. If only some handlers need access, configure them individually.
+:::
+</Fragment>
+<Fragment slot="terraform">
+
+Grant the Lambda execution role permission to access the DynamoDB table and its KMS encryption key:
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source = "../../common/terraform/src/app/dynamodb/my-table"
+}
+
+resource "aws_iam_role_policy" "dynamodb_access" {
+  role = module.my_api.lambda_role_name
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect = "Allow"
+        Action = [
+          "dynamodb:GetItem",
+          "dynamodb:PutItem",
+          "dynamodb:UpdateItem",
+          "dynamodb:DeleteItem",
+          "dynamodb:Query",
+          "dynamodb:Scan",
+          "dynamodb:BatchGetItem",
+          "dynamodb:BatchWriteItem",
+        ]
+        Resource = [
+          module.my_table.table_arn,
+          "${module.my_table.table_arn}/index/*",
+        ]
+      },
+      {
+        Effect = "Allow"
+        Action = [
+          "kms:Encrypt",
+          "kms:Decrypt",
+          "kms:ReEncrypt*",
+          "kms:GenerateDataKey*",
+          "kms:DescribeKey"
+        ]
+        Resource = [module.my_table.kms_key_arn]
+      },
+    ]
+  })
+}
+```
+
+</Fragment>
+</Infrastructure>

package/docs/snippets/connection/py-dynamodb-local-development.mdx

@@ -0,0 +1,7 @@
+---
+title: Python DynamoDB Local Development
+---
+
+The `connection` generator configures your project's `serve-local` target to depend on the DynamoDB project's `serve-local` target. DynamoDB Local will start automatically alongside your project when running `serve-local`.
+
+The `SERVE_LOCAL=true` environment variable is set automatically, so `is_local()` returns `True` and your PynamoDB entities connect to the local DynamoDB instance instead of AWS.

package/docs/snippets/dynamodb/deploying-table.mdx

@@ -0,0 +1,171 @@
+---
+title: Deploying your DynamoDB Table
+---
+import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
+
+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
+- Global Secondary Indexes as defined in `config.json`
+- 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
+- Global Secondary Indexes as defined in `config.json`
+- 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>

package/docs/snippets/dynamodb/gsi-config.mdx

@@ -0,0 +1,38 @@
+---
+title: GSI Configuration
+---
+
+```json title="config.json"
+{
+  ...
+  "tableConfig": {
+    "globalSecondaryIndexes": [
+      {
+        "indexName": "gsi1pk-gsi1sk-index",
+        "partitionKey": "gsi1pk",
+        "sortKey": "gsi1sk"
+      },
+      {
+        "indexName": "gsi2pk-gsi2sk-index",
+        "partitionKey": "gsi2pk",
+        "sortKey": "gsi2sk"
+      }
+    ]
+  }
+}
+```
+
+The `sortKey` field is optional for hash-key-only GSIs.
+
+This config file is the single source of truth read by all consumers:
+- **Local development** — `serve-local` reads `config.json` and creates or updates the local table to match the GSI list
+- **CDK** — the construct reads `config.json` at synth time, so GSI changes are reflected on the next `cdk deploy`
+- **Terraform** — the module reads `config.json` at plan/apply time
+
+### One GSI per Deployment
+
+:::caution
+DynamoDB [does not allow more than one GSI to be created or deleted in a single table update](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.OnlineOps.html).
+
+Each deployment can add or remove **at most one GSI**. If you need to add or remove multiple GSIs, do so one at a time — update `config.json` and relevant entity classes, deploy the stack, then repeat for the next change.
+:::

package/docs/snippets/dynamodb/infrastructure.mdx

@@ -0,0 +1,33 @@
+---
+title: DynamoDB Infrastructure
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
+
+<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>

package/docs/snippets/dynamodb/serve-local-start.mdx

@@ -0,0 +1,13 @@
+---
+title: Starting Local DynamoDB
+---
+import NxCommands from '@components/nx-commands.astro';
+
+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 the indexes defined in `config.json`

package/docs/snippets/dynamodb/serve-local-windows.mdx

@@ -0,0 +1,15 @@
+---
+title: Serve Local Windows Caution
+---
+
+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`).
+:::

package/docs/snippets/mcp/config.mdx

@@ -6,7 +6,7 @@ title: MCP Server Configuration
   "mcpServers": {
     "nx-plugin-for-aws": {
       "command": "npx",
-      "args": ["-y", "@aws/nx-plugin-mcp"]
+      "args": ["-y", "@aws/nx-plugin-mcp@next"]
     }
   }
 }

package/docs/snippets/required-prerequisites.mdx

@@ -4,7 +4,7 @@ title: Required Prerequisites
 - [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
 - [Node >= 22](https://nodejs.org/en/download) (We recommend using something like [NVM](https://github.com/nvm-sh/nvm) to manage your node versions)
   - verify by running `node --version`
-- [PNPM >= 10](https://pnpm.io/installation#using-npm) (you can also use [Yarn >= 4](https://yarnpkg.com/getting-started/install), [Bun >= 1](https://bun.sh/docs/installation), or [NPM >= 10](https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager) if you prefer)
+- [PNPM >= 11](https://pnpm.io/installation#using-npm) (you can also use [Yarn >= 4](https://yarnpkg.com/getting-started/install), [Bun >= 1](https://bun.sh/docs/installation), or [NPM >= 10](https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager) if you prefer)
   - verify by running `pnpm --version`, `yarn --version`, `bun --version` or `npm --version`
 - [UV >= 0.5.29](https://docs.astral.sh/uv/getting-started/installation/)
   1. install Python 3.14 by running: `uv python install 3.14.0`

package/generators.json

@@ -3,6 +3,26 @@
   "name": "@aws/nx-plugin",
   "version": "0.0.1",
   "generators": {
+    "agentcore-gateway": {
+      "factory": "./src/agentcore-gateway/generator",
+      "schema": "./src/agentcore-gateway/schema.json",
+      "description": "Generate an AgentCore Gateway project",
+      "metric": "g48"
+    },
+    "agentcore-gateway#mcp-connection": {
+      "factory": "./src/agentcore-gateway/mcp-connection/generator",
+      "schema": "./src/agentcore-gateway/mcp-connection/schema.json",
+      "description": "Connect an AgentCore Gateway to an MCP server",
+      "metric": "g49",
+      "hidden": true
+    },
+    "agentcore-gateway#gateway-connection": {
+      "factory": "./src/agentcore-gateway/gateway-connection/generator",
+      "schema": "./src/agentcore-gateway/gateway-connection/schema.json",
+      "description": "Connect an AgentCore Gateway to another AgentCore Gateway",
+      "metric": "g52",
+      "hidden": true
+    },
     "connection": {
       "factory": "./src/connection/generator",
       "schema": "./src/connection/schema.json",
@@ -23,7 +43,11 @@
         "connection/trpc-rdb",
         "connection/smithy-rdb",
         "connection/ts-mcp-server-rdb",
-        "connection/ts-agent-rdb"
+        "connection/ts-agent-rdb",
+        "connection/ts-agent-gateway",
+        "connection/py-agent-gateway",
+        "connection/agentcore-gateway-mcp",
+        "connection/agentcore-gateway-gateway"
       ]
     },
     "license": {
@@ -279,6 +303,13 @@
       "metric": "g35",
       "hidden": true
     },
+    "ts#agent#gateway-connection": {
+      "factory": "./src/ts/agent/gateway-connection/generator",
+      "schema": "./src/ts/agent/gateway-connection/schema.json",
+      "description": "Connect a TypeScript Agent to an AgentCore Gateway",
+      "metric": "g50",
+      "hidden": true
+    },
     "py#agent#a2a-connection": {
       "factory": "./src/py/agent/a2a-connection/generator",
       "schema": "./src/py/agent/a2a-connection/schema.json",
@@ -286,6 +317,13 @@
       "metric": "g36",
       "hidden": true
     },
+    "py#agent#gateway-connection": {
+      "factory": "./src/py/agent/gateway-connection/generator",
+      "schema": "./src/py/agent/gateway-connection/schema.json",
+      "description": "Connect a Python Agent to an AgentCore Gateway",
+      "metric": "g51",
+      "hidden": true
+    },
     "ts#sync": {
       "factory": "./src/ts/sync/generator",
       "schema": "./src/ts/sync/schema.json",
@@ -349,6 +387,67 @@
       "description": "Connect a ts#mcp-server to a ts#rdb project",
       "metric": "g42",
       "hidden": true
+    },
+    "ts#dynamodb": {
+      "factory": "./src/ts/dynamodb/generator",
+      "schema": "./src/ts/dynamodb/schema.json",
+      "description": "Create a TypeScript DynamoDB project",
+      "metric": "g43"
+    },
+    "ts#dynamodb#trpc-connection": {
+      "factory": "./src/ts/dynamodb/trpc-connection/generator",
+      "schema": "./src/ts/dynamodb/trpc-connection/schema.json",
+      "description": "Connect a ts#trpc-api project to a ts#dynamodb project",
+      "metric": "g44",
+      "hidden": true
+    },
+    "ts#dynamodb#smithy-connection": {
+      "factory": "./src/ts/dynamodb/smithy-connection/generator",
+      "schema": "./src/ts/dynamodb/smithy-connection/schema.json",
+      "description": "Connect a Smithy backend to a ts#dynamodb project",
+      "metric": "g45",
+      "hidden": true
+    },
+    "ts#dynamodb#agent-connection": {
+      "factory": "./src/ts/dynamodb/agent-connection/generator",
+      "schema": "./src/ts/dynamodb/agent-connection/schema.json",
+      "description": "Connect a ts#agent to a ts#dynamodb project",
+      "metric": "g46",
+      "hidden": true
+    },
+    "ts#dynamodb#mcp-server-connection": {
+      "factory": "./src/ts/dynamodb/mcp-server-connection/generator",
+      "schema": "./src/ts/dynamodb/mcp-server-connection/schema.json",
+      "description": "Connect a ts#mcp-server to a ts#dynamodb project",
+      "metric": "g47",
+      "hidden": true
+    },
+    "py#dynamodb": {
+      "factory": "./src/py/dynamodb/generator",
+      "schema": "./src/py/dynamodb/schema.json",
+      "description": "Create a Python DynamoDB project",
+      "metric": "g52"
+    },
+    "py#dynamodb#fast-api-connection": {
+      "factory": "./src/py/dynamodb/fast-api-connection/generator",
+      "schema": "./src/py/dynamodb/fast-api-connection/schema.json",
+      "description": "Connect a py#fast-api project to a py#dynamodb project",
+      "metric": "g53",
+      "hidden": true
+    },
+    "py#dynamodb#agent-connection": {
+      "factory": "./src/py/dynamodb/agent-connection/generator",
+      "schema": "./src/py/dynamodb/agent-connection/schema.json",
+      "description": "Connect a py#agent to a py#dynamodb project",
+      "metric": "g54",
+      "hidden": true
+    },
+    "py#dynamodb#mcp-server-connection": {
+      "factory": "./src/py/dynamodb/mcp-server-connection/generator",
+      "schema": "./src/py/dynamodb/mcp-server-connection/schema.json",
+      "description": "Connect a py#mcp-server to a py#dynamodb project",
+      "metric": "g55",
+      "hidden": true
     }
   }
 }

package/package.json

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

package/src/agentcore-gateway/gateway-connection/schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "agentcore-gateway#gateway-connection",
+  "title": "agentcore-gateway#gateway-connection",
+  "description": "Connect an AgentCore Gateway to another AgentCore Gateway",
+  "type": "object",
+  "properties": {
+    "sourceProject": {
+      "type": "string",
+      "description": "The gateway project to add the target gateway to"
+    },
+    "targetProject": {
+      "type": "string",
+      "description": "The gateway project to register as a target"
+    },
+    "sourceComponent": {
+      "type": "string",
+      "description": "The gateway component in the source project"
+    },
+    "targetComponent": {
+      "type": "string",
+      "description": "The gateway component in the target project"
+    }
+  },
+  "required": ["sourceProject", "targetProject"]
+}

package/src/agentcore-gateway/mcp-connection/schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "agentcore-gateway#mcp-connection",
+  "title": "agentcore-gateway#mcp-connection",
+  "description": "Connect an AgentCore Gateway to an MCP server",
+  "type": "object",
+  "properties": {
+    "sourceProject": {
+      "type": "string",
+      "description": "The gateway project"
+    },
+    "targetProject": {
+      "type": "string",
+      "description": "The MCP server project"
+    },
+    "sourceComponent": {
+      "type": "string",
+      "description": "The gateway component in the source project"
+    },
+    "targetComponent": {
+      "type": "string",
+      "description": "The MCP server component in the target project"
+    }
+  },
+  "required": ["sourceProject", "targetProject"]
+}

package/src/agentcore-gateway/schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "agentcore-gateway",
+  "title": "agentcore-gateway",
+  "description": "Generate an AgentCore Gateway project",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The name of your AgentCore Gateway project",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What would you like to call your AgentCore Gateway?",
+      "x-priority": "important"
+    },
+    "directory": {
+      "type": "string",
+      "description": "Parent directory where the gateway project is placed.",
+      "default": "packages"
+    },
+    "subDirectory": {
+      "type": "string",
+      "description": "The sub directory the project is placed in. By default this is the project name."
+    },
+    "protocol": {
+      "type": "string",
+      "description": "The inbound protocol exposed by your gateway. Only mcp is supported today; additional protocols may be added in future.",
+      "enum": ["mcp"],
+      "default": "mcp",
+      "x-priority": "important"
+    },
+    "auth": {
+      "type": "string",
+      "description": "The method used to authenticate inbound requests to your gateway. Only iam is supported today; cognito and custom-jwt may be added in future.",
+      "enum": ["iam"],
+      "default": "iam",
+      "x-priority": "important"
+    },
+    "cedarPolicy": {
+      "type": "boolean",
+      "description": "Whether to include a Cedar policy engine enforcing fine-grained authorization on the gateway.",
+      "default": true,
+      "x-priority": "important"
+    },
+    "infra": {
+      "type": "string",
+      "description": "The type of infrastructure to host your gateway. Select none for no hosting.",
+      "x-prompt": "How would you like to host your gateway?",
+      "enum": ["agentcore", "none"],
+      "default": "agentcore",
+      "x-priority": "important"
+    },
+    "iac": {
+      "type": "string",
+      "description": "The preferred IaC provider. By default this is inherited from your initial selection.",
+      "enum": ["inherit", "cdk", "terraform"],
+      "x-priority": "important",
+      "default": "inherit",
+      "x-prompt": "Which provider would you like to manage your infrastructure? (default: inherit)"
+    }
+  },
+  "required": ["name"]
+}

package/src/license/schema.json

@@ -17,6 +17,12 @@
       "description": "The copyright holder, included in the LICENSE file and source file headers by default.",
       "default": "Amazon.com, Inc. or its affiliates",
       "x-priority": "important"
+    },
+    "dependencyCheck": {
+      "type": "boolean",
+      "description": "Configure a license-check target that fails when dependencies declare licenses outside the configured allowlist.",
+      "default": true,
+      "x-priority": "important"
     }
   },
   "required": []

package/src/preset/schema.json

@@ -23,6 +23,11 @@
       "description": "Whether to configure git-secrets to prevent committing AWS credentials.",
       "default": true
     },
+    "mcp": {
+      "type": "boolean",
+      "description": "Whether to configure the Nx Plugin for AWS MCP server for use by coding agents.",
+      "default": true
+    },
     "containers": {
       "type": "string",
       "description": "The container engine to use for build/push/login. 'infer' picks docker if installed, otherwise finch (falling back to docker when neither is installed).",