@aws/nx-plugin-mcp 1.0.0-rc.95 → 1.0.0-rc.97

package/bin/aws-nx-mcp.js

@@ -21917,6 +21917,8 @@ const NX_VERSION = {
 	"@aws/aws-distro-opentelemetry-node-autoinstrumentation": "0.12.0",
 	"@opentelemetry/propagator-jaeger": "2.10.0",
 	minimatch: "10.2.6",
+	"deepmerge-ts": "8.0.0",
+	mysql2: "3.22.0",
 	"@aws-sdk/client-dynamodb": "3.1121.0",
 	"@aws-sdk/client-api-gateway": "3.1121.0",
 	"@aws-sdk/client-iam": "3.1121.0",
@@ -21924,6 +21926,7 @@ const NX_VERSION = {
 	"@aws-sdk/client-bedrock-runtime": "3.1121.0",
 	"@aws-sdk/client-s3": "3.1121.0",
 	"@aws-sdk/client-sts": "3.1121.0",
+	"@aws-sdk/client-cognito-identity-provider": "3.1121.0",
 	"@aws-sdk/credential-providers": "3.1121.0",
 	"@aws-sdk/credential-provider-cognito-identity": "3.972.69",
 	"@aws-sdk/client-secrets-manager": "3.1121.0",
@@ -21939,14 +21942,14 @@ const NX_VERSION = {
 	"@middy/core": "7.9.2",
 	"@nxlv/python": "23.0.0",
 	"@nx-extend/terraform": "10.4.1",
-	nx: "23.1.2",
-	"@nx/devkit": "23.1.2",
-	"@nx/js": "23.1.2",
-	"@nx/react": "23.1.2",
-	"@nx/vite": "23.1.2",
-	"@nx/vitest": "23.1.2",
-	"@nx/workspace": "23.1.2",
-	"create-nx-workspace": "23.1.2",
+	nx: "23.2.0",
+	"@nx/devkit": "23.2.0",
+	"@nx/js": "23.2.0",
+	"@nx/react": "23.2.0",
+	"@nx/vite": "23.2.0",
+	"@nx/vitest": "23.2.0",
+	"@nx/workspace": "23.2.0",
+	"create-nx-workspace": "23.2.0",
 	"@swc-node/register": "1.12.1",
 	"@swc/core": "1.16.1",
 	"@modelcontextprotocol/sdk": "1.30.0",
@@ -22042,6 +22045,7 @@ const NX_VERSION = {
 	vite: "8.2.2",
 	typescript: "6.0.3",
 	vitest: "4.1.11",
+	jsdom: "27.4.0",
 	zod: "4.5.4",
 	ws: "8.21.3"
 }.nx;
@@ -55045,6 +55049,41 @@ const addToExistingProjectTool = (server, generators) => {
 	});
 };
 //#endregion
+//#region ../nx-plugin/src/mcp-server/tools/best-practices.ts
+/**
+* Guide pages documenting behaviour that spans generators, so no single
+* generator owns them and `generator-guide` never returns them. Each is
+* described for the agent so it can pick the ones relevant to its task.
+*/
+const BEST_PRACTICE_PAGES = {
+	workspace: "Workspace layout, configuration and common commands",
+	"typescript-project": "Conventions for TypeScript projects",
+	"python-project": "Conventions for Python projects",
+	security: "Security controls vended infrastructure carries, and the shared responsibility model",
+	"runtime-config": "How generated projects discover one another through AWS AppConfig",
+	"docker-bundling": "Building and deploying container images",
+	"local-development": "Running projects locally with the serve and dev targets"
+};
+const BEST_PRACTICE_PAGE_NAMES = Object.keys(BEST_PRACTICE_PAGES);
+/**
+* Add a tool which serves the cross-cutting guide pages. Kept separate from
+* `general-guidance` so an agent fetches only the pages its task needs rather
+* than every page on every call.
+*/
+const addBestPracticesTool = (server, generators) => {
+	server.registerTool("best-practices", {
+		title: "Best Practices",
+		description: "Tool to retrieve guidance which spans generators, rather than applying to one in particular. Request the pages relevant to your task:\n" + Object.entries(BEST_PRACTICE_PAGES).map(([page, description]) => `- \`${page}\`: ${description}`).join("\n"),
+		inputSchema: {
+			packageManager: PackageManagerSchema.optional(),
+			pages: array(_enum(BEST_PRACTICE_PAGE_NAMES)).min(1).describe("The guide pages to retrieve.")
+		}
+	}, async ({ packageManager, pages }) => ({ content: [{
+		type: "text",
+		text: await fetchGuidePages(pages, generators, packageManager)
+	}] }));
+};
+//#endregion
 //#region ../nx-plugin/src/utils/iac-providers.ts
 /**
 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
@@ -55088,9 +55127,20 @@ Refer to the \`general-guidance\` tool for full workspace documentation includin
 };
 //#endregion
 //#region ../nx-plugin/src/mcp-server/tools/general-guidance.ts
+/**
+* The cross-cutting pages every agent needs regardless of task, inlined here
+* so a workspace's conventions land without a second tool call. The rest are
+* served on demand by `best-practices`.
+*/
+const GENERAL_GUIDANCE_PAGES = [
+	"workspace",
+	"typescript-project",
+	"python-project"
+];
 const TOOL_SELECTION_GUIDE = `## Tool Selection Guide
 
 - Use the \`general-guidance\` tool for guidance and best practices for working with Nx and the Nx Plugin for AWS.
+- Use the \`best-practices\` tool for guidance which spans generators rather than applying to one in particular, such as workspace layout, security, runtime configuration, container builds and local development.
 - Use the \`create-workspace-command\` tool to discover how to create a workspace to start a new project.
 - Use the \`add-to-existing-project\` tool when adding the plugin to an existing Nx workspace or non-Nx monorepo, or when troubleshooting configuration errors in such a workspace.
 - Use the \`upgrade-workspace\` tool when upgrading Nx or the Nx Plugin for AWS to a newer version.
@@ -55169,13 +55219,9 @@ ${PACKAGE_MANAGERS.map((pm) => `  \`\`\`bash
 
 ## Detailed Guides
 
-Please refer to the below documentation for important details regarding workspaces and working with TypeScript or Python projects.
+Please refer to the below documentation for important details regarding workspaces and working with TypeScript or Python projects. Use the \`best-practices\` tool for the remaining cross-cutting guides (${BEST_PRACTICE_PAGE_NAMES.filter((p) => !GENERAL_GUIDANCE_PAGES.includes(p)).map((p) => `\`${p}\``).join(", ")}).
 
