@aws/nx-plugin-mcp 0.120.0 → 0.121.0

package/docs/snippets/connection/a2a-infrastructure.mdx

@@ -0,0 +1,63 @@
+---
+title: A2A Connection Infrastructure
+---
+import Link from '@components/link.astro';
+import Infrastructure from '@components/infrastructure.astro';
+
+After running the connection generator, you need to grant the host agent permission to invoke the remote A2A agent.
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts title="packages/infra/src/stacks/application-stack.ts" {5}
+const remoteAgent = new RemoteAgent(this, 'RemoteAgent');
+const myAgent = new MyAgent(this, 'MyAgent');
+
+// Grant the host agent permission to invoke the remote A2A agent
+remoteAgent.grantInvokeAccess(myAgent);
+```
+
+`grantInvokeAccess` on an A2A agent wires up both `bedrock-agentcore:InvokeAgentRuntime` and `bedrock-agentcore:GetAgentCard` — the A2A client needs both to fetch the agent card and send messages.
+
+The remote agent's AgentCore runtime ARN is automatically registered in the `agentcore` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link> by the generated CDK construct, so the host agent can discover it at runtime.
+</Fragment>
+<Fragment slot="terraform">
+```hcl title="packages/infra/src/main.tf" {3-6, 11-12, 16-17}
+module "remote_agent" {
+  source = "../../common/terraform/src/app/agents/remote-agent"
+
+  appconfig_application_id  = module.runtime_config_appconfig.application_id
+  appconfig_application_arn = module.runtime_config_appconfig.application_arn
+}
+
+module "my_agent" {
+  source = "../../common/terraform/src/app/agents/my-agent"
+
+  appconfig_application_id  = module.runtime_config_appconfig.application_id
+  appconfig_application_arn = module.runtime_config_appconfig.application_arn
+}
+
+# Grant the host agent permission to invoke the remote A2A agent
+resource "aws_iam_policy" "agent_invoke_a2a" {
+  name = "AgentInvokeA2aPolicy"
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect = "Allow"
+      Action = [
+        "bedrock-agentcore:InvokeAgentRuntime",
+        "bedrock-agentcore:GetAgentCard",
+      ]
+      Resource = module.remote_agent.agent_core_runtime_arn
+    }]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "agent_invoke_a2a" {
+  role       = module.my_agent.agent_core_runtime_role_arn
+  policy_arn = aws_iam_policy.agent_invoke_a2a.arn
+}
+```
+
+The remote agent's AgentCore runtime ARN is automatically registered in the `agentcore` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link> by the generated Terraform module, so the host agent can discover it at runtime.
+</Fragment>
+</Infrastructure>

package/docs/snippets/connection/lambda-rdb-ssl-requirements.mdx

@@ -0,0 +1,40 @@
+---
+title: SSL Requirements when Connecting without RDS Proxy
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+For direct Aurora cluster connections from Node.js 20 or later Lambda runtimes, load the Amazon RDS CA bundle by setting `NODE_EXTRA_CA_CERTS`:
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+const api = new Api(this, 'Api', {
+  integrations: Api.defaultIntegrations(this)
+    .withDefaultOptions({
+      environment: {
+        NODE_EXTRA_CA_CERTS: '/var/runtime/ca-cert.pem',
+      },
+    })
+    .build(),
+});
+```
+
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "api" {
+  source = "..."
+  ...
+
+  environment_variables = {
+    NODE_EXTRA_CA_CERTS = "/var/runtime/ca-cert.pem"
+  }
+}
+```
+
+</Fragment>
+</Infrastructure>
+
+For more details, see the AWS Lambda [SSL/TLS requirements for Amazon RDS connections](https://docs.aws.amazon.com/lambda/latest/dg/services-rds.html#services-rds-tls) and the Amazon RDS Proxy [TLS documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/rds-proxy.howitworks.html#rds-proxy-security.tls). When using RDS Proxy, you do not need to configure the RDS CA bundle in your Lambda function.

package/docs/snippets/connection/mcp-server-rdb-ssl-requirements.mdx

@@ -0,0 +1,35 @@
+---
+title: SSL Requirements when Connecting without RDS Proxy
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+The connection generator updates the Dockerfile to install the Amazon RDS CA bundle at `/usr/local/share/ca-certificates/rds-bundle.crt`. Set `NODE_EXTRA_CA_CERTS` to that path so Node.js trusts the certificate when connecting without RDS Proxy:
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+new MyMcpServer(this, 'MyMcpServer', {
+  ...
+  environmentVariables: {
+    NODE_EXTRA_CA_CERTS: '/usr/local/share/ca-certificates/rds-bundle.crt',
+  },
+});
+```
+
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_mcp_server" {
+  ...
+  environment_variables = {
+    NODE_EXTRA_CA_CERTS = "/usr/local/share/ca-certificates/rds-bundle.crt"
+  }
+}
+```
+
+</Fragment>
+</Infrastructure>
+
+For more details, see the [Amazon RDS SSL/TLS documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.SSL.html). When using RDS Proxy, you do not need to configure `NODE_EXTRA_CA_CERTS`.

package/docs/snippets/connection/rdb-api-infrastructure.mdx

@@ -0,0 +1,72 @@
+---
+title: RDB API Infrastructure
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+To allow your API to connect to the database at runtime, the API Lambda functions must be deployed into the same VPC as the database and granted network and IAM access.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+In your application stack, deploy the API into the same VPC as the database, then call `allowDefaultPortFrom` and `grantConnect` to open the network path and grant IAM `rds-db:connect` permission to each Lambda handler:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyDatabase } from ':my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', { vpc, ... });
+
+const api = new MyApi(this, 'Api', {
+  integrations: MyApi.defaultIntegrations(this)
+    .withDefaultOptions({
+      vpc,
+      vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
+    })
+    .build(),
+});
+
+Object.entries(api.integrations).forEach(([operation, integration]) => {
+  db.allowDefaultPortFrom(integration.handler, `Allow ${operation} to connect to the database`);
+  db.grantConnect(integration.handler);
+});
+```
+
+Deploy the API Lambda functions into a **private subnet with egress**, not a private isolated subnet. At runtime, `getPrisma()` retrieves database connection details from AWS AppConfig, which is a public AWS service endpoint that requires outbound internet access.
+
+:::note
+This example grants every handler in your API access, but if only some handlers need access it's better to configure individually.
+:::
+
+</Fragment>
+<Fragment slot="terraform">
+
+Pass the database module outputs into your API module so it can reach the database and read its runtime configuration:
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source              = "../../common/terraform/src/app/dbs/my-database"
+  vpc_id              = module.vpc.vpc_id
+  database_subnet_ids = module.vpc.private_isolated_subnet_ids
+  lambda_subnet_ids   = module.vpc.private_subnet_ids
+}
+
+module "api" {
+  source             = "..."
+  vpc_id             = module.vpc.vpc_id
+  private_subnet_ids = module.vpc.private_subnet_ids
+
+  appconfig_application_id     = module.my_database.appconfig_application_id
+  database_cluster_resource_id = module.my_database.cluster_resource_id
+  database_runtime_user        = module.my_database.database_runtime_user
+  database_security_group_id   = module.my_database.security_group_id
+  database_port                = module.my_database.cluster_port
+
+  environment_variables = {
+    RUNTIME_CONFIG_APP_ID = module.my_database.appconfig_application_id
+  }
+}
+```
+
+Deploy the API Lambda functions into **private subnets with egress**, not private isolated subnets. Ensure the API Lambda role has `rds-db:connect` permission and that its security group can reach the database security group on the database port.
+
+</Fragment>
+</Infrastructure>

package/docs/snippets/connection/react-agent-infrastructure.mdx

@@ -0,0 +1,61 @@
+---
+title: React to Agent Connection Infrastructure
+---
+import Link from '@components/link.astro';
+import Infrastructure from '@components/infrastructure.astro';
+
+If your agent uses IAM auth, the Cognito Identity Pool's authenticated role must be granted permission to invoke the agent.
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts title="packages/infra/src/stacks/application-stack.ts" {5}
+const identity = new UserIdentity(this, 'Identity');
+const myAgent = new MyAgent(this, 'MyAgent');
+
+// Grant the authenticated Cognito role permission to invoke the agent
+myAgent.grantInvokeAccess(identity.identityPool.authenticatedRole);
+```
+
+`grantInvokeAccess` wires up all AgentCore invoke actions (`InvokeAgentRuntime`, `InvokeAgentRuntimeWithWebSocketStream`) on the agent's runtime ARN.
+</Fragment>
+<Fragment slot="terraform">
+```hcl title="packages/infra/src/main.tf"
+module "identity" {
+  source = "../../common/terraform/src/core/user-identity"
+}
+
+module "my_agent" {
+  source = "../../common/terraform/src/app/agents/my-agent"
+
+  appconfig_application_id  = module.runtime_config_appconfig.application_id
+  appconfig_application_arn = module.runtime_config_appconfig.application_arn
+}
+
+# Grant the authenticated Cognito role permission to invoke the agent
+resource "aws_iam_policy" "invoke_my_agent" {
+  name = "InvokeMyAgentPolicy"
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect = "Allow"
+      Action = [
+        "bedrock-agentcore:InvokeAgentRuntime",
+        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
+      ]
+      Resource = [
+        module.my_agent.agent_core_runtime_arn,
+        "${module.my_agent.agent_core_runtime_arn}/*",
+      ]
+    }]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "invoke_my_agent" {
+  role       = module.identity.authenticated_role_name
+  policy_arn = aws_iam_policy.invoke_my_agent.arn
+}
+```
+</Fragment>
+</Infrastructure>
+
+If your agent uses Cognito auth, you do not need to define any additional infrastructure to connect your website to your agent.

