@aws/nx-plugin-mcp 1.0.0-rc.1 → 1.0.0-rc.11

package/docs/guides/connection/react-smithy.mdx

@@ -21,7 +21,7 @@ The `connection` generator provides a way to quickly integrate your React websit
 Before using this generator, ensure your React application has:
 
 1. A `main.tsx` file that renders your application
-2. A working Smithy TypeScript API backend (generated using the <Link path="/guides/ts-smithy-api">`ts#smithy-api` generator</Link>)
+2. A working Smithy TypeScript API backend (generated using the <Link path="/guides/ts-smithy-api">`ts#api` generator</Link> with `--framework=smithy`)
 3. Cognito Auth added via the <Link path="/guides/react-website-auth">`ts#website#auth` generator</Link> if connecting an API which uses Cognito or IAM auth
 
 <details>

package/docs/guides/connection/react-trpc.mdx

@@ -175,7 +175,7 @@ Subscriptions are only supported when the tRPC API uses `rest-lambda` (REST API)
 
 When connecting to a REST API tRPC backend, the generated client is automatically configured with a `splitLink` that routes subscription operations through `httpSubscriptionLink` (using SSE) and regular queries/mutations through `httpLink`. This means subscriptions work out of the box with no additional configuration.
 
-For information on how to define subscription procedures in your backend, see the <Link path="guides/trpc">`ts#trpc-api` generator guide</Link>.
+For information on how to define subscription procedures in your backend, see the <Link path="guides/trpc">tRPC API generator guide</Link>.
 
 #### Using the useSubscription Hook
 

package/docs/guides/connection/smithy-dynamodb.mdx

@@ -0,0 +1,68 @@
+---
+title: Smithy API to DynamoDB
+description: Connect a Smithy API to a DynamoDB table
+when:
+  sourceType: smithy
+  targetType: ts#dynamodb
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Snippet from '@components/snippet.astro';
+
+The `connection` generator wires a <Link path="guides/ts-smithy-api">Smithy API</Link> to a <Link path="guides/ts-dynamodb">DynamoDB</Link> project, configuring local development so both start together automatically.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/ts-smithy-api">Smithy TypeScript API</Link> project (generated with `ts#api` using `--framework=smithy`)
+2. A <Link path="guides/ts-dynamodb">`ts#dynamodb`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your Smithy API backend project as the source and your DynamoDB project as the target.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator updates your Smithy API's `project.json` to add a dependency from its `serve-local` target to the DynamoDB project's `serve-local` target. No source files are modified.
+
+## Using DynamoDB in Operations
+
+Import entity factories from the DynamoDB package and use them inside your operation implementations:
+
+```ts title="packages/api/src/operations/list-examples.ts"
+import { createExampleEntity } from ':my-scope/my-table';
+import {
+  ListExamplesOperationInput,
+  ListExamplesOperationOutput,
+} from '../generated/ssdk/index.js';
+import { ServiceContext } from '../context.js';
+
+export const listExamples = async (
+  _input: ListExamplesOperationInput,
+  _ctx: ServiceContext,
+): Promise<ListExamplesOperationOutput> => {
+  const entity = await createExampleEntity();
+  const result = await entity.scan.go();
+  return { items: result.data };
+};
+```
+
+## Infrastructure
+
+<Snippet name="connection/lambda-dynamodb-access" />
+
+## Local Development
+
+<Snippet name="connection/dynamodb-local-development" />

package/docs/guides/connection/smithy-rdb.mdx

@@ -18,7 +18,7 @@ The `connection` generator wires a <Link path="guides/ts-smithy-api">Smithy API<
 
 Before using this generator, ensure you have:
 
-1. A <Link path="guides/ts-smithy-api">`ts#smithy-api`</Link> project (TypeScript backend)
+1. A <Link path="guides/ts-smithy-api">Smithy TypeScript API</Link> project (generated with `ts#api` using `--framework=smithy`)
 2. A <Link path="guides/ts-rdb">`ts#rdb`</Link> project
 
 ## Usage

package/docs/guides/connection/trpc-dynamodb.mdx

