@aws/nx-plugin-mcp 1.0.0-rc.8 → 1.0.0-rc.80

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

@@ -0,0 +1,187 @@
+---
+title: Python MCP Server to Relational Database
+description: Connect a Python MCP Server to a Relational Database
+when:
+  sourceType: py#mcp-server
+  targetType: py#rdb
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+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';
+
+The `connection` generator wires a <Link path="guides/py-mcp-server">Python MCP Server</Link> to a <Link path="guides/py-rdb">Python Relational Database</Link> project, making the database session available to all tools registered in the server.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/py-mcp-server">`py#mcp-server`</Link> project
+2. A <Link path="guides/py-rdb">`py#rdb`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your MCP server project as the source and your relational database project as the target. If the project contains multiple MCP server components, specify `sourceComponent` to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+<FileTree>
+
+- packages/my\_service
+  - project.json Adds a dependency from `my_mcp_server-dev` on the database's `dev` target
+  - 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
+
+</FileTree>
+
+## Using the Database in MCP Tools
+
+Import `session_context` from your database package and use it inside your MCP server tools:
+
+```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
+
+@mcp.tool()
+async def list_examples() -> str:
+    """List all example records."""
+    async with session_context() as session:
+        items = (await session.execute(select(ExampleModel))).all()
+        return str([item.model_dump() for item in items])
+```
+
+## Multiple Databases
+
+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
+```
+
+## Infrastructure
+
+The generated MCP server construct implements `IGrantable` and `IConnectable`, so you can grant network and IAM access to the database directly on the construct.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { SecurityGroup } from 'aws-cdk-lib/aws-ec2';
+import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';
+import { MyDatabase } from '@my-scope/common-constructs';
+
+const db = new MyDatabase(this, 'Db', { vpc, ... });
+
+const myMcpServer = new MyMcpServer(this, 'MyMcpServer', {
+  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(this, {
+    vpc,
+    vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
+    securityGroups: [
+      new SecurityGroup(this, 'MyMcpServerSecurityGroup', { vpc, allowAllOutbound: true }),
+    ],
+  }),
+});
+
+db.allowDefaultPortFrom(myMcpServer);
+db.grantConnect(myMcpServer);
+```
+
+`allowDefaultPortFrom` opens the security group rule so the MCP server runtime can reach the database port. `grantConnect` grants IAM `rds-db:connect` permission to the server's execution role.
+
+
+</Fragment>
+<Fragment slot="terraform">
+
+Run the MCP server inside the same VPC as the database, grant it `rds-db:connect` via `additional_iam_policy_statements`, and open the network path with a pair of security group rules. The `aws_vpc.main` and `aws_subnet` resources are defined in the database deployment guide:
+
+```hcl title="packages/infra/src/main.tf"
+module "my_database" {
+  source              = "../../common/terraform/src/app/dbs/my-database"
+  vpc_id              = aws_vpc.main.id
+  database_subnet_ids = aws_subnet.database[*].id
+  lambda_subnet_ids   = aws_subnet.private[*].id
+}
+
+module "my_mcp_server" {
+  source     = "../../common/terraform/src/app/mcp-servers/my-mcp-server"
+  enable_vpc = true
+  vpc_id     = aws_vpc.main.id
+  subnet_ids = aws_subnet.private[*].id
+
+  appconfig_application_id  = module.runtime_config_appconfig.application_id
+  appconfig_application_arn = module.runtime_config_appconfig.application_arn
+
+  additional_iam_policy_statements = [
+    {
+      Effect = "Allow"
+      Action = ["rds-db:connect"]
+      Resource = [
+        "arn:aws:rds-db:${data.aws_region.current.region}:${data.aws_caller_identity.current.account_id}:dbuser:${module.my_database.connect_resource_id}/${module.my_database.database_runtime_user}"
+      ]
+    }
+  ]
+}
+
+resource "aws_vpc_security_group_ingress_rule" "mcp_server_to_database" {
+  description                  = "Allow the MCP server runtime to connect to the database"
+  security_group_id            = module.my_database.security_group_id
+  referenced_security_group_id = module.my_mcp_server.security_group_id
+  from_port                    = module.my_database.cluster_port
+  to_port                      = module.my_database.cluster_port
+  ip_protocol                  = "tcp"
+}
+
+resource "aws_vpc_security_group_egress_rule" "mcp_server_to_database" {
+  description                  = "Allow outbound traffic from the MCP server runtime to the database"
+  security_group_id            = module.my_mcp_server.security_group_id
+  referenced_security_group_id = module.my_database.security_group_id
+  from_port                    = module.my_database.cluster_port
+  to_port                      = module.my_database.cluster_port
+  ip_protocol                  = "tcp"
+}
+```
+
+`appconfig_application_id`/`appconfig_application_arn` come from the shared <Link path="guides/runtime-config">runtime configuration</Link> AppConfig application declared once in your root module, not from the database module. Include the `database` namespace when instantiating it so the database module's runtime configuration entry is deployed:
+
+```hcl title="packages/infra/src/main.tf"
+module "runtime_config_appconfig" {
+  source = "../../common/terraform/src/core/runtime-config/appconfig"
+
+  application_name = "my-app-runtime-config"
+  namespaces       = ["connection", "agentcore", "database"]
+}
+```
+
+</Fragment>
+</Infrastructure>
+
+### SSL Requirements When Connecting Without RDS Proxy
+
+When the MCP server connects directly to the Aurora cluster (without RDS Proxy), the connection generator updates the generated MCP server Dockerfile to install the Amazon RDS CA bundle into the system trust store:
+
+```dockerfile
+ADD https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem /usr/local/share/ca-certificates/rds-global-bundle.crt
+RUN update-ca-certificates
+```
+
+When using RDS Proxy, you do not need to configure the RDS CA bundle in the MCP server runtime.
+
+## Local Development
+
+<NxCommands commands={["<mcp-server-name>-dev <project-name>"]} />
+
+This starts the MCP server and all connected databases. The `LOCAL_DEV=true` environment variable causes the database client to connect to its local Docker database instead of Aurora.