package/docs/snippets/connection/strands-agent-rdb-ssl-requirements.mdx

@@ -0,0 +1,35 @@
+---
+title: SSL Requirements when Connecting without RDS Proxy
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+The connection generator updates the Dockerfile to install the Amazon RDS CA bundle at `/usr/local/share/ca-certificates/rds-bundle.crt`. Set `NODE_EXTRA_CA_CERTS` to that path so Node.js trusts the certificate when connecting without RDS Proxy:
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+new MyAgent(this, 'MyAgent', {
+  ...
+  environmentVariables: {
+    NODE_EXTRA_CA_CERTS: '/usr/local/share/ca-certificates/rds-bundle.crt',
+  },
+});
+```
+
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_agent" {
+  ...
+  environment_variables = {
+    NODE_EXTRA_CA_CERTS = "/usr/local/share/ca-certificates/rds-bundle.crt"
+  }
+}
+```
+
+</Fragment>
+</Infrastructure>
+
+For more details, see the [Amazon RDS SSL/TLS documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.SSL.html). When using RDS Proxy, you do not need to configure `NODE_EXTRA_CA_CERTS`.

package/docs/snippets/lambda-function/architecture.mdx

@@ -0,0 +1,36 @@
+---
+title: Lambda Function Architecture
+---
+
+The deployed function has the following architecture:
+
+```d2 inline=true
+direction: right
+
+source: Event Source\n(SNS, SQS, ...) {
+  shape: rectangle
+}
+
+lambda: Lambda {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/lambda.svg
+}
+
+cw: CloudWatch\n(Logs, Metrics) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/cloudwatch.svg
+  near: top-right
+}
+
+xray: X-Ray\n(Traces) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/xray.svg
+  near: bottom-right
+}
+
+source -> lambda
+lambda -> cw
+lambda -> xray
+```
+
+The generator vends the function itself; you wire the event source up in your stack to invoke it (for example, an API Gateway integration, an EventBridge rule, an S3 notification or an SQS event source mapping).

