@aws/nx-plugin-mcp 1.0.0-rc.96 → 1.0.0-rc.98

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

package/docs/guides/connection/react-agui.mdx

@@ -46,16 +46,17 @@ The generator creates a **single shared** `AguiProvider` component, one hook per
 - src
   - components
     - AguiProvider.tsx Single `CopilotKitProvider` for every AG-UI agent. Created on the first `connection` run and updated on subsequent runs to register each new agent.
+    - \<agent-name>-chat.tsx A themed `<AgentName>Chat` bound to this agent's id. One file per `connection` run.
     - copilot
       - index.tsx Re-exports `CopilotChat`, `CopilotSidebar` and `CopilotPopup` with slot defaults that match your website's `ux` (Cloudscape, Shadcn, or no theme at all).
       - *ThemeComponents*.tsx Per-slot theme components (e.g. `CloudscapeAssistantMessage.tsx`, `ShadcnChatInput.tsx`). Only vended when `ux` is `cloudscape` or `shadcn`.
   - hooks
-    - useAgui\<AgentName>.tsx Registers one AG-UI agent. One file per `connection` run.
+    - useAgui\<AgentName>.tsx Registers one AG-UI agent and exports its id as `<AGENT_NAME>_ID`. One file per `connection` run.
     - useSigV4.tsx SigV4 signing (IAM only)
 
 </FileTree>
 
-Running `connection` a second time for a different agent **adds a new `useAgui<AgentName>.tsx` hook** and updates `AguiProvider.tsx` to register both hooks — any custom edits you've made to the provider are preserved. `main.tsx` keeps its single `<AguiProvider>` wrapper — you never end up with nested providers.
+Running `connection` a second time for a different agent **adds a new `useAgui<AgentName>.tsx` hook and `<agent-name>-chat.tsx` component** and updates `AguiProvider.tsx` to register both hooks — any custom edits you've made to the provider are preserved. `main.tsx` keeps its single `<AguiProvider>` wrapper — you never end up with nested providers.
 
 The following dependencies are added to the root `package.json`:
 
@@ -119,17 +120,14 @@ Both Session ID and Thread ID are provided by the browser. To restrict each user
 
 ### Adding a Chat Interface
 
-Instantiate CopilotKit components with `agentId` to select which agent to use. The id is the agent's name — the same one you chose when you ran the <Link path="guides/ts-agent">`ts#agent`</Link> or <Link path="guides/py-agent">`py#agent`</Link> generator — and you can also find it in the generated hook file (e.g. the key returned from `packages/web/src/hooks/useAgui<AgentName>.tsx`).
-
-Import the chat components from the generated `./components/copilot` module so the theme that matches your website's `ux` is applied automatically:
+The generator vends a `<AgentName>Chat` component per connected agent, already bound to that agent's id and themed to match your website's `ux`. Drop it anywhere inside the `<AguiProvider>` wrapper:
 
 ```tsx
-import { CopilotChat } from './components/copilot';
+import { StoryAgentChat } from './components/story-agent-chat';
 
 function ChatPage() {
   return (
-    <CopilotChat
-      agentId="agent"
+    <StoryAgentChat
       labels={{
         welcomeMessageText: 'How can I help you today?',
         chatInputPlaceholder: 'Ask me anything...',
@@ -139,15 +137,24 @@ function ChatPage() {
 }
 ```
 
+It forwards every `CopilotChat` prop except `agentId`, so anything you can pass to `<CopilotChat />` works here too.
+
 ### Connecting Multiple AG-UI Agents
 
-Run the `connection` generator once per agent. Every agent registered via the shared `AguiProvider` is visible from anywhere in the app — instantiate a CopilotKit component with a different `agentId` to route each chat to the agent you want:
+Run the `connection` generator once per agent. Each run vends that agent's own chat component, so routing a chat to a particular agent is a matter of which component you render:
 
 ```tsx
-import { CopilotChat } from './components/copilot';
+import { StoryAgentChat } from './components/story-agent-chat';
+import { ResearchAgentChat } from './components/research-agent-chat';
 
-<CopilotChat agentId="story" />    {/* talks to StoryAgent */}
-<CopilotChat agentId="research" /> {/* talks to ResearchAgent */}
+<StoryAgentChat />    {/* talks to StoryAgent */}
+<ResearchAgentChat /> {/* talks to ResearchAgent */}
+```
+
+If you need the raw id — to call CopilotKit's own hooks, say — each generated hook exports it:
+
+```tsx
+import { STORY_AGENT_ID } from './hooks/useAguiStoryAgent';
 ```
 
 ## Customising the Look and Feel
