@aws/nx-plugin-mcp 1.0.0-rc.12 → 1.0.0-rc.14

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

@@ -0,0 +1,116 @@
+---
+title: Python Agent to DynamoDB
+description: Connect a Python Agent to a Python DynamoDB project
+when:
+  sourceType: py#agent
+  targetType: py#dynamodb
+---
+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 Snippet from '@components/snippet.astro';
+
+The `connection` generator wires a <Link path="guides/py-agent">Python Agent</Link> to a <Link path="guides/py-dynamodb">Python DynamoDB</Link> project, configuring local development so both start together automatically.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/py-agent">`py#agent`</Link> project
+2. A <Link path="guides/py-dynamodb">`py#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, and adds the DynamoDB package as a workspace dependency. No source files are modified.
+
+## Using DynamoDB in Agents
+
+Import entity classes from the DynamoDB package and use them inside your agent tools:
+
+```python title="packages/my_project/my_project/my_agent/agent.py"
+from my_scope.my_table.entities.example import ExampleModel
+from strands import tool
+
+@tool
+def list_examples() -> list:
+    """List all example items."""
+    return [item.attribute_values for item in ExampleModel.scan()]
+```
+
+## 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/py-dynamodb-local-development" />

package/docs/guides/connection/py-fast-api-dynamodb.mdx

@@ -0,0 +1,56 @@
+---
+title: FastAPI to DynamoDB
+description: Connect a FastAPI to a Python DynamoDB project
+when:
+  sourceType: py#fast-api
+  targetType: py#dynamodb
+---
+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';
+
+The `connection` generator wires a <Link path="guides/fastapi">FastAPI</Link> to a <Link path="guides/py-dynamodb">Python DynamoDB</Link> project, configuring local development so both start together automatically.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/fastapi">`py#fast-api`</Link> project
+2. A <Link path="guides/py-dynamodb">`py#dynamodb`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your FastAPI project as the source and your DynamoDB project as the target.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator updates the FastAPI's `project.json` to add a dependency from its `serve-local` target to the DynamoDB project's `serve-local` target, and adds the DynamoDB package as a workspace dependency. No source files are modified.
+
+## Using DynamoDB in Route Handlers
+
+Import entity classes from the DynamoDB package and use them inside your route handlers:
+
+```python title="packages/my_api/my_api/api.py"
+from my_scope.my_table.entities.example import ExampleModel
+
+@app.get("/examples")
+def list_examples():
+    return list(ExampleModel.scan())
+```
+
+## Infrastructure
+
+<Snippet name="connection/lambda-dynamodb-access" />
+
+## Local Development
+
+<Snippet name="connection/py-dynamodb-local-development" />

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