package/docs/guides/connection/react-agentcore-gateway.mdx

@@ -0,0 +1,112 @@
+---
+title: React Website to AgentCore Gateway
+description: Connect a React website to agents through an AgentCore Gateway
+when:
+  sourceType: ts#react-website
+  targetType: agentcore-gateway
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+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';
+
+The `connection` generator can connect a <Link path="guides/react-website">React website</Link> to the agents fronted by an <Link path="guides/agentcore-gateway">AgentCore Gateway</Link> generated with `protocol: http`.
+
+The browser talks only to the Gateway — requests to `<gatewayUrl>/<targetName>/invocations` are proxied to the agent runtime behind it. Because the website never needs to reach the runtimes directly, the agents can be deployed inside a VPC, with the Gateway as the single governed entry point providing authentication and observability.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/react-website">React website</Link> project
+2. An <Link path="guides/agentcore-gateway">`agentcore-gateway`</Link> project generated with `protocol: http`
+3. At least one AG-UI or HTTP agent attached to the Gateway via the <Link path="guides/connection/agentcore-gateway-agent">Gateway to agent connection generator</Link>
+
+The generator creates a website client for **each** AG-UI or HTTP agent attached to the Gateway (A2A targets are skipped — they speak agent-to-agent JSON-RPC, not a browser protocol). It generates the same clients as connecting the website to each agent directly (<Link path="guides/connection/react-agui">AG-UI/CopilotKit</Link> for AG-UI agents, an <Link path="guides/connection/react-py-agent">OpenAPI client</Link> for Python HTTP agents), routed through the Gateway rather than at the runtime.
+
+:::note[Authentication]
+The browser authenticates with the **Gateway**, not the agents: SigV4 for an IAM Gateway (via the website's Cognito identity pool), or a JWT bearer token for a Cognito Gateway.
+:::
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select the website project as the source and the Gateway project as the target.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+For each fronted AG-UI agent, the same files as the <Link path="guides/connection/react-agui">React to AG-UI agent connection</Link> are generated (an `AguiProvider`, a `useAgui<Agent>` hook and a themed CopilotKit component module), with the hook reading the Gateway's URL from runtime configuration:
+
+<FileTree>
+
+- packages/\<website>/src
+  - components
+    - AguiProvider.tsx CopilotKit provider registering each agent
+    - copilot/ Themed chat components
+  - hooks
+    - useAgui\<Agent>.tsx Connects to the agent via the Gateway's `/<targetName>/invocations` route
+
+</FileTree>
+
+For each fronted Python HTTP agent, the same files as the <Link path="guides/connection/react-py-agent">React to Python agent connection</Link> are generated (a type-safe OpenAPI client, hooks, and a provider), with the client's base URL routed through the Gateway.
+
+The Gateway's URL is registered in the `connection.gateways.<GatewayClassName>` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link>, so it is published to the website's `runtime-config.json`.
+
+## Granting website users access
+
+For an **IAM** Gateway, grant the website's authenticated users permission to invoke it (a **Cognito** Gateway needs no grant — the browser authenticates with its JWT bearer token instead):
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts title="packages/infra/src/stacks/application-stack.ts" {6}
+const identity = new UserIdentity(this, 'UserIdentity');
+new Website(this, 'Website');
+
+const myGateway = new MyGateway(this, 'MyGateway');
+myGateway.addAgent(myAgent);
+myGateway.grantInvokeAccess(identity.identityPool.authenticatedRole);
+```
+</Fragment>
+<Fragment slot="terraform">
+```hcl title="packages/infra/src/main.tf"
+resource "aws_iam_policy" "gateway_invoke_policy" {
+  name = "GatewayInvokePolicy"
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Effect   = "Allow"
+        Action   = ["bedrock-agentcore:InvokeGateway"]
+        Resource = [module.my_gateway.gateway_arn]
+      }
+    ]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "authenticated_gateway_access" {
+  role       = module.user_identity.authenticated_role_name
+  policy_arn = aws_iam_policy.gateway_invoke_policy.arn
+}
+```
+</Fragment>
+</Infrastructure>
+
+## Local Development
+
+The website's `dev` target gains a dependency on the Gateway project's `dev` target, which starts the local gateway plus every attached agent. The website's runtime configuration is overridden in `local-dev` mode to point the Gateway's URL at the local gateway, so the browser exercises the same `/<targetName>/invocations` routes locally:
+
+<NxCommands commands={["dev <website-name>"]} />
+
+## Connecting new agents
+
+The generator connects the website to the agents attached to the Gateway **at the time it runs**. After attaching another agent to the Gateway, re-run the connection generator to generate its website client — existing clients are left untouched.

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

@@ -2,7 +2,7 @@
 title: React to AG-UI Agent
 description: Connect a React website to an Agent via the AG-UI protocol using CopilotKit
 when:
-  sourceType: react
+  sourceType: ts#react-website
   targetType:
     - ts#agent
     - py#agent
@@ -22,7 +22,7 @@ Nx Plugin for AWS provides a generator to connect a React website to an Agent th
 Before using this generator, ensure you have:
 
 1. A React website (generated using the <Link path="guides/react-website">`ts#website` generator</Link>)