-${await fetchGuidePages([
-			"workspace",
-			"typescript-project",
-			"python-project"
-		], generators)}
+${await fetchGuidePages([...GENERAL_GUIDANCE_PAGES], generators)}
 
     `
 	}] }));
@@ -55864,6 +55910,7 @@ on AWS, if the generators apply to your use case.
 ${TOOL_SELECTION_GUIDE}
 ` });
 	addGeneralGuidanceTool(server, generators);
+	addBestPracticesTool(server, generators);
 	addCreateWorkspaceCommandTool(server);
 	addListGeneratorsTool(server, generators);
 	addGeneratorGuideTool(server, generators);

package/docs/get_started/existing-project.mdx

@@ -124,12 +124,15 @@ It creates or updates the following files:
 - tsconfig.json a root TypeScript config referencing your workspace's projects, which Nx's TypeScript sync keeps up to date
 - tsconfig.base.json the shared compiler options the plugin's TypeScript projects extend (see below for what it carries)
 - pnpm-workspace.yaml (pnpm only) allow-lists the build scripts the plugin's dependencies need (`@swc/core`, `esbuild`, `nx`, `sharp`)
-- package.json convenience scripts for common tasks, plus the `@aws/nx-plugin`, `@aws/nx-plugin-mcp`, `nx`, `@nx/js`, `@nx/workspace`, `typescript` and Biome dev dependencies
+- package.json convenience scripts for common tasks, a `prepare` script that installs the git hooks, plus the `@aws/nx-plugin`, `@aws/nx-plugin-mcp`, `nx`, `@nx/js`, `@nx/workspace`, `typescript`, husky and Biome dev dependencies
 - biome.json default Biome formatter and linter configuration
