@aws/nx-plugin 1.0.0-rc.7 → 1.0.0-rc.71

package/src/py/mcp-server/__snapshots__/generator.spec.ts.snap

@@ -8,13 +8,14 @@ exports[`py#mcp-server generator > should match snapshot for BedrockAgentCoreRun
 exports[`py#mcp-server generator > should match snapshot for BedrockAgentCoreRuntime generated constructs files > core-index.ts 1`] = `
 "export * from './app.js';
 export * from './checkov.js';
+export * from './cloudfront.js';
 export * from './runtime-config.js';
 export * from './workspace.js';
 "
 `;
 
 exports[`py#mcp-server generator > should match snapshot for BedrockAgentCoreRuntime generated constructs files > mcp-server-construct.ts 1`] = `
-"import { Lazy, Names } from 'aws-cdk-lib';
+"import { Fn, Lazy, Names, Stack } from 'aws-cdk-lib';
 import { Platform } from 'aws-cdk-lib/aws-ecr-assets';
 import { Connections, IConnectable } from 'aws-cdk-lib/aws-ec2';
 import { Construct } from 'constructs';
@@ -44,6 +45,8 @@ export class SnapshotBedrockServer
 {
   public readonly dockerImage: AgentRuntimeArtifact;
   public readonly agentCoreRuntime: Runtime;
+  /** Default Gateway target name for this MCP server. */
+  public readonly mcpServerName = 'snapshot-bedrock-server';
 
   constructor(
     scope: Construct,
@@ -82,7 +85,9 @@ export class SnapshotBedrockServer
 
     rc.set('agentcore', 'agentRuntimes', {
       ...rc.get('agentcore').agentRuntimes,
-      SnapshotBedrockServer: this.agentCoreRuntime.agentRuntimeArn,
+      SnapshotBedrockServer: {
+        arn: this.agentCoreRuntime.agentRuntimeArn,
+      },
     });
   }
 
@@ -100,6 +105,23 @@ export class SnapshotBedrockServer
     return this.agentCoreRuntime.connections;
   }
 
+  /**
+   * The MCP endpoint URL of the runtime, e.g. for use as a Gateway target
+   * endpoint.
+   */
+  public get invocationUrl(): string {
+    // The URL must URL-encode the runtime ARN (':' -> '%3A', '/' -> '%2F').
+    // The ARN is a CDK token, so encode at deploy time via Fn.join/Fn.split.
+    const encodedArn = Fn.join(
+      '%2F',
+      Fn.split(
+        '/',
+        Fn.join('%3A', Fn.split(':', this.agentCoreRuntime.agentRuntimeArn)),
+      ),
+    );
+    return \`https://bedrock-agentcore.\${Stack.of(this).region}.amazonaws.com/runtimes/\${encodedArn}/invocations?qualifier=DEFAULT\`;
+  }
+
   /**
    * Grants IAM permissions to invoke this agent runtime.
    *
@@ -133,15 +155,15 @@ exports[`py#mcp-server generator > should match snapshot for Terraform generated
   required_providers {
     aws = {
       source  = "hashicorp/aws"
-      version = ">= 6.23"
+      version = "6.60.0"
     }
     null = {
       source  = "hashicorp/null"
-      version = ">= 3.0"
+      version = "3.3.0"
     }
     random = {
       source  = "hashicorp/random"
-      version = ">= 3.0"
+      version = "3.9.0"
     }
   }
 }
@@ -199,6 +221,30 @@ variable "additional_iam_policy_statements" {
   default = []
 }
 
+# VPC Configuration (optional)
+variable "enable_vpc" {
+  description = "Run the agent core runtime inside a VPC. Set alongside vpc_id/subnet_ids."
+  type        = bool
+  default     = false
+}
+
+variable "vpc_id" {
+  description = "VPC ID to run the agent core runtime in. Required when enable_vpc is true."
+  type        = string
+  default     = null
+
+  validation {
+    condition     = !var.enable_vpc || (var.vpc_id != null && var.subnet_ids != null)
+    error_message = "vpc_id and subnet_ids must be set when enable_vpc is true."
+  }
+}
+
+variable "subnet_ids" {
+  description = "Subnet IDs to run the agent core runtime in. Required when enable_vpc is true."
+  type        = list(string)
+  default     = null
+}
+
 variable "tags" {
   description = "Tags to apply to resources"
   type        = map(string)
@@ -224,8 +270,7 @@ resource "aws_ecr_repository" "agent_core_repository" {
   #checkov:skip=CKV_AWS_136:AES256 encryption is sufficient for ECR repositories
   name = "\${lower(var.agent_runtime_name)}_repository_\${random_id.unique_suffix.hex}"
 
-  #checkov:skip=CKV_AWS_51:Image tag is reused for latest deployments
-  image_tag_mutability = "MUTABLE"
+  image_tag_mutability = "IMMUTABLE"
   force_delete         = true
 
   image_scanning_configuration {
@@ -399,30 +444,64 @@ data "external" "docker_digest" {
   program = ["sh", "-c", "echo '{\\"digest\\":\\"'$(docker inspect \${var.docker_image_tag} --format '{{.Id}}')'\\"}' "]
 }
 
+locals {
+  # Content-based, immutable image tag derived from the local image digest
+  image_tag = replace(data.external.docker_digest.result.digest, "sha256:", "")
+}
+
 # Null resource for container image publish
 resource "null_resource" "docker_publish" {
   triggers = {
     docker_digest    = data.external.docker_digest.result.digest
     repository_url   = aws_ecr_repository.agent_core_repository.repository_url
     docker_image_tag = var.docker_image_tag
+    image_tag        = local.image_tag
   }
 
   provisioner "local-exec" {
     command = <<-EOT
       # Get ECR login token
-      aws ecr get-login-password --region \${local.aws_region} | docker login --username AWS --password-stdin \${self.triggers.repository_url}
+      aws ecr get-login-password --region "$AWS_REGION" | docker login --username AWS --password-stdin "$REPOSITORY_URL"
 
-      # Tag the image
-      docker tag \${self.triggers.docker_image_tag} \${self.triggers.repository_url}:latest
+      # Tag the image with the immutable content-based tag
+      docker tag "$DOCKER_IMAGE_TAG" "$REPOSITORY_URL:$IMAGE_TAG"
 
       # Push the image
-      docker push \${self.triggers.repository_url}:latest
+      docker push "$REPOSITORY_URL:$IMAGE_TAG"
     EOT
+    environment = {
+      AWS_REGION       = local.aws_region
+      REPOSITORY_URL   = self.triggers.repository_url
+      DOCKER_IMAGE_TAG = self.triggers.docker_image_tag
+      IMAGE_TAG        = self.triggers.image_tag
+    }
   }
 
   depends_on = [aws_ecr_repository_policy.agent_core_ecr_policy]
 }
 
+# Security group for the agent core runtime, used when running inside a VPC
+resource "aws_security_group" "agent_core_runtime" {
+  count = var.enable_vpc ? 1 : 0
+
+  #checkov:skip=CKV2_AWS_5:Attached to the runtime via network_configuration; Checkov cannot resolve this reference
+  name_prefix = "\${var.agent_runtime_name}-runtime-"
+  description = "Security group for the \${var.agent_runtime_name} agent core runtime"
+  vpc_id      = var.vpc_id
+  tags        = var.tags
+}
+
+resource "aws_vpc_security_group_egress_rule" "agent_core_runtime_https" {
+  count = var.enable_vpc ? 1 : 0
+
+  security_group_id = aws_security_group.agent_core_runtime[0].id
+  cidr_ipv4         = "0.0.0.0/0"
+  from_port         = 443
+  to_port           = 443
+  ip_protocol       = "tcp"
+  description       = "Allow outbound HTTPS to AWS service endpoints"
+}
+
 # Bedrock AgentCore Agent Runtime
 resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
   agent_runtime_name = "\${var.agent_runtime_name}_\${random_id.unique_suffix.hex}"
@@ -431,7 +510,7 @@ resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
 
   agent_runtime_artifact {
     container_configuration {
-      container_uri = "\${aws_ecr_repository.agent_core_repository.repository_url}:latest"
+      container_uri = "\${aws_ecr_repository.agent_core_repository.repository_url}:\${local.image_tag}"
     }
   }
 
@@ -448,8 +527,24 @@ resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
     }
   }
 
+  # Receive the caller's Authorization header (validated by the JWT authorizer).
+  dynamic "request_header_configuration" {
+    for_each = var.authorizer_configuration != null && try(var.authorizer_configuration.custom_jwt_authorizer, null) != null ? [1] : []
+    content {
+      request_header_allowlist = ["Authorization"]
+    }
+  }
+
   network_configuration {
-    network_mode = "PUBLIC"
+    network_mode = var.enable_vpc ? "VPC" : "PUBLIC"
+
+    dynamic "network_mode_config" {
+      for_each = var.enable_vpc ? [1] : []
+      content {
+        security_groups = [aws_security_group.agent_core_runtime[0].id]
+        subnets         = var.subnet_ids
+      }
+    }
   }
 
   protocol_configuration {
@@ -464,7 +559,70 @@ resource "aws_bedrockagentcore_agent_runtime" "agent_runtime" {
   ]
 }
 
+# MCP consumers (e.g. gateway targets, which fetch tools at creation) can race
+# the runtime's first cold start, so probe it until it serves MCP. The ARN
+# output is routed through this resource so consumers wait for readiness.
+resource "null_resource" "runtime_ready" {
+  count = var.server_protocol == "MCP" ? 1 : 0
+
+  triggers = {
+    runtime_arn = aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_arn
+  }
+
+  provisioner "local-exec" {
+    command = <<-EOT
+      uv run --with boto3==1.43.67 python -c "
+import boto3
+import json
+import os
+import time
+import uuid
+
+runtime_arn = os.environ['RUNTIME_ARN']
+client = boto3.client('bedrock-agentcore')
+initialize_request = json.dumps({
+    'jsonrpc': '2.0',
+    'id': 1,
+    'method': 'initialize',
+    'params': {
+        'protocolVersion': '2025-03-26',
+        'capabilities': {},
+        'clientInfo': {'name': 'readiness-probe', 'version': '1.0'},
+    },
+})
+
+deadline = time.time() + 5 * 60
+while True:
+    try:
+        client.invoke_agent_runtime(
+            agentRuntimeArn=runtime_arn,
+            runtimeSessionId=f'readiness-probe-{uuid.uuid4()}',
+            contentType='application/json',
+            accept='application/json, text/event-stream',
+            payload=initialize_request,
+        )
+        break
+    except Exception:
+        if time.time() >= deadline:
+            raise
+        time.sleep(5)
+
+print(f'Runtime {runtime_arn} is serving MCP')
+"
+    EOT
+    environment = {
+      RUNTIME_ARN = self.triggers.runtime_arn
+    }
+  }
+}
+
 # Outputs
+locals {
+  # For MCP runtimes the ARN flows through the readiness probe, so consumers
+  # wait until the runtime serves MCP.
+  ready_runtime_arn = var.server_protocol == "MCP" ? null_resource.runtime_ready[0].triggers.runtime_arn : aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_arn
+}
+
 output "agent_core_runtime_role_arn" {
   description = "ARN of the Agent Core Runtime IAM role"
   value       = aws_iam_role.agent_core_runtime_role.arn
@@ -481,8 +639,13 @@ output "agent_runtime_name" {
 }
 
 output "agent_core_runtime_arn" {
-  description = "ARN of the Bedrock Agent Core runtime"
-  value       = aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_arn
+  description = "ARN of the Bedrock Agent Core runtime. For MCP runtimes the value flows through the readiness probe, so consumers wait until the runtime serves MCP."
+  value       = local.ready_runtime_arn
+}
+
+output "invocation_url" {
+  description = "HTTPS invocation URL of the runtime. MCP runtimes get the MCP endpoint (e.g. for use as a Gateway target endpoint), A2A runtimes the A2A endpoint (trailing slash required). For MCP runtimes the value flows through the readiness probe, so consumers wait until the runtime serves MCP."
+  value       = "https://bedrock-agentcore.\${local.aws_region}.amazonaws.com/runtimes/\${urlencode(local.ready_runtime_arn)}/invocations\${var.server_protocol == "A2A" ? "/" : "?qualifier=DEFAULT"}"
 }
 
 output "agent_runtime_id" {
@@ -494,6 +657,11 @@ output "agent_runtime_version" {
   description = "Version of the Bedrock Agent Core runtime"
   value       = aws_bedrockagentcore_agent_runtime.agent_runtime.agent_runtime_version
 }
+
+output "security_group_id" {
+  description = "Security group ID of the agent core runtime, for use in ingress rules on resources it must reach (e.g. a database). Null unless enable_vpc is true."
+  value       = var.enable_vpc ? aws_security_group.agent_core_runtime[0].id : null
+}
 "
 `;
 
@@ -520,6 +688,25 @@ variable "tags" {
   default     = {}
 }
 
+# VPC Configuration (optional)
+variable "enable_vpc" {
+  description = "Run the agent core runtime inside a VPC. Set alongside vpc_id/subnet_ids."
+  type        = bool
+  default     = false
+}
+
+variable "vpc_id" {
+  description = "VPC ID to run the agent core runtime in. Required when enable_vpc is true."
+  type        = string
+  default     = null
+}
+
+variable "subnet_ids" {
+  description = "Subnet IDs to run the agent core runtime in. Required when enable_vpc is true."
+  type        = list(string)
+  default     = null
+}
+
 variable "appconfig_application_id" {
   description = "ID of the shared runtime-config AppConfig application (from \`core/runtime-config/appconfig.application_id\`). The agent reads its runtime configuration from this application."
   type        = string
@@ -535,6 +722,9 @@ module "agent_core_runtime" {
   agent_runtime_name = "TerraformSnapshotServer"
   docker_image_tag = "proj-terraform-snapshot-server:latest"
   server_protocol = "MCP"
+  enable_vpc = var.enable_vpc
+  vpc_id = var.vpc_id
+  subnet_ids = var.subnet_ids
 
   env = merge({
     RUNTIME_CONFIG_APP_ID = var.appconfig_application_id
@@ -558,7 +748,7 @@ module "add_agent_runtime_to_runtime_config" {
 
   namespace = "agentcore"
   key       = "agentRuntimes"
-  value     = { "TerraformSnapshotServer" = module.agent_core_runtime.agent_core_runtime_arn }
+  value     = { "TerraformSnapshotServer" = { arn = module.agent_core_runtime.agent_core_runtime_arn } }
 
   depends_on = [module.agent_core_runtime]
 }
@@ -573,10 +763,20 @@ output "agent_core_runtime_arn" {
   value       = module.agent_core_runtime.agent_core_runtime_arn
 }
 
+output "invocation_url" {
+  description = "HTTPS invocation URL of the runtime (the MCP endpoint, e.g. for use as a Gateway target endpoint)"
+  value       = module.agent_core_runtime.invocation_url
+}
+
 output "appconfig_application_id" {
   description = "AppConfig Application ID for runtime config (passthrough of the shared \`appconfig_application_id\` input)."
   value       = var.appconfig_application_id
 }
+
+output "security_group_id" {
+  description = "Security group ID of the agent core runtime, for use in ingress rules on resources it must reach (e.g. a database). Null unless enable_vpc is true."
+  value       = module.agent_core_runtime.security_group_id
+}
 "
 `;
 
@@ -646,11 +846,11 @@ exports[`py#mcp-server generator > should match snapshot for generated files > u
 name = "proj.test_project"
 version = "0.1.0"
 dependencies = [
-  "aws-lambda-powertools==3.29.0",
-  "mcp==1.27.2",
-  "uvicorn==0.48.0",
-  "boto3==1.43.20",
-  "aws-opentelemetry-distro==0.17.1"
+  "aws-lambda-powertools==3.31.1",
+  "mcp==1.28.1",
+  "uvicorn==0.52.1",
+  "boto3==1.43.67",
+  "aws-opentelemetry-distro==0.19.0"
 ]
 
 [dependency-groups]

package/src/py/mcp-server/files/deploy/Dockerfile.template

@@ -1,4 +1,11 @@
-FROM public.ecr.aws/docker/library/python:3.14-slim
+FROM <%- pythonBaseImage %>
+
+# Remove the base image's pip: the server runs from the bundled environment and
+# never needs it at runtime, and pip's vendored packages carry known
+# HIGH/CRITICAL vulnerabilities flagged by the image scan.
+RUN python -m pip uninstall -y pip && \
+    rm -rf /usr/local/lib/python*/site-packages/pip \
+           /usr/local/lib/python*/site-packages/pip-*.dist-info
 
 WORKDIR /app
 

package/src/py/mcp-server/generator.d.ts

@@ -4,7 +4,75 @@
  */
 import { type GeneratorCallback, type Tree } from '@nx/devkit';
 import { type NxGeneratorInfo } from '../../utils/nx';
+import type { IacMetadata } from '../../utils/shared-constructs-constants';
 import type { PyMcpServerGeneratorSchema } from './schema';
+/** The metadata this generator records, which its predicates read. */
+export interface PyMcpServerMetadata extends IacMetadata {
+    readonly port: number;
+    readonly rc: string;
+    readonly auth: string;
+}
+export declare const DEPENDENCIES: import("../../utils/declared-dependencies").DependencyDeclaration<readonly [{
+    readonly name: "@modelcontextprotocol/inspector";
+    readonly dev: true;
+    readonly root: true;
+}, {
+    readonly name: "ncp";
+} & {
+    versionOnly: true;
+}, {
+    readonly name: "rimraf";
+} & {
+    versionOnly: true;
+}, {
+    readonly name: "make-dir-cli";
+} & {
+    versionOnly: true;
+}, {
+    readonly name: "cpy-cli";
+} & {
+    versionOnly: true;
+}, {
+    readonly name: "ncp";
+} & {
+    versionOnly: true;
+}, {
+    readonly name: "rimraf";
+} & {
+    versionOnly: true;
+}, {
+    readonly name: "make-dir-cli";
+} & {
+    versionOnly: true;
+}, {
+    readonly name: "cpy-cli";
+} & {
+    versionOnly: true;
+}, {
+    readonly name: "constructs";
+    readonly when: (m: IacMetadata) => boolean;
+} & {
+    versionOnly: true;
+}, {
+    readonly name: "aws-cdk-lib";
+    readonly when: (m: IacMetadata) => boolean;
+} & {
+    versionOnly: true;
+}, {
+    readonly name: "@types/node";
+} & {
+    versionOnly: true;
+}], readonly [{
+    readonly name: "aws-lambda-powertools";
+}, {
+    readonly name: "mcp";
+}, {
+    readonly name: "uvicorn";
+}, {
+    readonly name: "boto3";
+}, {
+    readonly name: "aws-opentelemetry-distro";
+}]>;
 export declare const PY_MCP_SERVER_GENERATOR_INFO: NxGeneratorInfo;
 export declare const pyMcpServerGenerator: (tree: Tree, options: PyMcpServerGeneratorSchema) => Promise<GeneratorCallback>;
 export default pyMcpServerGenerator;