-2. A TypeScript or Python Agent with `protocol=AG-UI` (generated using the <Link path="guides/ts-agent">`ts#agent`</Link> or <Link path="guides/py-agent">`py#agent`</Link> generator)
+2. A TypeScript or Python Agent with `protocol=ag-ui` (generated using the <Link path="guides/ts-agent">`ts#agent`</Link> or <Link path="guides/py-agent">`py#agent`</Link> generator)
 3. For deployed agents, Cognito Auth added via the <Link path="/guides/react-website-auth">`ts#website#auth` generator</Link>
 
 ## Usage
@@ -47,8 +47,8 @@ The generator creates a **single shared** `AguiProvider` component, one hook per
   - 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.
     - copilot
-      - index.tsx Re-exports `CopilotChat`, `CopilotSidebar` and `CopilotPopup` with slot defaults that match your website's `uxProvider` (Cloudscape, Shadcn, or no theme at all).
-      - *ThemeComponents*.tsx Per-slot theme components (e.g. `CloudscapeAssistantMessage.tsx`, `ShadcnChatInput.tsx`). Only vended when `uxProvider` is `Cloudscape` or `Shadcn`.
+      - 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.
     - useSigV4.tsx SigV4 signing (IAM only)
@@ -71,7 +71,7 @@ The following dependencies are added to the root `package.json`:
 Each `useAgui<AgentName>` hook reads its agent's runtime value from <Link path="guides/runtime-config">Runtime Configuration</Link> and instantiates an `@ag-ui/client` `HttpAgent`:
 
 - **Deployed**: the runtime value is a Bedrock AgentCore Runtime ARN, which is converted to the AgentCore HTTPS endpoint: `https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/invocations?qualifier=DEFAULT`
-- **Local development**: `serve-local` overrides the value to the agent's local URL (e.g. `http://localhost:8081`)
+- **Local development**: `dev` overrides the value to the agent's local URL (e.g. `http://localhost:8081`)
 
 The shared `AguiProvider` calls every generated hook and spreads each one into `selfManagedAgents` on a single `CopilotKitProvider`, which exposes them all to CopilotKit components.
 