@@ -164,12 +171,13 @@ The generator reads `metadata.ux` from your React website project and vends a th
 | `shadcn` | Assistant messages render in a `bg-muted` bubble with a `Sparkles` avatar; user messages render right-aligned in a `bg-primary` bubble with a `User` avatar. The input is a rounded `Textarea` + pill-shaped send/stop `Button` (Enter submits, Shift+Enter newlines). Uses shadcn primitives from the shared `common-shadcn` package. |
 | `none` (or anything else) | No theme — the module just re-exports the default CopilotKit components. |
 
-Import the themed components from the **local theme module** (not `@copilotkit/react-core/v2` directly) so the theme is applied automatically:
+The vended `<AgentName>Chat` components are already themed. For a chat you wire up yourself, import from the **local theme module** (not `@copilotkit/react-core/v2` directly) so the theme is applied automatically:
 
 ```tsx
 import { CopilotChat } from './components/copilot';
+import { STORY_AGENT_ID } from './hooks/useAguiStoryAgent';
 
-<CopilotChat agentId="agent" />
+<CopilotChat agentId={STORY_AGENT_ID} />
 ```
 
 The theme is applied as slot defaults, so any slot you explicitly pass still wins — you keep full control whenever you need a one-off override.
@@ -188,8 +196,7 @@ For example, to drop in your own user-message renderer while keeping the rest of
 Per-chat overrides still work alongside the theme — anything you pass as a slot prop overrides the themed default:
 
 ```tsx
-<CopilotChat
-  agentId="agent"
+<StoryAgentChat
   // style the input and its children
   input={{
     textArea: 'text-blue-600',
@@ -205,28 +212,26 @@ Per-chat overrides still work alongside the theme — anything you pass as a slo
 
 ### Replacing a slot with a custom component
 
-Any slot can take a React component instead of a className, so you can replace the default entirely:
+Any slot can take a React component instead of a className, so you can replace the default entirely. Type your component against the props the slot declares — `sendButton` renders a `<button>`, so it receives `ButtonHTMLAttributes`:
 
 ```tsx
-import { CopilotChat } from './components/copilot';
+import { StoryAgentChat } from './components/story-agent-chat';
 
-const MySendButton: React.FC<{ onClick: () => void }> = ({ onClick }) => (
+const MySendButton: React.FC<React.ButtonHTMLAttributes<HTMLButtonElement>> = ({
+  onClick,
+}) => (
   <button onClick={onClick} className="my-send-btn">
     Send
   </button>
 );
 
-<CopilotChat
-  agentId="agent"
-  input={{ sendButton: MySendButton }}
-/>;
+<StoryAgentChat input={{ sendButton: MySendButton }} />;
 ```
 
 Deeper overrides follow the same shape — e.g. replace just the copy button on assistant messages:
 
 ```tsx
-<CopilotChat
-  agentId="agent"
+<StoryAgentChat
   messageView={{
     assistantMessage: {
       copyButton: ({ onClick }) => <button onClick={onClick}>Copy</button>,
@@ -249,6 +254,10 @@ The connection generator automatically configures `dev` integration:
 The website and connected agent hot-reload together, enabling you to quickly iterate on both sides without deploying to AWS.
 :::
 
+:::note[The dev target requires the Nx Daemon]
+The `dev` target hot-reloads local dev servers. Many of these rely on [`nx watch`](https://nx.dev/docs/guides/tasks--caching/workspace-watching) to achieve this, which requires the [Nx Daemon](https://nx.dev/docs/concepts/nx-daemon) to be enabled.
+:::
+
 ## More Information
 
 - <Link path="guides/ts-agent">TypeScript Agent Guide</Link>