@@ -0,0 +1,62 @@
+---
+title: tRPC API to DynamoDB
+description: Connect a tRPC API to a DynamoDB table
+when:
+  sourceType: ts#trpc-api
+  targetType: ts#dynamodb
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Snippet from '@components/snippet.astro';
+
+The `connection` generator wires a <Link path="guides/trpc">tRPC API</Link> to a <Link path="guides/ts-dynamodb">DynamoDB</Link> project, configuring local development so both start together automatically.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/trpc">tRPC API</Link> project (generated with `ts#api`)
+2. A <Link path="guides/ts-dynamodb">`ts#dynamodb`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your tRPC API project as the source and your DynamoDB project as the target.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator updates your tRPC API's `project.json` to add a dependency from its `serve-local` target to the DynamoDB project's `serve-local` target. No source files are modified.
+
+## Using DynamoDB in Procedures
+
+Import entity factories from the DynamoDB package and use them inside your tRPC procedures:
+
+```ts title="packages/api/src/procedures/example.ts"
+import { createExampleEntity } from ':my-scope/my-table';
+import { publicProcedure } from '../init.js';
+
+export const listExamples = publicProcedure
+  .query(async () => {
+    const entity = await createExampleEntity();
+    const result = await entity.scan.go();
+    return result.data;
+  });
+```
+
+## Infrastructure
+
+<Snippet name="connection/lambda-dynamodb-access" />
+
+## Local Development
+
+<Snippet name="connection/dynamodb-local-development" />

package/docs/guides/connection/trpc-rdb.mdx

@@ -18,7 +18,7 @@ The `connection` generator wires a <Link path="guides/trpc">tRPC API</Link> to a
 
 Before using this generator, ensure you have:
 
-1. A <Link path="guides/trpc">`ts#trpc-api`</Link> project
+1. A <Link path="guides/trpc">tRPC API</Link> project (generated with `ts#api`)
 2. A <Link path="guides/ts-rdb">`ts#rdb`</Link> project
 
 ## Usage

package/docs/guides/connection/ts-agent-dynamodb.mdx

@@ -0,0 +1,128 @@
+---
+title: TypeScript Agent to DynamoDB
+description: Connect a TypeScript Agent to a DynamoDB table
+when:
+  sourceType: ts#agent
+  targetType: ts#dynamodb
+---
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
+
+The `connection` generator wires a <Link path="guides/ts-agent">TypeScript Agent</Link> to a <Link path="guides/ts-dynamodb">DynamoDB</Link> project, configuring local development so both start together automatically.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/ts-agent">`ts#agent`</Link> project
+2. A <Link path="guides/ts-dynamodb">`ts#dynamodb`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your Agent project as the source and your DynamoDB project as the target. If the project contains multiple agent components, specify `sourceComponent` to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator updates the agent's `<agent-name>-serve-local` target in `project.json` to depend on the DynamoDB project's `serve-local` target. No source files are modified.
+
+## Using DynamoDB in Agents
+
+Import entity factories from the DynamoDB package and use them inside your agent definition:
+
+```ts title="packages/my-service/src/my-agent/agent.ts"
+import { createExampleEntity } from ':my-scope/my-table';
+
+export const getAgent = async () => {
+  // ...
+  return new Agent({
+    tools: [
+      tool({
+        name: 'list_examples',
+        description: 'List all example items',
+        func: async () => {
+          const entity = await createExampleEntity();
+          const result = await entity.scan.go();
+          return result.data;
+        },
+      }),
+    ],
+  });
+};
+```
+
+## Infrastructure
+
+To allow the agent's Lambda function to access the DynamoDB table, grant the necessary permissions in your infrastructure.
+
+<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');
+const myAgent = new MyAgent(this, 'MyAgent');
+
+table.grantReadWriteData(myAgent);
+```
+
+`grantReadWriteData` grants both the DynamoDB and KMS permissions to the agent's execution role.
+</Fragment>
+<Fragment slot="terraform">
+
+```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_agent.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>
+
+## Local Development
+
+<Snippet name="connection/dynamodb-local-development" />

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