@@ -92,6 +92,25 @@ The generated code handles authentication depending on your agent's configuratio
 - **IAM** (default): uses AWS SigV4-signed HTTP requests. Credentials are obtained from the Cognito Identity Pool configured with your website's auth.
 - **Cognito**: embeds the JWT access token in the `Authorization` header as a Bearer token.
 
+### Sessions and Threads
+
+AG-UI and AgentCore Runtime each identify a conversation differently, and the generated hook ties them together:
+
+- **`threadId`** — the AG-UI conversation identifier, sent in the request body. CopilotKit generates a random UUID per chat unless you pass an explicit `threadId`.
+- **Session ID** — the AgentCore Runtime session, sent in the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header. It selects the [microVM](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-how-it-works.html) serving the request, and is what your agent's `session.ts` / `session.py` keys conversation state on.
+
+The hook derives the session ID from the thread ID, right-padding it to the 33 characters AgentCore Runtime requires:
+
+```ts
+function agentCoreSessionId(input: RunAgentInput): string {
+  return (input.threadId ?? '').padEnd(33, '0');
+}
+```
+
+Leaving `threadId` unset is simplest — CopilotKit's generated UUID is already 36 characters. If you pass one explicitly, make it at least 33 characters, since padding maps thread IDs that differ only in trailing characters onto the same session.
+
+Both Session ID and Thread ID are provided by the browser. To restrict each user to their own conversations, refer to the <Link path="guides/py-agent">`py#agent`</Link> or <Link path="guides/ts-agent">`ts#agent`</Link> guide.
+
 ## Infrastructure
 
 <Snippet name="connection/react-agent-infrastructure" parentHeading="Infrastructure" />
@@ -102,7 +121,7 @@ The generated code handles authentication depending on your agent's configuratio
 
 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 `uxProvider` is applied automatically:
