@aws/nx-plugin 1.0.0-rc.4 → 1.0.0-rc.41

package/README.md

@@ -137,16 +137,16 @@ pnpm create @aws/nx-workspace my-project
 cd my-project
 
 # Add a tRPC API
-pnpm nx g @aws/nx-plugin:ts#trpc-api
+pnpm nx g @aws/nx-plugin:ts#api --framework=trpc
 
 # Add a Strands AI agent (Python)
 pnpm nx g @aws/nx-plugin:py#agent
 
 # Add a React website
-pnpm nx g @aws/nx-plugin:ts#react-website
+pnpm nx g @aws/nx-plugin:ts#website --framework=react
 
 # Add authentication to your website
-pnpm nx g @aws/nx-plugin:ts#react-website#auth
+pnpm nx g @aws/nx-plugin:ts#website#auth
 
 # Connect your website to your API and agent
 pnpm nx g @aws/nx-plugin:connection
@@ -162,17 +162,17 @@ pnpm nx g @aws/nx-plugin:ts#infra
 | Generator               | Description                                                                                                       |
 | ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
 | `ts#project`            | TypeScript library                                                                                                |
-| `ts#trpc-api`           | tRPC API with API Gateway + Lambda + [Powertools](https://github.com/aws-powertools/powertools-lambda-typescript) |
+| `ts#api`                | TypeScript API (tRPC or Smithy) with API Gateway + Lambda + [Powertools](https://github.com/aws-powertools/powertools-lambda-typescript) |
 | `ts#rdb`                | Relational databases with Aurora RDS                                                                              |
-| `ts#react-website`      | React app (Vite)                                                                                                  |
-| `ts#react-website#auth` | Add Cognito auth to a React website                                                                               |
+| `ts#website`            | React app (Vite)                                                                                                  |
+| `ts#website#auth`       | Add Cognito auth to a website                                                                                     |
 | `ts#infra`              | AWS CDK infrastructure project                                                                                    |
 | `ts#lambda-function`    | TypeScript Lambda with type-safe event sources                                                                    |
 | `ts#mcp-server`         | MCP server (TypeScript)                                                                                           |
 | `ts#agent`              | [Strands Agent](https://strandsagents.com/) (TypeScript)                                                          |
 | `ts#nx-generator`       | Nx generator scaffold                                                                                             |
 | `py#project`            | Python project (uv)                                                                                               |
-| `py#fast-api`           | FastAPI with API Gateway + Lambda + [Powertools](https://github.com/aws-powertools/powertools-lambda-python)      |
+| `py#api`                | Python API (FastAPI) with API Gateway + Lambda + [Powertools](https://github.com/aws-powertools/powertools-lambda-python)      |
 | `py#lambda-function`    | Python Lambda with type-safe event sources                                                                        |
 | `py#mcp-server`         | MCP server (Python)                                                                                               |
 | `py#agent`              | [Strands Agent](https://strandsagents.com/) (Python)                                                              |

package/executors.json

@@ -0,0 +1,9 @@
+{
+  "executors": {
+    "license-check": {
+      "implementation": "./src/license/dependency-check/executor",
+      "schema": "./src/license/dependency-check/executor-schema.json",
+      "description": "Check that all workspace dependencies conform to a license allowlist"
+    }
+  }
+}

package/generators.json

@@ -3,6 +3,33 @@
   "name": "@aws/nx-plugin",
   "version": "0.0.1",
   "generators": {
+    "init": {
+      "factory": "./src/init/generator",
+      "schema": "./src/init/schema.json",
+      "description": "Configure an existing Nx workspace to use the @aws/nx-plugin",
+      "metric": "g57",
+      "guidePages": ["existing-project"]
+    },
+    "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 +50,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 +310,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 +324,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",
@@ -353,7 +398,7 @@
     "ts#dynamodb": {
       "factory": "./src/ts/dynamodb/generator",
       "schema": "./src/ts/dynamodb/schema.json",
-      "description": "Create a DynamoDB project",
+      "description": "Create a TypeScript DynamoDB project",
       "metric": "g43"
     },
     "ts#dynamodb#trpc-connection": {
@@ -383,6 +428,60 @@
       "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
+    },
+    "py#rdb": {
+      "factory": "./src/py/rdb/generator",
+      "schema": "./src/py/rdb/schema.json",
+      "description": "Create a Python relational database project",
+      "metric": "g56"
+    },
+    "py#rdb#fast-api-connection": {
+      "factory": "./src/py/rdb/fast-api-connection/generator",
+      "schema": "./src/py/rdb/fast-api-connection/schema.json",
+      "description": "Connect a py#fast-api project to a py#rdb project",
+      "metric": "g57",
+      "hidden": true
+    },
+    "py#rdb#agent-connection": {
+      "factory": "./src/py/rdb/agent-connection/generator",
+      "schema": "./src/py/rdb/agent-connection/schema.json",
+      "description": "Connect a py#agent to a py#rdb project",
+      "metric": "g58",
+      "hidden": true
+    },
+    "py#rdb#mcp-server-connection": {
+      "factory": "./src/py/rdb/mcp-server-connection/generator",
+      "schema": "./src/py/rdb/mcp-server-connection/schema.json",
+      "description": "Connect a py#mcp-server to a py#rdb project",
+      "metric": "g59",
+      "hidden": true
     }
   }
 }

package/package.json

@@ -1,46 +1,64 @@
 {
   "name": "@aws/nx-plugin",
-  "version": "1.0.0-rc.4",
+  "version": "1.0.0-rc.41",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",
     "directory": "packages/nx-plugin"
   },
   "private": false,
-  "type": "commonjs",
+  "type": "module",
   "license": "Apache-2.0",
   "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
   "typings": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./sdk/*": {
+      "types": "./src/sdk/*.d.ts",
+      "default": "./src/sdk/*.js"
+    },
+    "./package.json": "./package.json"
+  },
   "publishConfig": {
     "access": "public"
   },
   "bin": {
-    "aws-nx-mcp": "./bin/aws-nx-mcp.js"
+    "aws-nx-mcp": "./src/bin/aws-nx-mcp.js"
   },
   "generators": "./generators.json",
+  "executors": "./executors.json",
+  "engines": {
+    "node": ">=20.19.0"
+  },
   "peerDependencies": {
-    "nx": "22.7.5",
-    "prettier": "3.8.3"
+    "nx": "23.1.0"
   },
   "dependencies": {
     "@apidevtools/swagger-parser": "12.1.0",
+    "@biomejs/js-api": "6.0.0",
+    "@biomejs/wasm-nodejs": "2.5.3",
     "@getgrit/gritql": "0.0.3",
-    "@hey-api/openapi-ts": "0.64.13",
     "@iarna/toml": "2.2.5",
     "@modelcontextprotocol/sdk": "1.29.0",
-    "@nx/devkit": "22.7.5",
-    "@nx/eslint": "22.7.5",
-    "@nx/js": "22.7.5",
-    "@nx/react": "22.7.5",
-    "@nx/vite": "22.7.5",
+    "@nx/devkit": "23.1.0",
+    "@nx/js": "23.1.0",
+    "@nx/react": "23.1.0",
+    "@nx/vite": "23.1.0",
     "@types/estree": "1.0.9",
     "@types/js-yaml": "4.0.9",
     "@types/mdast": "4.0.4",
-    "@nxlv/python": "22.1.4",
+    "@nxlv/python": "22.2.1",
     "@phenomnomnominal/tsquery": "6.2.0",
     "enquirer": "2.4.1",
     "fast-glob": "3.3.3",
-    "js-yaml": "4.2.0",
+    "jiti": "2.7.0",
+    "js-yaml": "4.3.0",
+    "license-checker-rseidelsohn": "4.4.2",
     "lodash.camelcase": "4.3.0",
     "lodash.clonedeepwith": "4.5.0",
     "lodash.deburr": "4.1.0",
@@ -55,12 +73,12 @@
     "remark-mdx": "3.1.1",
     "remark-parse": "11.0.0",
     "remark-stringify": "11.0.0",
+    "spdx-satisfies": "6.0.0",
     "typescript": "6.0.3",
     "unified": "11.0.5",
     "unist-util-visit": "5.1.0",
-    "vite": "8.0.14",
-    "vitest": "4.1.7",
+    "vite": "8.1.4",
+    "vitest": "4.1.10",
     "zod": "4.4.3"
-  },
-  "types": "./src/index.d.ts"
+  }
 }

package/src/agentcore-gateway/attach-upstream.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type ProjectConfiguration, type Tree } from '@nx/devkit';
+export interface LocalGatewayUpstream {
+    /**
+     * Gateway target name for the upstream — prefixes its tools as
+     * `<targetName>___<toolName>` both locally and deployed.
+     */
+    targetName: string;
+    /**
+     * Local port the upstream MCP endpoint listens on.
+     */
+    port: number;
+    /**
+     * Project providing the upstream's dev target.
+     */
+    upstreamProjectName: string;
+    /**
+     * Name of the upstream's dev target.
+     */
+    upstreamDevTargetName: string;
+}
+/**
+ * Attach an upstream MCP endpoint (an MCP server or another gateway's local
+ * gateway) to a gateway's local gateway.
+ *
+ * Chains the gateway's dev target onto the upstream's dev target, and
+ * registers the upstream in the gateway's local-dev.ts so the local gateway
+ * aggregates its tools.
+ */
+export declare const attachUpstreamToLocalGateway: (tree: Tree, gatewayProject: ProjectConfiguration, gatewayDevTargetName: string, upstream: LocalGatewayUpstream) => Promise<void>;

package/src/agentcore-gateway/attach-upstream.js

@@ -0,0 +1,38 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { joinPathFragments, updateProjectConfiguration } from "@nx/devkit";
+import { applyGritQL } from "../utils/ast.js";
+import { addDependencyToTargetIfNotPresent } from "../utils/nx.js";
+/**
+ * Attach an upstream MCP endpoint (an MCP server or another gateway's local
+ * gateway) to a gateway's local gateway.
+ *
+ * Chains the gateway's dev target onto the upstream's dev target, and
+ * registers the upstream in the gateway's local-dev.ts so the local gateway
+ * aggregates its tools.
+ */ export const attachUpstreamToLocalGateway = async (tree, gatewayProject, gatewayDevTargetName, upstream)=>{
+    // 1. Wire dev chain
+    if (gatewayProject.targets?.[gatewayDevTargetName]) {
+        addDependencyToTargetIfNotPresent(gatewayProject, gatewayDevTargetName, {
+            projects: [
+                upstream.upstreamProjectName
+            ],
+            target: upstream.upstreamDevTargetName
+        });
+        updateProjectConfiguration(tree, gatewayProject.name, gatewayProject);
+    }
+    // 2. Register the upstream in the gateway's local local-dev.ts
+    const serveTsPath = joinPathFragments(gatewayProject.root, 'local-dev.ts');
+    if (tree.exists(serveTsPath)) {
+        const entry = `{ name: '${upstream.targetName}', url: 'http://localhost:${upstream.port}/mcp' }`;
+        await applyGritQL(tree, serveTsPath, `or {
+  \`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = []\` => \`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [${entry}]\`,
+  \`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [$items]\` => \`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [${entry}, $items]\` where {
+    $items <: not contains \`'${upstream.targetName}'\`
+  }
+}`);
+    }
+};
+
+//# sourceMappingURL=attach-upstream.js.map

package/src/agentcore-gateway/attach-upstream.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/agentcore-gateway/attach-upstream.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  joinPathFragments,\n  type ProjectConfiguration,\n  type Tree,\n  updateProjectConfiguration,\n} from '@nx/devkit';\nimport { applyGritQL } from '../utils/ast';\nimport { addDependencyToTargetIfNotPresent } from '../utils/nx';\n\nexport interface LocalGatewayUpstream {\n  /**\n   * Gateway target name for the upstream — prefixes its tools as\n   * `<targetName>___<toolName>` both locally and deployed.\n   */\n  targetName: string;\n  /**\n   * Local port the upstream MCP endpoint listens on.\n   */\n  port: number;\n  /**\n   * Project providing the upstream's dev target.\n   */\n  upstreamProjectName: string;\n  /**\n   * Name of the upstream's dev target.\n   */\n  upstreamDevTargetName: string;\n}\n\n/**\n * Attach an upstream MCP endpoint (an MCP server or another gateway's local\n * gateway) to a gateway's local gateway.\n *\n * Chains the gateway's dev target onto the upstream's dev target, and\n * registers the upstream in the gateway's local-dev.ts so the local gateway\n * aggregates its tools.\n */\nexport const attachUpstreamToLocalGateway = async (\n  tree: Tree,\n  gatewayProject: ProjectConfiguration,\n  gatewayDevTargetName: string,\n  upstream: LocalGatewayUpstream,\n): Promise<void> => {\n  // 1. Wire dev chain\n  if (gatewayProject.targets?.[gatewayDevTargetName]) {\n    addDependencyToTargetIfNotPresent(gatewayProject, gatewayDevTargetName, {\n      projects: [upstream.upstreamProjectName],\n      target: upstream.upstreamDevTargetName,\n    });\n    updateProjectConfiguration(tree, gatewayProject.name, gatewayProject);\n  }\n\n  // 2. Register the upstream in the gateway's local local-dev.ts\n  const serveTsPath = joinPathFragments(gatewayProject.root, 'local-dev.ts');\n  if (tree.exists(serveTsPath)) {\n    const entry = `{ name: '${upstream.targetName}', url: 'http://localhost:${upstream.port}/mcp' }`;\n    await applyGritQL(\n      tree,\n      serveTsPath,\n      `or {\n  \\`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = []\\` => \\`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [${entry}]\\`,\n  \\`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [$items]\\` => \\`const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [${entry}, $items]\\` where {\n    $items <: not contains \\`'${upstream.targetName}'\\`\n  }\n}`,\n    );\n  }\n};\n"],"names":["joinPathFragments","updateProjectConfiguration","applyGritQL","addDependencyToTargetIfNotPresent","attachUpstreamToLocalGateway","tree","gatewayProject","gatewayDevTargetName","upstream","targets","projects","upstreamProjectName","target","upstreamDevTargetName","name","serveTsPath","root","exists","entry","targetName","port"],"mappings":"AAAA;;;CAGC,GACD,SACEA,iBAAiB,EAGjBC,0BAA0B,QACrB,aAAa;AACpB,SAASC,WAAW,QAAQ,kBAAe;AAC3C,SAASC,iCAAiC,QAAQ,iBAAc;AAsBhE;;;;;;;CAOC,GACD,OAAO,MAAMC,+BAA+B,OAC1CC,MACAC,gBACAC,sBACAC;IAEA,oBAAoB;IACpB,IAAIF,eAAeG,OAAO,EAAE,CAACF,qBAAqB,EAAE;QAClDJ,kCAAkCG,gBAAgBC,sBAAsB;YACtEG,UAAU;gBAACF,SAASG,mBAAmB;aAAC;YACxCC,QAAQJ,SAASK,qBAAqB;QACxC;QACAZ,2BAA2BI,MAAMC,eAAeQ,IAAI,EAAER;IACxD;IAEA,+DAA+D;IAC/D,MAAMS,cAAcf,kBAAkBM,eAAeU,IAAI,EAAE;IAC3D,IAAIX,KAAKY,MAAM,CAACF,cAAc;QAC5B,MAAMG,QAAQ,CAAC,SAAS,EAAEV,SAASW,UAAU,CAAC,0BAA0B,EAAEX,SAASY,IAAI,CAAC,OAAO,CAAC;QAChG,MAAMlB,YACJG,MACAU,aACA,CAAC;mHAC4G,EAAEG,MAAM;yHACF,EAAEA,MAAM;8BACnG,EAAEV,SAASW,UAAU,CAAC;;CAEnD,CAAC;IAEA;AACF,EAAE"}

package/src/agentcore-gateway/files/cedar/policies/README.md

@@ -0,0 +1,52 @@
+# Cedar policies for <%= nameClassName %>
+
+Every `.cedar` file in this directory is deployed as a separate `Policy`
+resource attached to this gateway's `PolicyEngine`. The engine runs in
+`ENFORCE` mode, so policies are evaluated and decisions are enforced at
+runtime.
+
+## Default policy
+
+`permit-all.cedar` permits any IAM caller from the deploying AWS account.
+It is scoped to your account because AgentCore's policy validator rejects
+truly unrestricted permits (`permit (principal, action, resource)`) as
+"Overly Permissive".
+
+**If you delete this file without adding replacement `permit` policies, the
+gateway will deny every request** — Cedar uses a default-deny evaluation
+model, so every request requires at least one matching `permit` to be
+allowed.
+
+## Template variables
+
+Policies are [EJS](https://ejs.co/) templates rendered at synth/plan time
+with the following variables in scope:
+
+- `<%%= gatewayArn %>` — this gateway's ARN
+- `<%%= accountId %>` — the AWS account this gateway is deployed into
+
+Add your own variables (e.g. an agent's role name) where the policies are
+rendered:
+
+- CDK: the `cedarPolicyVariables` prop in
+  `packages/common/constructs/src/app/gateways/<name>/<name>.ts`
+- Terraform: the `query` of the `rendered_policies` data source in
+  `packages/common/terraform/src/app/gateways/<name>/<name>.tf`
+
+## Adding a new policy
+
+1. Create `policies/<my-policy>.cedar` alongside the existing files.
+2. Write Cedar rules — see the **Writing Policies** section of the
+   [AgentCore Gateway guide](https://awslabs.github.io/nx-plugin-for-aws/guides/agentcore-gateway/)
+   for valid patterns and validator gotchas.
+3. Re-synth / plan your infrastructure to deploy the new policy.
+
+Policy names are derived from file names: `my-policy.cedar` becomes the
+policy `MyPolicy` (plus a unique suffix, since policy names must be unique
+account-wide). Keep file names unique within this directory.
+
+## Further reading
+
+- [Cedar policy language reference](https://docs.cedarpolicy.com/)
+- [AgentCore policy semantics](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy-understanding-cedar.html)
+- [AgentCore common policy patterns](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/policy-common-patterns.html)

package/src/agentcore-gateway/files/cedar/policies/permit-all.cedar

@@ -0,0 +1,11 @@
+// Default policy: permit any IAM caller from the deploying AWS account.
+// The PolicyEngine runs in ENFORCE mode (default-deny) — deleting this file
+// without a replacement permit denies every call. See policies/README.md.
+
+permit (
+  principal is AgentCore::IamEntity,
+  action,
+  resource == AgentCore::Gateway::"<%%= gatewayArn %>"
+) when {
+  principal.id like "arn:aws:*::<%%= accountId %>:*"
+};

package/src/agentcore-gateway/files/project/local-dev.ts.template

@@ -0,0 +1,134 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import express from 'express';
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+const PORT = parseInt(process.env.PORT || '<%- port %>');
+const PREFIX_SEPARATOR = '___';
+const SESSION_HEADER = 'x-amzn-bedrock-agentcore-runtime-session-id';
+
+interface AttachedMcpServer {
+  name: string;
+  url: string;
+}
+
+// Upstream MCP endpoints attached to this gateway (MCP servers and other
+// gateways), maintained by the `agentcore-gateway#mcp-connection` and
+// `agentcore-gateway#gateway-connection` generators.
+const ATTACHED_MCP_SERVERS: AttachedMcpServer[] = [<% attachedMcpServers.forEach((s) => { %>
+  { name: '<%- s.name %>', url: 'http://localhost:<%- s.port %>/mcp' },<% }); %>
+];
+
+// Forwards the inbound request's AgentCore session header to upstream calls
+const sessionContext = new AsyncLocalStorage<string | undefined>();
+
+const createUpstreamClient = async (url: string): Promise<Client> => {
+  const fetchWithSession: typeof fetch = async (input, init) => {
+    const headers = new Headers(init?.headers);
+    const sessionId = sessionContext.getStore();
+    if (sessionId) headers.set(SESSION_HEADER, sessionId);
+    return fetch(input, { ...init, headers });
+  };
+  const client = new Client({ name: '<%- nameKebabCase %>', version: '1.0.0' });
+  await client.connect(
+    new StreamableHTTPClientTransport(new URL(url), {
+      fetch: fetchWithSession,
+    }),
+  );
+  return client;
+};
+
+/**
+ * Local gateway for <%- nameClassName %>: a single MCP endpoint aggregating
+ * every attached MCP server, with tools exposed as `<target>___<tool>` to
+ * match the deployed AgentCore Gateway. Unlike the real gateway, Cedar
+ * policies are not evaluated and there is no semantic tool search.
+ */
+const createServer = async (): Promise<Server> => {
+  const server = new Server(
+    { name: '<%- nameKebabCase %>', version: '1.0.0' },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const lists = await Promise.all(
+      ATTACHED_MCP_SERVERS.map(async (s) => {
+        const client = await createUpstreamClient(s.url);
+        try {
+          const { tools } = await client.listTools();
+          return tools.map((t) => ({
+            ...t,
+            name: `${s.name}${PREFIX_SEPARATOR}${t.name}`,
+          }));
+        } finally {
+          await client.close();
+        }
+      }),
+    );
+    return { tools: lists.flat() };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const name = request.params.name;
+    const upstream = ATTACHED_MCP_SERVERS.find((s) =>
+      name.startsWith(`${s.name}${PREFIX_SEPARATOR}`),
+    );
+    if (!upstream) {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+    const client = await createUpstreamClient(upstream.url);
+    try {
+      return await client.callTool({
+        ...request.params,
+        name: name.slice(upstream.name.length + PREFIX_SEPARATOR.length),
+      });
+    } finally {
+      await client.close();
+    }
+  });
+
+  return server;
+};
+
+const app = express();
+app.use(express.json());
+
+app.post('/mcp', async (req, res) => {
+  const sessionId = req.headers[SESSION_HEADER];
+  await sessionContext.run(
+    typeof sessionId === 'string' ? sessionId : undefined,
+    async () => {
+      try {
+        const server = await createServer();
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: undefined,
+        });
+        res.on('close', () => {
+          transport.close();
+          server.close();
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+      } catch (error) {
+        console.error('Error handling MCP request:', error);
+        if (!res.headersSent) {
+          res.status(500).json({
+            jsonrpc: '2.0',
+            error: { code: -32603, message: 'Internal server error' },
+            id: null,
+          });
+        }
+      }
+    },
+  );
+});
+
+app.listen(PORT, () => {
+  console.log(`<%- nameKebabCase %>: local gateway listening on port ${PORT}`);
+});

package/src/agentcore-gateway/gateway-connection/generator.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { GeneratorCallback, Tree } from '@nx/devkit';
+import { type NxGeneratorInfo } from '../../utils/nx';
+import type { AgentcoreGatewayGatewayConnectionGeneratorSchema } from './schema';
+export declare const AGENTCORE_GATEWAY_GATEWAY_CONNECTION_GENERATOR_INFO: NxGeneratorInfo;
+/**
+ * Connect an AgentCore Gateway to another AgentCore Gateway.
+ *
+ * Chains the source gateway's dev target to the target gateway's
+ * dev target, and registers the target gateway in the source
+ * gateway's local local-dev.ts so the local gateway aggregates its tools
+ * (already prefixed by the target gateway) under
+ * `<targetGateway>___<targetName>___<toolName>`. Users must still call
+ * `gateway.addGateway(...)` in their application stack to create the
+ * actual CDK/Terraform resource.
+ */
+export declare const agentcoreGatewayGatewayConnectionGenerator: (tree: Tree, options: AgentcoreGatewayGatewayConnectionGeneratorSchema) => Promise<GeneratorCallback>;
+export default agentcoreGatewayGatewayConnectionGenerator;