package/docs/snippets/lambda-function/deploying-your-function.mdx

@@ -0,0 +1,118 @@
+---
+title: Deploying your Function
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+This generator creates CDK or Terraform infrastructure as code based on your selected `iacProvider`. You can use this to deploy your function.
+
+<Infrastructure>
+<Fragment slot="cdk">
+This generator creates a CDK construct for deploying your function in the `common/constructs` folder. You can use this in a CDK application:
+
+```typescript {1, 6}
+import { MyProjectMyFunction } from ':my-scope/common-constructs';
+
+export class ExampleStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    // Add the function to your stack
+    const fn = new MyProjectMyFunction(this, 'MyFunction');
+  }
+}
+```
+
+This sets up:
+
+1. AWS Lambda function
+2. CloudWatch log group
+3. X-Ray tracing configuration
+4. CloudWatch metrics namespace
+
+This function can then be used as a target for any lambda [event source](https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parser/):
+
+:::note[Event Source Matching]
+Ensure the event source matches the selected `eventSource` option to ensure the event is properly handled within your handler function.
+:::
+
+The example below demonstrates the CDK code for invoking your lambda function on a schedule using EventBridge:
+
+```typescript
+import { Rule, Schedule } from 'aws-cdk-lib/aws-events';
+import { LambdaFunction } from 'aws-cdk-lib/aws-events-targets';
+import { MyProjectMyFunction } from ':my-scope/common-constructs';
+
+export class ExampleStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    // Add the function to your stack
+    const fn = new MyProjectMyFunction(this, 'MyFunction');
+
+    // Add the function to an EventBridge scheduled rule
+    const eventRule = new Rule(this, 'MyFunctionScheduleRule', {
+      schedule: Schedule.cron({ minute: '15' }),
+      targets: [new LambdaFunction(fn)],
+    });
+  }
+}
+```
+</Fragment>
+<Fragment slot="terraform">
+This generator creates a Terraform module for deploying your function in the `common/terraform` folder. Instantiate the shared `core/asset-bucket` module once per deployment and pass its `bucket_name` into the `asset_bucket_name` input:
+
+```hcl
+module "asset_bucket" {
+  source = "../../common/terraform/src/core/asset-bucket"
+}
+
+module "my_project_my_function" {
+  source = "../../common/terraform/src/app/lambda-functions/my-project-my-function"
+
+  asset_bucket_name = module.asset_bucket.bucket_name
+
+  env = {
+    SOME_VARIABLE = "some value"
+  }
+
+  additional_iam_policy_statements = [
+    # Add any additional permissions your function needs
+  ]
+}
+```
+
+This sets up:
+
+1. AWS Lambda function
+2. CloudWatch log group
+3. X-Ray tracing configuration
+4. CloudWatch metrics namespace
+
+This function can then be used as a target for any lambda event source. The example below demonstrates the Terraform code for invoking your lambda function on a schedule using EventBridge:
+
+```hcl
+# EventBridge rule for scheduled execution
+resource "aws_cloudwatch_event_rule" "my_function_schedule" {
+  name                = "my-function-schedule"
+  description         = "Trigger my function every 15 minutes"
+  schedule_expression = "cron(15 * * * ? *)"
+}
+
+# EventBridge target
+resource "aws_cloudwatch_event_target" "lambda_target" {
+  rule      = aws_cloudwatch_event_rule.my_function_schedule.name
+  target_id = "MyFunctionTarget"
+  arn       = module.my_project_my_function.function_arn
+}
+
+# Permission for EventBridge to invoke the Lambda function
+resource "aws_lambda_permission" "allow_eventbridge" {
+  statement_id  = "AllowExecutionFromEventBridge"
+  action        = "lambda:InvokeFunction"
+  function_name = module.my_project_my_function.function_name
+  principal     = "events.amazonaws.com"
+  source_arn    = aws_cloudwatch_event_rule.my_function_schedule.arn
+}
+```
+
+:::note[Event Source Matching]
+Ensure the event source matches the selected `eventSource` option to ensure the event is properly handled within your handler function.
+:::
+</Fragment>
+</Infrastructure>