+Import the chat components from the generated `./components/copilot` module so the theme that matches your website's `ux` is applied automatically:
 
 ```tsx
 import { CopilotChat } from './components/copilot';
@@ -137,13 +156,13 @@ import { CopilotChat } from './components/copilot';
 
 ### Built-in Themes
 
-The generator reads `metadata.uxProvider` from your React website project and vends a themed wrapper module at `src/components/copilot/index.tsx` so the chat components match the rest of your UI without any extra configuration:
+The generator reads `metadata.ux` from your React website project and vends a themed wrapper module at `src/components/copilot/index.tsx` so the chat components match the rest of your UI without any extra configuration:
 
-| `uxProvider` | Styling applied to `CopilotChat` / `CopilotSidebar` / `CopilotPopup` |
+| `ux` | Styling applied to `CopilotChat` / `CopilotSidebar` / `CopilotPopup` |
 | ------------ | -------------------------------------------------------------------- |
-| `Cloudscape` | Messages render inside Cloudscape `ChatBubble`s with gen-AI `Avatar`s (matching the [Cloudscape generative AI chat pattern](https://cloudscape.design/patterns/genai/generative-AI-chat/)); the typing indicator becomes a `LoadingBar` and the input is a `PromptInput`. Built from `@cloudscape-design/components` and `@cloudscape-design/chat-components`. |
-| `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. |
+| `cloudscape` | Messages render inside Cloudscape `ChatBubble`s with gen-AI `Avatar`s (matching the [Cloudscape generative AI chat pattern](https://cloudscape.design/patterns/genai/generative-AI-chat/)); the typing indicator becomes a `LoadingBar` and the input is a `PromptInput`. Built from `@cloudscape-design/components` and `@cloudscape-design/chat-components`. |
+| `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:
 
@@ -218,13 +237,13 @@ Deeper overrides follow the same shape — e.g. replace just the copy button on
 
 ## Local Development
 
-The connection generator automatically configures `serve-local` integration:
+The connection generator automatically configures `dev` integration:
 
-1. Running `nx serve-local <website>` will also start the agent's local server
+1. Running `nx dev <website>` will also start the agent's local server
 2. The runtime config is overridden to point to the local AG-UI URL (e.g. `http://localhost:8081`)
 3. Both the website and the agent hot-reload together
 
-<NxCommands commands={['serve-local <WebsiteProject>']} />
+<NxCommands commands={['dev <WebsiteProject>']} />
 
 :::tip[Hot Reloading]
 The website and connected agent hot-reload together, enabling you to quickly iterate on both sides without deploying to AWS.

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

@@ -2,7 +2,7 @@
 title: React to FastAPI
 description: Connect a React website to a Python FastAPI
 when:
-  sourceType: react
+  sourceType: ts#react-website
   targetType: py#fast-api
 ---
 
@@ -115,9 +115,9 @@ Whenever you make changes to your FastAPI, you need to rebuild your project in o
 :::
 
 :::tip[Auto-Regeneration]
-If you're actively working on both your React application and FastAPI together, use the React application's `serve-local` target which will automatically regenerate the client whenever your API changes, as well as hot-reloading your website and local FastAPI server:
+If you're actively working on both your React application and FastAPI together, use the React application's `dev` target which will automatically regenerate the client whenever your API changes, as well as hot-reloading your website and local FastAPI server:
 
-<NxCommands commands={['serve-local <WebsiteProject>']} />
+<NxCommands commands={['dev <WebsiteProject>']} />
 
 For more fine-grained control, you can use the `watch-generate:<ApiName>-client` target for your React application to regenerate the client every time you make API changes:
 
@@ -312,6 +312,42 @@ function CreateItemForm() {
 ```
 </Drawer>
 
+### File Uploads
+
+For endpoints that accept a file upload, the generated client sends the request as `FormData`. Define an operation with a `multipart/form-data` body in your FastAPI, for example using `UploadFile`:
+
+```python
+from fastapi import UploadFile
+
+@app.post("/files")
+async def upload_file(file: UploadFile, description: str = "") -> FileMetadata:
+    contents = await file.read()
+    ...
+```
+
+Binary fields are typed as `Blob` on the generated client, and other fields (such as `description` above) keep their modelled types. Pass a `Blob` or `File` — for example one obtained from an `<input type="file">`:
+
+```tsx {9-12}
+import { useMutation } from '@tanstack/react-query';
+import { useMyApi } from './hooks/useMyApi';
+
+function UploadForm() {
+  const api = useMyApi();
+  const uploadFile = useMutation(api.uploadFile.mutationOptions());
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (file) {
+      uploadFile.mutate({ file, description: file.name });
+    }
+  };
+
+  return <input type="file" onChange={handleChange} />;
+}
+```
+
+The client builds a `FormData` body and lets `fetch` set the `Content-Type` (including the multipart boundary) automatically.
+
 ### Pagination with Infinite Queries
 
 For endpoints that accept a `cursor` parameter as input, the generated hooks provide support for infinite queries using TanStack Query's `useInfiniteQuery` hook. This makes it easy to implement "load more" or infinite scrolling functionality.

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

@@ -2,7 +2,7 @@
 title: React to Python Agent
 description: Connect a React website to a Python Agent
 when:
-  sourceType: react
+  sourceType: ts#react-website
   targetType: py#agent
   protocol: http
 ---
@@ -16,7 +16,7 @@ import Snippet from '@components/snippet.astro';
 Nx Plugin for AWS provides a generator to quickly integrate your <Link path="guides/py-agent">Python Agent</Link> with a React website. It sets up all necessary configuration for connecting to your agent via a type-safe OpenAPI-generated client, including AWS IAM and Cognito authentication support.
 
 :::tip[AG-UI agents]
-If your Python Agent was generated with `protocol=AG-UI`, the connection generator instead wires up [CopilotKit](https://docs.copilotkit.ai/aws-strands) and an [`@ag-ui/client`](https://docs.ag-ui.com/) `HttpAgent` on the React website. See the <Link path="guides/connection/react-agui">React to AG-UI Agent</Link> guide for details.
+If your Python Agent was generated with `protocol=ag-ui`, the connection generator instead wires up [CopilotKit](https://docs.copilotkit.ai/aws-strands) and an [`@ag-ui/client`](https://docs.ag-ui.com/) `HttpAgent` on the React website. See the <Link path="guides/connection/react-agui">React to AG-UI Agent</Link> guide for details.
 :::
 
 ## Prerequisites
@@ -24,7 +24,7 @@ If your Python Agent was generated with `protocol=AG-UI`, the connection generat
 Before using this generator, ensure you have:
 
 1. A React website (generated using the <Link path="guides/react-website">`ts#website` generator</Link>)
-2. A Python Agent with `protocol=HTTP` (generated using the <Link path="guides/py-agent">`py#agent` generator</Link>)
+2. A Python Agent with `protocol=http` (generated using the <Link path="guides/py-agent">`py#agent` generator</Link>)
 3. Cognito Auth added via the <Link path="/guides/react-website-auth">`ts#website#auth` generator</Link>
 
 ## Usage
@@ -122,11 +122,8 @@ function ChatComponent() {
     },
   }));
 