+- .git-secrets/ the vendored [git-secrets](https://github.com/awslabs/git-secrets) script, with `.gitallowed` for false positives and a `.husky/pre-commit` hook that runs it — see <Link path="guides/workspace#git-secrets">Git Secrets</Link>
 - .mcp.json configures the MCP server for supported coding agents unless disabled (also .cursor/, .kiro/, .gemini/, .vscode/ and .codex/ equivalents). It runs the workspace's own `@aws/nx-plugin-mcp`, so the server always matches the version installed in your workspace
 </FileTree>
 
-The <Link path="get_started/building-with-ai">MCP server</Link> configuration can be disabled with `--mcp=false`.
+The <Link path="get_started/building-with-ai">MCP server</Link> configuration can be disabled with `--mcp=false`, and the credential scanning hooks with `--gitSecrets=false`.
+
+Files you already have are preserved: an existing `.husky/pre-commit` hook or `prepare` script is left as it is, and the generator prints what to add so credential scanning runs alongside your own checks. An existing `.gitallowed` keeps every pattern it has.
 
 <Drawer title="tsconfig.base.json" trigger="Click here to see the compiler options a created tsconfig.base.json carries.">
 The plugin's TypeScript projects rely on these compiler options. If a `tsconfig.base.json` already exists it is left as-is, so if you keep your own these are the options to align with:
@@ -159,7 +162,7 @@ pnpm skips install scripts for packages that aren't allow-listed. `init` allow-l
 
 #### `nx sync` hangs, or `plugin worker ... exited before the connection was established`
 
-If two different `nx` versions are present in the same node_modules tree (run `npm ls nx` to confirm), their plugin-worker IPC deadlocks. The `init` generator pins the root `nx` devDependency to the version the plugin's own `@nx/*` packages resolve, but a later install of another `@nx/*` package at a different patch version can reintroduce the mismatch. Align every `nx` and `@nx/*` entry in your root `package.json` to a single version and reinstall.
+If two different `nx` versions are present in the same node_modules tree (run `npm ls nx` to confirm), their plugin-worker IPC deadlocks. `init` declares the `nx` and `@nx/*` versions the plugin is built against, but it never downgrades a version your workspace already has: a workspace already on a newer `nx` keeps it, and the plugin's own `@nx/*` packages pull in their own copy alongside it. Align every `nx` and `@nx/*` entry in your root `package.json` — and, where your package manager uses one, the dependency catalog — to a single version, then reinstall.
 
 #### `ts.readConfigFile is not a function`
 

package/docs/get_started/quick-start.mdx

@@ -224,6 +224,14 @@ If you encounter any lint errors, you can run the following command to automatic
 <PackageManagerShortCommand commands={["lint"]} />
 :::
 
+:::tip[The workspace is out of sync]
+If the build reports `The workspace is out of sync`, accept the prompt to sync the workspace or run the following sync command directly before retrying the build:
+
+<NxCommands commands={["sync"]} />
+
+This writes the TypeScript project references and `package.json` dependency entries your imports require.
+:::
+
 Bootstrap your infrastructure:
 
 <Infrastructure>

package/docs/get_started/tutorials/dungeon-game/1.mdx

@@ -130,8 +130,9 @@ Below is a list of all files which have been generated by the `ts#api` generator
       - local-server.ts used when running the tRPC server locally
       - **router.ts** defines the tRPC router and all procedures
     - project.json
+    - vitest.config.mts test configuration
     - ...
-- vitest.workspace.ts
+- vitest.config.mts root test configuration which discovers every project's tests
 </FileTree>
 
 Let us look at these key files:
@@ -151,13 +152,10 @@ export type AppRouter = typeof appRouter;
 ```
 The router defines the tRPC router for your API and is the place where you will declare all of your API methods. As you can see above, we have a method called `echo` with it's implementation in the `./procedures/echo.ts` file. The Lambda handler entrypoint is in `handler.ts`, which is configured automatically by the generator.
 
-```ts {7-10}
+```ts {4-6}
 // packages/game-api/src/procedures/echo.ts
 import { publicProcedure } from '../init.js';
-import {
-  EchoInputSchema,
-  EchoOutputSchema,
-} from '../schema/echo.js';
+import { EchoInputSchema, EchoOutputSchema } from '../schema/index.js';
 
 export const echo = publicProcedure
   .input(EchoInputSchema)
@@ -903,9 +901,7 @@ export class StoryAgent extends Construct implements IGrantable, IConnectable {
 }
 ```
 
-This configures a CDK `AgentRuntimeArtifact` which uploads your agent Docker image to ECR, and hosts it using AgentCore Runtime. Because we chose `--auth=cognito`, the construct requires the user pool/client identity and authorizes AgentCore Runtime invocations through Cognito, forwarding the caller's `Authorization` header. It also provisions the session bucket the Story Agent's `session.py` reads back at runtime — a KMS-encrypted S3 bucket with server access logs delivered to CloudWatch Logs — grants the agent read/write access to it, grants it access to invoke Bedrock models, and registers its ARN and bucket name in `RuntimeConfig` so both the agent (at runtime, via AppConfig) and the Game API (at synth time, via `invocationUrl`) can find it.
-
-You may notice an extra `Dockerfile`, that references the Docker image from the `story` project, allowing us to co-locate the Dockerfile and agent source code.
+This configures a CDK `AgentRuntimeArtifact` which packages your agent's built code as a zip asset and hosts it using AgentCore Runtime. Because we chose `--auth=cognito`, the construct requires the user pool/client identity and authorizes AgentCore Runtime invocations through Cognito, forwarding the caller's `Authorization` header. It also provisions the session bucket the Story Agent's `session.py` reads back at runtime — a KMS-encrypted S3 bucket with server access logs delivered to CloudWatch Logs — grants the agent read/write access to it, grants it access to invoke Bedrock models, and registers its ARN and bucket name in `RuntimeConfig` so both the agent (at runtime, via AppConfig) and the Game API (at synth time, via `invocationUrl`) can find it.
 
 </details>
 
@@ -965,7 +961,6 @@ The `ts#mcp-server` generator generates these files.
         - sample-guidance.ts example resource
       - stdio.ts entry point for MCP with STDIO transport
       - http.ts entry point for MCP with Streamable HTTP transport
-      - Dockerfile builds the image for AgentCore Runtime
     - rolldown.config.ts configuration for bundling the MCP server for deployment to AgentCore
   - common/constructs/
     - src
@@ -1277,9 +1272,12 @@ The `connection` generator generates/updates these files. Let us examine some of
 ```tsx
 // packages/game-ui/src/hooks/useGameApi.tsx
 import { useContext } from 'react';
-import { GameApiTRPCContext } from '../components/GameApiClientProvider';
+import {
+  GameApiTRPCContext,
+  type GameApiTRPCContextValue,
+} from '../components/GameApiClientProvider';
 
-export const useGameApi = () => {
+export const useGameApi = (): GameApiTRPCContextValue['optionsProxy'] => {
   const container = useContext(GameApiTRPCContext);
   if (!container) {
     throw new Error('useGameApi must be used within GameApiClientProvider');
@@ -1287,7 +1285,7 @@ export const useGameApi = () => {
   return container.optionsProxy;
 };
 
-export const useGameApiClient = () => {
+export const useGameApiClient = (): GameApiTRPCContextValue['client'] => {
   const container = useContext(GameApiTRPCContext);
   if (!container) {
     throw new Error(
@@ -1559,7 +1557,7 @@ Then, run the following command for a full build:
 
 <PackageManagerShortCommand commands={["build"]} />
 
-You will be prompted with the following:
+You may be prompted with the following:
 
 ```bash
  NX   The workspace is out of sync

package/docs/get_started/tutorials/dungeon-game/2.mdx

@@ -170,11 +170,19 @@ The `DungeonDb` construct registers the deployed table name in <Link path="guide
 
 There's no need to deploy to AWS to try out our API — the `dev` target runs the Game API against [DynamoDB Local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html). Because we connected the Game API to the `DungeonDb` project in Module 1, this target also starts DynamoDB Local automatically.
 
-First, fix any lint issues:
+The procedures and MCP server we just wrote import `@dungeon-adventure/dungeon-db`, a new cross-project import, so start by syncing the workspace:
+
+<NxCommands commands={["sync"]} />
+
+<Aside type="tip" title="Why this step is needed">
+`nx sync` declares `@dungeon-adventure/dungeon-db` in the `game-api` and `inventory` `package.json` files and adds the matching TypeScript project references for you, saving you from needing to add this by hand when declaring dependencies between projects.
+</Aside>
+
+Then fix any lint issues:
 
 <PackageManagerShortCommand commands={["lint"]} />
 
-Then build the codebase:
+And build the codebase:
 
 <PackageManagerShortCommand commands={["build"]} />
 

package/docs/get_started/tutorials/dungeon-game/3.mdx

@@ -47,6 +47,10 @@ If you encounter any lint errors, run the following command to automatically fix
 <PackageManagerShortCommand commands={["lint"]} />
 </Aside>
 
+<Aside type="tip" title="The workspace is out of sync">
+If the build reports `The workspace is out of sync`, run `nx sync` and build again.
+</Aside>
+
 ### Chat with your Agent
 
 The generated `agent-chat` target opens an interactive REPL against your agent. It runs standalone and connects to your locally-running agent, so first start the agent's local server in one terminal:

package/docs/get_started/tutorials/dungeon-game/4.mdx

@@ -27,7 +27,7 @@ Start the full local stack — the game-ui dev server together with a local Game
 
 <NxCommands commands={["dev game-ui"]} />
 
-The `dev` target on `game-ui` has `dependsOn` on `game-api:dev` and `dungeon_adventure.story:agent-dev`, so Nx spins up every project's local server in parallel. Through the connections we set up in Module 1, those in turn boot the Inventory MCP server and DynamoDB Local. Make sure your container engine is running, then open the dev server in a browser.
+The `dev` target on `game-ui` has `dependsOn` on `game-api:dev` and `dungeon_adventure.story:agent-dev`, so Nx spins up every project's local server in parallel. Through the connections we set up in Module 1, those in turn boot the Inventory MCP server and DynamoDB Local. Make sure your container engine is running, then open the dev server at `http://localhost:4200/` in a browser.
 
 <Aside type="tip" title="No login locally">
 In `local-dev` mode the `CognitoAuth` component skips the Cognito login flow (there's no user pool running locally), so you'll land straight on the game without signing in. You'll create a real account when we deploy to AWS at the end of this module.
@@ -90,7 +90,7 @@ The `$playerName` syntax tells `@tanstack/react-router` to treat `playerName` as
 </TabItem>
 </Tabs>
 
-Once saved, the dev server at `http://localhost:4200/` should now let you start an adventure and chat with the Story Agent.
+Once saved, the dev server should now let you start an adventure and chat with the Story Agent.
 
 <Image src={gameSelectPng} alt="game-select.png" width="600" height="309" />
 <div style="margin-top: -100px; margin-left: 100px;">

package/docs/guides/agentcore-gateway.mdx

@@ -42,7 +42,9 @@ The generator creates a new project at `packages/<name>/`, plus a CDK construct
       - permit-all.cedar Default Cedar policy that permits authenticated callers
       - README.md Reference for writing Cedar policies
     - local-dev.ts Local gateway for local development — aggregates attached MCP servers (`mcp`) or proxies attached agents (`http`)
-    - project.json Adds the `serve` and `dev` targets
+    - package.json Declares the dependencies `local-dev.ts` imports
+    - tsconfig.json TypeScript configuration used by the `typecheck` target
+    - project.json Adds the `serve`, `dev`, `build`, `lint`, `format` and `typecheck` targets
 </FileTree>
 
 ### Infrastructure
@@ -133,7 +135,7 @@ The generated infrastructure consumes an existing Cognito user pool and client
 The generated construct requires an `identity` prop supplying the user pool and client:
 
 ```ts {7,9-11} title="packages/infra/src/stacks/application-stack.ts"
-import { MyGateway, UserIdentity } from ':my-scope/common-constructs';
+import { MyGateway, UserIdentity } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {

package/docs/guides/agentcore-harness.mdx

@@ -32,7 +32,8 @@ The generator creates a standalone project at `packages/<name>/`. Because AWS ru
   - packages/\<name>/
     - src/PROMPT.md The Harness system prompt
     - scripts/chat.ts Multi-turn chat client for the deployed Harness
-    - project.json Adds the `chat` target
+    - tsconfig.json TypeScript configuration used by the `typecheck` target
+    - project.json Adds the `chat`, `build`, `lint`, `format` and `typecheck` targets
     - README.md Chat and customization instructions
 </FileTree>
 

package/docs/guides/astro-docs.mdx

@@ -43,7 +43,9 @@ workspace root (configurable via the `name`, `directory` and `subDirectory` opti
   - scripts
     - translate.ts Translation driver — a Strands agent with a scoped file-editor tool (omitted with `--noTranslation`)
     - translate.config.json Source/target locales, glob patterns, model id, region (omitted with `--noTranslation`)
+  - .gitignore Ignores Astro's build output and generated types
   - src
+    - content.config.ts Starlight's docs content collection definition
     - components
       - link.astro Locale-aware link component (resolves paths against the current locale)
       - snippet.astro Locale-aware snippet loader component
@@ -74,14 +76,29 @@ it. To add more languages:
 ## Translation
 
 Unless you passed `--noTranslation`, the generator adds a `translate` target to
-`project.json`, so you can run:
+`project.json`. Which locales it translates to comes from `targetLanguages` in
+`scripts/translate.config.json`, which ships empty — so start by naming the
+locales you want on the command line:
 
 <NxCommands commands={[
-  'translate docs -- --all',
   'translate docs -- --languages jp,ko',
+  'translate docs -- --languages jp,ko --dry-run',
+]} />
+
+Once you have populated `targetLanguages` (see [Configuring
+translation](#configuring-translation)), `--languages` becomes optional and the
+configured locales are used:
+
+<NxCommands commands={[
+  'translate docs -- --all',
   'translate docs -- --dry-run',
 ]} />
 
+:::caution[Configure your target languages first]
+Without `--languages` and with `targetLanguages` still empty, the target exits
+non-zero with `ERROR No target languages configured`.
+:::
+
 When run without `--all`, the script only translates files that have changed
 since the last translation commit on the current branch — meaning you can
 safely re-run it on every docs PR without re-translating the whole site.
@@ -145,8 +162,9 @@ No CI workflow is generated out of the box — add one that:
 
    <NxCommands commands={['translate docs']} />
 
-3. Commits the resulting translations back to the PR branch. The commit message
-   must match the `translationCommitMessage` value in
-   `scripts/translate.config.json` (default `docs: update translations`) so that
-   subsequent incremental runs can detect the baseline commit and only
-   re-translate the files that changed since.
+3. Commits the resulting translations back to the PR branch, using
+   `docs: update translations` as the commit message, so that subsequent
+   incremental runs can detect the baseline commit and only re-translate the
+   files that changed since. To use a different message, add a
+   `translationCommitMessage` key to `scripts/translate.config.json` and match
+   that value instead.

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

@@ -48,11 +48,13 @@ The generator creates a shared `agent_connection` Python project at `packages/co
   - \<scope>\_agent\_connection
     - \_\_init\_\_.py Re-exports per-connection clients
     - core
+      - \_\_init\_\_.py Python package initialization
       - agentcore\_endpoints.py Framework-agnostic ARN/URL resolution
       - agentcore\_a2a\_client\_config.py Framework-agnostic A2A client config (signed `ClientConfig`)
       - agentcore\_a2a\_client\_\<framework>.py A2A client wrapping the config for your agent's framework
       - auth/ Framework-agnostic SigV4 / session-forwarding `httpx.Auth`
     - app
+      - \_\_init\_\_.py Python package initialization
       - \<target\_agent\_name>\_client\_\<framework>.py Per-connection A2A client for each A2A agent
 
 </FileTree>

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

@@ -41,7 +41,7 @@ The generator updates the agent's `<agent-name>-dev` target in `project.json` to
 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 my_scope_my_table.entities.example import ExampleModel
 from strands import tool
 
 @tool

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

@@ -50,11 +50,14 @@ The generator emits shared core-gateway modules into your `agent_connection` Pyt
 - packages/common/agent\_connection
   - \<scope>\_agent\_connection
     - core/
+      - \_\_init\_\_.py Python package initialization
       - agentcore\_endpoints.py Framework-agnostic ARN/URL resolution
+      - agentcore\_transport.py Shared AgentCore transport plumbing
       - agentcore\_gateway\_mcp\_transport.py Framework-agnostic Gateway MCP transport
       - agentcore\_gateway\_mcp\_client\_\<framework>.py Gateway MCP client for your agent's framework
       - auth/ Framework-agnostic SigV4 / session-forwarding `httpx.Auth`
     - app/
+      - \_\_init\_\_.py Python package initialization
       - \<gateway\_snake>\_client\_\<framework>.py Per-Gateway client wrapper
     - \_\_init\_\_.py Re-exports the Gateway client
 

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

@@ -13,6 +13,7 @@ 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 can connect your <Link path="guides/py-agent">Python Agent</Link> to an MCP server (either <Link path="guides/ts-mcp-server">TypeScript</Link> or <Link path="guides/py-mcp-server">Python</Link>).
 
@@ -48,11 +49,14 @@ The generator creates a shared `agent_connection` Python project at `packages/co
   - \<scope>\_agent\_connection
     - \_\_init\_\_.py Re-exports per-connection clients
     - core
+      - \_\_init\_\_.py Python package initialization
       - agentcore\_endpoints.py Framework-agnostic ARN/URL resolution
+      - agentcore\_transport.py Shared AgentCore transport plumbing
       - agentcore\_mcp\_transport.py Framework-agnostic MCP transport
       - agentcore\_mcp\_client\_\<framework>.py MCP client wrapping the transport for your agent's framework
       - auth/ Framework-agnostic SigV4 / session-forwarding `httpx.Auth`
     - app
+      - \_\_init\_\_.py Python package initialization
       - \<mcp\_server\_name>\_client\_\<framework>.py Per-connection client for each MCP server
 
 </FileTree>
@@ -114,6 +118,8 @@ The AgentCore session ID is propagated to the MCP server automatically via the `
 
 ## Infrastructure
 
+<Snippet name="connection/infra-project-prerequisite" />
+
 <Infrastructure>
 <Fragment slot="cdk">
 After running the connection generator, you need to grant the agent permission to invoke the MCP server:
@@ -126,12 +132,14 @@ const myAgent = new MyAgent(this, 'MyAgent');
 mcpServer.grantInvokeAccess(myAgent);
 ```
 
+`grantInvokeAccess` wires up the AgentCore invoke actions (`InvokeAgentRuntime`, `InvokeAgentRuntimeForUser` and `InvokeAgentRuntimeWithWebSocketStream`) on the MCP server's runtime ARN.
+
 The MCP server'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 agent can discover it at runtime.
 </Fragment>
 <Fragment slot="terraform">
 After running the connection generator, you need to grant the agent permission to invoke the MCP server in your Terraform configuration:
 
-```hcl title="packages/infra/src/main.tf" {9-25}
+```hcl title="packages/infra/src/main.tf" {9-31}
 module "inventory_mcp_server" {
   source = "../../common/terraform/src/app/mcp-servers/inventory-mcp"
 }
@@ -146,9 +154,15 @@ resource "aws_iam_policy" "agent_invoke_mcp" {
   policy = jsonencode({
     Version = "2012-10-17"
     Statement = [{
-      Effect   = "Allow"
-      Action   = "bedrock-agentcore:InvokeAgent"
-      Resource = module.inventory_mcp_server.agent_core_runtime_arn
+      Effect = "Allow"
+      Action = [
+        "bedrock-agentcore:InvokeAgentRuntime",
+        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
+      ]
+      Resource = [
+        module.inventory_mcp_server.agent_core_runtime_arn,
+        "${module.inventory_mcp_server.agent_core_runtime_arn}/*",
+      ]
     }]
   })
 }

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

@@ -42,7 +42,7 @@ Select your Agent project as the source and your relational database project as
   - pyproject.toml Adds the database package as a workspace dependency
   - my\_service
     - my\_agent
-      - Dockerfile Adds the RDS CA bundle used for direct Aurora connections
+      - Dockerfile Adds the RDS CA bundle used for direct Aurora connections (only when the agent's `infra` is `agentcore-ecr`)
 
 </FileTree>
 
@@ -52,15 +52,16 @@ Import `session_context` from your database package and use it inside your agent
 
 ```python title="packages/my_service/my_service/my_agent/agent.py"
 from sqlmodel import select
-from my_scope.my_db import session_context
-from my_scope.my_db.models.example import ExampleModel
+from my_scope_my_db import session_context
+from my_scope_my_db.models.example import ExampleModel
 from strands import tool
 
 @tool
 async def list_examples() -> list:
     """List all example records."""
     async with session_context() as session:
-        return [item.model_dump() for item in (await session.execute(select(ExampleModel))).all()]
+        items = (await session.execute(select(ExampleModel))).scalars().all()
+        return [item.model_dump() for item in items]
 ```
 
 ## Infrastructure

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

@@ -40,7 +40,7 @@ The generator updates the FastAPI's `project.json` to add a dependency from its
 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
+from my_scope_my_table.entities.example import ExampleModel
 
 @app.get("/examples")
 def list_examples():

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

@@ -11,6 +11,7 @@ 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/fastapi">FastAPI</Link> to a <Link path="guides/py-rdb">Python Relational Database</Link> project, injecting a typed SQLModel session into your route handlers via a FastAPI dependency.
 
@@ -55,11 +56,11 @@ This generator configures an injectable [FastAPI Dependency](https://fastapi.tia
 ```python title="packages/my_api/my_api/api.py" {2,6,10}
 from sqlmodel import select
 from my_api.dependencies.my_db import MyDbSession
-from my_scope.my_db.models.example import ExampleModel
+from my_scope_my_db.models.example import ExampleModel
 
 @app.get("/examples")
 async def list_examples(my_db: MyDbSession):
-    return (await my_db.execute(select(ExampleModel))).all()
+    return (await my_db.execute(select(ExampleModel))).scalars().all()
 
 @app.post("/examples")
 async def create_example(name: str, my_db: MyDbSession):
@@ -168,6 +169,10 @@ The AppConfig application exposes the `database` namespace by default, so the da
 </Fragment>
 </Infrastructure>
 
+### SSL Requirements When Connecting Without RDS Proxy
+
+<Snippet name="connection/py-lambda-rdb-ssl-requirements" parentHeading="SSL Requirements When Connecting Without RDS Proxy" />
+
 ## Local Development
 
 <NxCommands commands={["dev <project-name>"]} />

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

@@ -41,7 +41,7 @@ The generator updates the MCP server's `<mcp-server-name>-dev` target in `projec
 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
+from my_scope_my_table.entities.example import ExampleModel
 
 @mcp.tool()
 def list_examples() -> str:

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

@@ -42,7 +42,7 @@ Select your MCP server project as the source and your relational database projec
   - pyproject.toml Adds the database package as a workspace dependency
   - my\_service
     - my\_mcp\_server
-      - Dockerfile Adds the RDS CA bundle used for direct Aurora connections
+      - Dockerfile Adds the RDS CA bundle used for direct Aurora connections (only when the MCP server's `infra` is `agentcore-ecr`)
 
 </FileTree>
 
@@ -52,14 +52,14 @@ Import `session_context` from your database package and use it inside your MCP s
 
 ```python title="packages/my_service/my_service/my_mcp_server/server.py"
 from sqlmodel import select
-from my_scope.my_db import session_context
-from my_scope.my_db.models.example import ExampleModel
+from my_scope_my_db import session_context
+from my_scope_my_db.models.example import ExampleModel
 
 @mcp.tool()
 async def list_examples() -> str:
     """List all example records."""
     async with session_context() as session:
-        items = (await session.execute(select(ExampleModel))).all()
+        items = (await session.execute(select(ExampleModel))).scalars().all()
         return str([item.model_dump() for item in items])
 ```
 
@@ -68,8 +68,8 @@ async def list_examples() -> str:
 Running the generator again with a different target adds the second database alongside the first. Both session contexts are available to all tools:
 
 ```python title="packages/my_service/my_service/my_mcp_server/server.py"
-from my_scope.my_db import session_context as my_db_session_context
-from my_scope.other_db import session_context as other_db_session_context
+from my_scope_my_db import session_context as my_db_session_context
+from my_scope_other_db import session_context as other_db_session_context
 ```
 
 ## Infrastructure