@@ -0,0 +1,116 @@
+---
+title: Python MCP Server to DynamoDB
+description: Connect a Python MCP Server to a Python DynamoDB project
+when:
+  sourceType: py#mcp-server
+  targetType: py#dynamodb
+---
+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 Snippet from '@components/snippet.astro';
+
+The `connection` generator wires a <Link path="guides/py-mcp-server">Python MCP Server</Link> to a <Link path="guides/py-dynamodb">Python DynamoDB</Link> project, configuring local development so both start together automatically.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/py-mcp-server">`py#mcp-server`</Link> project
+2. A <Link path="guides/py-dynamodb">`py#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, and adds the DynamoDB package as a workspace dependency. No source files are modified.
+
+## Using DynamoDB in Tools
+
+Import entity classes from the DynamoDB package and use them inside your MCP server tools:
+
+```python title="packages/my_project/my_project/my_mcp_server/server.py"
+from my_scope.my_table.entities.example import ExampleModel
+
+@mcp.tool()
+def list_examples() -> str:
+    """List all example items."""
+    items = list(ExampleModel.scan())
+    return str([item.attribute_values for item in items])
+```
+
+## Infrastructure
+
+To allow the MCP server'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 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/py-dynamodb-local-development" />

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

@@ -1,6 +1,6 @@
 ---
 title: Smithy API to DynamoDB
-description: Connect a Smithy API to a DynamoDB table
+description: Connect a Smithy API to a TypeScript DynamoDB project
 when:
   sourceType: smithy
   targetType: ts#dynamodb
@@ -12,7 +12,7 @@ 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.
+The `connection` generator wires a <Link path="guides/ts-smithy-api">Smithy API</Link> to a <Link path="guides/ts-dynamodb">TypeScript DynamoDB</Link> project, configuring local development so both start together automatically.
 
 ## Prerequisites
 

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

@@ -1,6 +1,6 @@
 ---
 title: tRPC API to DynamoDB
-description: Connect a tRPC API to a DynamoDB table
+description: Connect a tRPC API to a TypeScript DynamoDB project
 when:
   sourceType: ts#trpc-api
   targetType: ts#dynamodb
@@ -12,7 +12,7 @@ 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.
+The `connection` generator wires a <Link path="guides/trpc">tRPC API</Link> to a <Link path="guides/ts-dynamodb">TypeScript DynamoDB</Link> project, configuring local development so both start together automatically.
 
 ## Prerequisites
 

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

@@ -1,6 +1,6 @@
 ---
 title: TypeScript Agent to DynamoDB
-description: Connect a TypeScript Agent to a DynamoDB table
+description: Connect a TypeScript Agent to a TypeScript DynamoDB project
 when:
   sourceType: ts#agent
   targetType: ts#dynamodb
@@ -12,7 +12,7 @@ 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.
+The `connection` generator wires a <Link path="guides/ts-agent">TypeScript Agent</Link> to a <Link path="guides/ts-dynamodb">TypeScript DynamoDB</Link> project, configuring local development so both start together automatically.
 
 ## Prerequisites
 

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

@@ -1,6 +1,6 @@
 ---
 title: MCP Server to DynamoDB
-description: Connect a TypeScript MCP Server to a DynamoDB table
+description: Connect a TypeScript MCP Server to a TypeScript DynamoDB project
 when:
   sourceType: ts#mcp-server
   targetType: ts#dynamodb
@@ -12,7 +12,7 @@ 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.
+The `connection` generator wires a <Link path="guides/ts-mcp-server">TypeScript MCP Server</Link> to a <Link path="guides/ts-dynamodb">TypeScript DynamoDB</Link> project, configuring local development so both start together automatically.
 
 ## Prerequisites
 

package/docs/guides/connection.mdx

@@ -120,21 +120,21 @@ The Connection generator supports the following connections:
     target="aurora"
   />
   <ConnectionCard
-    title="tRPC API to DynamoDB"
+    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 DynamoDB"
+    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 DynamoDB"
+    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"
@@ -142,12 +142,38 @@ The Connection generator supports the following connections:
     target="dynamodb"
   />
   <ConnectionCard
-    title="MCP Server to DynamoDB"
+    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="FastAPI to Python DynamoDB"
+    description="Connect a FastAPI to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-fast-api-dynamodb`}
+    source="fastapi"
+    target="dynamodb"
+    targetBadge="python"
+  />
+  <ConnectionCard
+    title="Python Agent to Python DynamoDB"
+    description="Connect a Python Agent to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-agent-dynamodb`}
+    source="strands"
+    sourceBadge="python"
+    target="dynamodb"
+    targetBadge="python"
+  />
+  <ConnectionCard
+    title="Python MCP Server to Python DynamoDB"
+    description="Connect a Python MCP Server to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-mcp-server-dynamodb`}
+    source="mcp"
+    sourceBadge="python"
+    target="dynamodb"
+    targetBadge="python"
+  />
   <ConnectionCard
     title="AgentCore Gateway to MCP Server"
     description="Aggregate an MCP server behind an AgentCore Gateway"

package/docs/guides/py-agent.mdx

@@ -351,19 +351,58 @@ This command uses `uv run` to execute your Agent using the [Bedrock AgentCore Py
 
 ### 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 `<your-agent-name>-serve-local` first (in a separate terminal):
+
+<NxCommands commands={['run your-project:agent-serve-local']} />
+
+Then, in another terminal, start the chat:
 
 <NxCommands commands={['run your-project:agent-chat']} />
 
-For **HTTP** agents, the generator also emits:
+The generator emits a `scripts/<your-agent-name>/chat.ts` for every protocol. 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).
+
+For **HTTP** agents, the chat script uses a type-safe TypeScript client generated from the agent's OpenAPI spec. The generator also emits:
 
 - `scripts/<your-agent-name>_openapi.py` — a small script that exports the agent's OpenAPI spec
 - An `<your-agent-name>-openapi` Nx target that runs it
 - An `<your-agent-name>-generate-client` Nx target that produces a type-safe TypeScript client under `scripts/<your-agent-name>/generated/`
-- `scripts/<your-agent-name>/chat.ts` — a thin wrapper around the generated client
 
 When you customize the agent's input shape (e.g. add new fields to `InvokeInput`), update `chat.ts` to pass the new fields when invoking the agent and the rest works automatically.
 
+<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