package/docs/snippets/mcp/architecture.mdx

@@ -0,0 +1,58 @@
+---
+title: MCP Server Architecture
+---
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+<Tabs syncKey="computeType">
+<TabItem label="Bedrock AgentCore Runtime" _filter={{ computeType: 'BedrockAgentCoreRuntime' }}>
+
+When deployed to [Bedrock AgentCore Runtime](https://aws.amazon.com/bedrock/agentcore/), the MCP server is built into a container image, pushed to Amazon ECR, and run in AgentCore Runtime. AI assistants invoke the AgentCore Runtime data plane endpoint, which forwards `tools/*` and `resources/*` calls to your server over the [streamable HTTP transport](https://modelcontextprotocol.io/specification/draft/basic/transports#streamable-http).
+
+```d2 inline=true
+direction: right
+
+assistant: AI Assistant {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/client.svg
+}
+
+ecr: ECR {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/ecr.svg
+}
+
+agentcore: MCP Server\n(AgentCore Runtime) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/bedrock-agentcore.svg
+}
+
+cw: CloudWatch\n(Logs, Metrics) {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/cloudwatch.svg
+}
+
+assistant -> agentcore: Streamable\nHTTP
+ecr -> agentcore: Container\nimage
+agentcore -> cw
+```
+</TabItem>
+<TabItem label="None (local only)" _filter={{ computeType: 'None' }}>
+
+With `computeType: None`, no AWS infrastructure is generated. The MCP server is configured for local STDIO and HTTP transports only, and is consumed by AI assistants running on the same machine.
+
+```d2 inline=true
+direction: right
+
+assistant: AI Assistant {
+  shape: image
+  icon: /nx-plugin-for-aws/icons/aws/client.svg
+}
+
+server: MCP Server\n(local process) {
+  shape: rectangle
+}
+
+assistant -> server: STDIO\nor\nStreamable HTTP
+```
+</TabItem>
+</Tabs>

package/docs/snippets/mcp/assistant-docs.mdx

@@ -0,0 +1,10 @@
+---
+title: MCP AI Assistant docs
+---
+- [Kiro](https://kiro.dev/docs/mcp/configuration/)
+- [Kiro CLI](https://kiro.dev/docs/cli/mcp/)
+- [Claude Code](https://code.claude.com/docs/en/mcp)
+- [Cursor](https://cursor.com/docs/mcp)
+- [Codex](https://github.com/openai/codex)
+- [Cline](https://docs.cline.bot/mcp/mcp-overview)
+- [Roo Code](https://docs.roocode.com/features/mcp/using-mcp-in-roo)