-  const handleSend = (message: string) => {
-    invoke.mutate({
-      prompt: message,
-      sessionId: 'my-session',
-    });
+  const handleSend = (prompt: string) => {
+    invoke.mutate({ prompt });
   };
 
   return (
@@ -154,12 +151,9 @@ function ChatComponent() {
   const client = useMyAgentClient();
   const [chunks, setChunks] = useState<StreamChunk[]>([]);
 
-  const handleSend = async (message: string) => {
+  const handleSend = async (prompt: string) => {
     setChunks([]);
-    for await (const chunk of client.invoke({
-      prompt: message,
-      sessionId: 'my-session',
-    })) {
+    for await (const chunk of client.invoke({ prompt })) {
       setChunks((prev) => [...prev, chunk]);
     }
   };
@@ -177,13 +171,13 @@ function ChatComponent() {
 
 ## Local Development
 
-The connection generator automatically configures `serve-local` integration:
+The connection generator automatically configures `dev` integration:
 
-1. Running `nx serve-local <website>` will also start the agent's local FastAPI server
+1. Running `nx dev <website>` will also start the agent's local FastAPI server
 2. The runtime config is overridden to point to the local HTTP URL (e.g., `http://localhost:8081/`)
 3. The TypeScript client is automatically regenerated when the agent's API changes
 
-<NxCommands commands={['serve-local <WebsiteProject>']} />
+<NxCommands commands={['dev <WebsiteProject>']} />
 
 :::tip[Hot Reloading]
 The website and connected agent will hot-reload, enabling you to quickly iterate on both together without deploying to AWS.

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

@@ -2,8 +2,8 @@
 title: React to Smithy API
 description: Connect a React website to a Smithy TypeScript API
 when:
-  sourceType: react
-  targetType: smithy
+  sourceType: ts#react-website
+  targetType: ts#smithy-api
 ---
 
 import { FileTree, Steps } from '@astrojs/starlight/components';
@@ -21,7 +21,7 @@ The `connection` generator provides a way to quickly integrate your React websit
 Before using this generator, ensure your React application has:
 
 1. A `main.tsx` file that renders your application
-2. A working Smithy TypeScript API backend (generated using the <Link path="/guides/ts-smithy-api">`ts#smithy-api` generator</Link>)
+2. A working Smithy TypeScript API backend (generated using the <Link path="/guides/ts-smithy-api">`ts#api` generator</Link> with `--framework=smithy`)
 3. Cognito Auth added via the <Link path="/guides/react-website-auth">`ts#website#auth` generator</Link> if connecting an API which uses Cognito or IAM auth
 
 <details>
@@ -116,9 +116,9 @@ Whenever you make changes to your Smithy API model, you need to rebuild your pro
 :::
 
 :::tip[Auto-Regeneration]
-If you're actively working on both your React application and Smithy API together, use the React application's `serve-local` target which will automatically regenerate the client whenever your API changes, as well as hot-reloading your website and local Smithy API server:
+If you're actively working on both your React application and Smithy API together, use the React application's `dev` target which will automatically regenerate the client whenever your API changes, as well as hot-reloading your website and local Smithy API server:
 
-<NxCommands commands={['serve-local <WebsiteProject>']} />
+<NxCommands commands={['dev <WebsiteProject>']} />
 
 For more fine-grained control, you can use the `watch-generate:<ApiName>-client` target for your React application to regenerate the client every time you make API changes:
 

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

@@ -2,7 +2,7 @@
 title: React to tRPC
 description: Connect a React website to a tRPC API
 when:
-  sourceType: react
+  sourceType: ts#react-website
   targetType: ts#trpc-api
 ---
 import { FileTree } from '@astrojs/starlight/components';
@@ -175,7 +175,7 @@ Subscriptions are only supported when the tRPC API uses `rest-lambda` (REST API)
 
 When connecting to a REST API tRPC backend, the generated client is automatically configured with a `splitLink` that routes subscription operations through `httpSubscriptionLink` (using SSE) and regular queries/mutations through `httpLink`. This means subscriptions work out of the box with no additional configuration.
 
-For information on how to define subscription procedures in your backend, see the <Link path="guides/trpc">`ts#trpc-api` generator guide</Link>.
+For information on how to define subscription procedures in your backend, see the <Link path="guides/trpc">tRPC API generator guide</Link>.
 
 #### Using the useSubscription Hook