@@ -0,0 +1,125 @@
+---
+title: MCP Server to DynamoDB
+description: Connect a TypeScript MCP Server to a DynamoDB table
+when:
+  sourceType: ts#mcp-server
+  targetType: ts#dynamodb
+---
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
+
+The `connection` generator wires a <Link path="guides/ts-mcp-server">TypeScript MCP Server</Link> to a <Link path="guides/ts-dynamodb">DynamoDB</Link> project, configuring local development so both start together automatically.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/ts-mcp-server">`ts#mcp-server`</Link> project
+2. A <Link path="guides/ts-dynamodb">`ts#dynamodb`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your MCP server project as the source and your DynamoDB project as the target. If the project contains multiple MCP server components, specify `sourceComponent` to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator updates the MCP server's `<mcp-server-name>-serve-local` target in `project.json` to depend on the DynamoDB project's `serve-local` target. No source files are modified.
+
+## Using DynamoDB in Tools
+
+Import entity factories from the DynamoDB package and use them inside `createServer`:
+
+```ts title="packages/my-service/src/my-mcp/server.ts"
+import { createExampleEntity } from ':my-scope/my-table';
+
+export const createServer = async () => {
+  const server = new McpServer({ name: 'my-service', version: '1.0.0' });
+
+  server.tool('list_examples', 'List all example items', {}, async () => {
+    const entity = await createExampleEntity();
+    const result = await entity.scan.go();
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result.data) }],
+    };
+  });
+
+  return server;
+};
+```
+
+## Infrastructure
+
+To allow the MCP server to access the DynamoDB table, grant the necessary permissions in your infrastructure.
+
+<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');
+const myMcpServer = new MyMcpServer(this, 'MyMcpServer');
+
+table.grantReadWriteData(myMcpServer);
+```
+
+`grantReadWriteData` grants both the DynamoDB and KMS permissions to the MCP server's execution role.
+</Fragment>
+<Fragment slot="terraform">
+
+```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_mcp_server.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>
+
+## Local Development
+
+<Snippet name="connection/dynamodb-local-development" />

package/docs/guides/connection.mdx

@@ -119,8 +119,41 @@ The Connection generator supports the following connections:
     source="mcp"
     target="aurora"
   />
+  <ConnectionCard
+    title="tRPC API to 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 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 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 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>
 
 :::note[Runtime Configuration]
 The connection generator makes use of <Link path="guides/runtime-config">Runtime Configuration</Link> to pass deploy-time values (such as API URLs, Cognito settings, and agent runtime ARNs) between generated projects and components at runtime so they can discover and connect to one another.
 :::
+
+:::tip[Local Development]
+Connected projects can be run on your machine with the `serve` and `serve-local` targets. See the <Link path="guides/local-development">Local Development</Link> guide for details.
+:::

package/docs/guides/docker-bundling.mdx

@@ -8,7 +8,7 @@ import NxCommands from '@components/nx-commands.astro';
 import Link from '@components/link.astro';
 import Infrastructure from '@components/infrastructure.astro';
 
-Several generators (such as <Link path="/guides/ts-agent">`ts#agent`</Link> and <Link path="/guides/py-agent">`py#agent`</Link>) produce a Docker image that is pushed to Amazon ECR and consumed by AWS infrastructure. This guide describes the pattern they follow so that you can apply it to other use cases — for example, running a <Link path="/guides/fastapi">`py#fast-api`</Link> project on Amazon ECS, or deploying a containerised Express server.
+Several generators (such as <Link path="/guides/ts-agent">`ts#agent`</Link> and <Link path="/guides/py-agent">`py#agent`</Link>) produce a Docker image that is pushed to Amazon ECR and consumed by AWS infrastructure. This guide describes the pattern they follow so that you can apply it to other use cases — for example, running a <Link path="/guides/fastapi">FastAPI</Link> project on Amazon ECS, or deploying a containerised Express server.
 
 :::tip[Docker or Finch]
 The container engine used to build images is chosen at workspace creation time via the `--containerEngine` flag (`docker`, `finch`, or `infer` — the default — which auto-detects what's installed). [Finch](https://runfinch.com/) is an open-source, drop-in alternative to Docker. The selection is recorded in `aws-nx-plugin.config.mts` and applied to every generator that emits container build commands. CDK image asset builds honour the choice via the `CDK_DOCKER` environment variable.

package/docs/guides/fastapi.mdx

@@ -1,7 +1,7 @@
 ---
 title: FastAPI
 description: Reference documentation for FastAPI
-generator: py#fast-api
+generator: py#api
 when:
   framework: [fastapi]
 ---
@@ -26,11 +26,11 @@ The FastAPI generator creates a new FastAPI with AWS CDK or Terraform infrastruc
 
 You can generate a new FastAPI in two ways:
 
-<RunGenerator generator="py#fast-api" />
+<RunGenerator generator="py#api" requiredParameters={{ framework: 'fastapi' }} />
 
 ### Options
 
-<GeneratorParameters generator="py#fast-api" />
+<GeneratorParameters generator="py#api" />
 
 <Snippet name="api/api-choice-note" />