@aws/nx-plugin-mcp 1.0.0-rc.9 → 1.0.0-rc.91

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

@@ -0,0 +1,182 @@
+---
+title: Python Agent to Gateway
+description: Connect a Python Agent to an AgentCore Gateway
+when:
+  sourceType: py#agent
+  targetType: agentcore-gateway
+---
+import { FileTree, Tabs, TabItem } 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 your <Link path="guides/py-agent">Python Agent</Link> to an <Link path="guides/agentcore-gateway">AgentCore Gateway</Link>.
+
+The generator wires the agent so it authenticates to the Gateway with IAM SigV4 (via `httpx` request signing) when deployed, and connects to the local gateway started by the Gateway project when running locally.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A Python project with a <Link path="guides/py-agent">Agent</Link> component (`infra: agentcore`)
+2. A <Link path="guides/agentcore-gateway">`agentcore-gateway`</Link> project with `protocol: mcp` and `auth: iam`
+
+The Gateway must serve the `mcp` protocol — the agent reaches it as an MCP client, so its targets are exposed as tools. The Gateway must also use IAM authentication: the agent signs its requests with SigV4 using its own execution role. The generator rejects Cognito-authenticated gateways.
+
+:::note[One direction per Gateway]
+A single Gateway cannot both be called by an agent and front one. Fronting agent runtimes needs `protocol: http` (see <Link path="guides/connection/agentcore-gateway-agent">Gateway to Agent</Link>), whereas being called by an agent needs `protocol: mcp`. Use a separate Gateway for each direction.
+:::
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select the agent project as the source and the Gateway project as the target.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator emits shared core-gateway modules into your `agent_connection` Python project, plus a per-Gateway wrapper, and modifies your agent:
+
+<FileTree>
+
+- packages/common/agent\_connection
+  - \<scope>\_agent\_connection
+    - core/
+      - agentcore\_endpoints.py Framework-agnostic ARN/URL resolution
+      - 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/
+      - \<gateway\_snake>\_client\_\<framework>.py Per-Gateway client wrapper
+    - \_\_init\_\_.py Re-exports the Gateway client
+
+</FileTree>
+
+The client suffix matches your agent's framework (`_strands` or `_langchain`).
+
+Additionally, the generator:
+
+- Modifies your agent's `agent.py` to import the Gateway client and register its tools in `tools`
+- Adds `agent_connection` as a workspace dependency of the agent
+- Wires the agent's `<agent>-dev` target to depend on the Gateway's `dev` target
+
+## Using the connected Gateway
+
+The generator transforms your agent's `agent.py` to use the Gateway client:
+
+<Tabs syncKey="agent-framework">
+<TabItem label="Strands" _filter={{ framework: 'strands' }}>
+```python title="packages/example/example/my_agent/agent.py" {4,8,9-13}
+from contextlib import contextmanager
+from strands import Agent
+
+from my_scope_agent_connection import MyGatewayClientStrands
+
+@contextmanager
+def get_agent():
+    my_gateway = MyGatewayClientStrands.create()
+    with (
+        my_gateway,
+    ):
+        yield Agent(
+            system_prompt="...",
+            tools=[*my_gateway.list_tools_sync()],
+        )
+```
+
+`MyGatewayClientStrands.create()` returns a single context-manageable `MCPClient` whose `list_tools_sync()` yields every tool available through the Gateway.
+</TabItem>
+<TabItem label="LangChain" _filter={{ framework: 'langchain' }}>
+```python title="packages/example/example/my_agent/agent.py" {4,7,11}
+from langchain.agents import create_agent
+from langchain_aws import ChatBedrockConverse
+
+from my_scope_agent_connection import MyGatewayClientLangChain
+
+def get_agent():
+    my_gateway = MyGatewayClientLangChain.create()
+    return create_agent(
+        model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
+        system_prompt="...",
+        tools=[*my_gateway],
+    )
+```
+
+`MyGatewayClientLangChain.create()` returns a list of tools loaded via [`langchain-mcp-adapters`](https://docs.langchain.com/oss/python/langchain/mcp). Each tool opens a fresh session per call, so no `with` block is needed.
+</TabItem>
+</Tabs>
+
+In both cases the client behaves the same way per mode:
+
+- **Deployed mode** (`LOCAL_DEV` unset): tools pointed at the Gateway's MCP endpoint, SigV4-signed.
+- **Local mode** (`LOCAL_DEV=true`): plain-HTTP tools pointed at the local gateway started by the Gateway project's `dev` target.
+
+The session ID is propagated to downstream MCP servers automatically via the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header.
+
+## Infrastructure
+
+After running the generator you must grant the agent permission to invoke the Gateway.
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts title="packages/infra/src/stacks/application-stack.ts" {5}
+const gateway = new MyGateway(this, 'MyGateway');
+const myAgent = new MyAgent(this, 'MyAgent');
+
+// Grant the agent permissions to invoke the Gateway
+gateway.grantInvokeAccess(myAgent);
+```
+
+The Gateway URL is automatically registered in the `agentcore.gateways.<ClassName>` 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">
+```hcl title="packages/infra/src/main.tf" {8-13}
+module "my_gateway" {
+  source = "../../common/terraform/src/app/gateways/my-gateway"
+}
+
+module "my_agent" {
+  source = "../../common/terraform/src/app/agents/my-agent"
+
+  # Grant the agent permission to invoke the Gateway
+  additional_iam_policy_statements = [{
+    Effect   = "Allow"
+    Action   = ["bedrock-agentcore:InvokeGateway"]
+    Resource = [module.my_gateway.gateway_arn]
+  }]
+}
+```
+
+The Gateway URL is automatically registered in the `agentcore.gateways.<ClassName>` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link> by the generated Terraform module, so the agent can discover it at runtime.
+</Fragment>
+</Infrastructure>
+
+## Local Development
+
+The generator configures the agent's `dev` target to:
+
+1. Start the connected Gateway's local gateway and every attached MCP server
+2. Set `LOCAL_DEV=true` so the generated client points at the local gateway instead of the deployed Gateway
+
+Run the agent locally with:
+
+<NxCommands commands={["<agent-name>-dev <project-name>"]} />
+
+To run the agent locally **against the deployed Gateway** instead (for example, to exercise Cedar policies), use the agent's `serve` target. Without `LOCAL_DEV` set, the client resolves the deployed Gateway URL from runtime configuration and SigV4-signs requests with your local AWS credentials:
+
+<NxCommands commands={["<agent-name>-serve <project-name>"]} />
+
+### Local fidelity
+
+The local gateway stands in for the deployed Gateway, so:
+
+- **No Cedar policy evaluation.** Every tool is visible to the agent regardless of policies. Use the `serve` target to exercise policies against the deployed Gateway.
+- **Tool-name prefixing is preserved.** Each local MCP server's tools are exposed as `<target-name>___<tool-name>`, matching what the deployed Gateway emits. This keeps the agent's system prompt and the Cedar action names you reference consistent across local and deployed runs.

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

@@ -7,7 +7,7 @@ when:
     - ts#mcp-server
     - py#mcp-server
 ---
-import { FileTree } from '@astrojs/starlight/components';
+import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
 import Link from '@components/link.astro';
 import RunGenerator from '@components/run-generator.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
@@ -22,7 +22,7 @@ The generator sets up all the necessary wiring so your agent can discover and in
 
 Before using this generator, ensure you have:
 
-1. A Python project with a <Link path="guides/py-agent">Strands Agent</Link> component
+1. A Python project with a <Link path="guides/py-agent">Python Agent</Link> component (Strands or LangChain)
 2. A project with an MCP server component (either <Link path="guides/ts-mcp-server">`ts#mcp-server`</Link> or <Link path="guides/py-mcp-server">`py#mcp-server`</Link>)
 3. Both components created with `infra: agentcore`
 
@@ -48,30 +48,37 @@ The generator creates a shared `agent_connection` Python project at `packages/co
   - \<scope>\_agent\_connection
     - \_\_init\_\_.py Re-exports per-connection clients
     - core
-      - agentcore\_mcp\_client.py Core AgentCore MCP client
+      - agentcore\_endpoints.py Framework-agnostic ARN/URL resolution
+      - 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
-      - \<mcp\_server\_name>\_client.py Per-connection client for each MCP server
+      - \<mcp\_server\_name>\_client\_\<framework>.py Per-connection client for each MCP server
 
 </FileTree>
 
+The client suffix matches your agent's framework (`_strands` or `_langchain`).
+
 Additionally, the generator:
 - Transforms your agent's `agent.py` to import and use the MCP server's tools via a class-based client
 - Adds the `agent_connection` project as a workspace dependency of your agent project
-- Updates the agent's `serve-local` target to depend on the MCP server's serve target
+- Updates the agent's `dev` target to depend on the MCP server's serve target
 
 ## Using the Connected MCP Server
 
 The generator transforms your agent's `agent.py` to use the MCP server's tools:
 
-```python title="packages/my-project/my_module/agent/agent.py" {4,10-14}
+<Tabs syncKey="agent-framework">
+<TabItem label="Strands" _filter={{ framework: 'strands' }}>
+```python title="packages/my-project/my_module/agent/agent.py" {4,8,9-13}
 from contextlib import contextmanager
 from strands import Agent
 
-from my_scope_agent_connection import MyMcpServerClient
+from my_scope_agent_connection import MyMcpServerClientStrands
 
 @contextmanager
-def get_agent(session_id: str):
-    my_mcp_server = MyMcpServerClient.create(session_id=session_id)
+def get_agent():
+    my_mcp_server = MyMcpServerClientStrands.create()
     with (
         my_mcp_server,
     ):
@@ -81,7 +88,29 @@ def get_agent(session_id: str):
         )
 ```
 
-The `session_id` parameter is plumbed through from the caller, ensuring consistency for [Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html).
+The Strands client is a context manager, entered in a `with` block around the agent.
+</TabItem>
+<TabItem label="LangChain" _filter={{ framework: 'langchain' }}>
+```python title="packages/my-project/my_module/agent/agent.py" {4,7,11}
+from langchain.agents import create_agent
+from langchain_aws import ChatBedrockConverse
+
+from my_scope_agent_connection import MyMcpServerClientLangChain
+
+def get_agent():
+    my_mcp_server = MyMcpServerClientLangChain.create()
+    return create_agent(
+        model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
+        system_prompt="...",
+        tools=[*my_mcp_server],
+    )
+```
+
+The LangChain client returns a list of tools loaded via [`langchain-mcp-adapters`](https://docs.langchain.com/oss/python/langchain/mcp). Each tool opens a fresh MCP session per call, so the tools stay usable for the agent's lifetime — no `with` block is needed.
+</TabItem>
+</Tabs>
+
+The AgentCore session ID is propagated to the MCP server automatically via the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header for both frameworks, ensuring consistency for [Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html).
 
 ## Infrastructure
 
@@ -102,7 +131,7 @@ The MCP server's AgentCore runtime ARN is automatically registered in the `agent
 <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" {12-24}
+```hcl title="packages/infra/src/main.tf" {9-25}
 module "inventory_mcp_server" {
   source = "../../common/terraform/src/app/mcp-servers/inventory-mcp"
 }
@@ -136,12 +165,12 @@ The MCP server's AgentCore runtime ARN is automatically registered in the `agent
 
 ## Local Development
 
-The generator configures the agent's `serve-local` target to:
+The generator configures the agent's `dev` target to:
 1. Start the connected MCP server(s) automatically
-2. Set `SERVE_LOCAL=true` so the generated client uses direct HTTP transport instead of AgentCore
+2. Set `LOCAL_DEV=true` so the generated client uses direct HTTP transport instead of AgentCore
 
 Run the agent locally with:
 
-<NxCommands commands={["<agent-name>-serve-local <project-name>"]} />
+<NxCommands commands={["<agent-name>-dev <project-name>"]} />
 
 This will start both the agent and all connected MCP servers, with the agent connecting to the MCP servers directly via HTTP on their assigned local ports.

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

@@ -0,0 +1,169 @@
+---
+title: Python Agent to Relational Database
+description: Connect a Python Agent to a Relational Database
+when:
+  sourceType: py#agent
+  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-agent">Python Agent</Link> to a <Link path="guides/py-rdb">Python Relational Database</Link> project, making the database session available inside your agent tools.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A <Link path="guides/py-agent">`py#agent`</Link> project
+2. A <Link path="guides/py-rdb">`py#rdb`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your Agent project as the source and your relational database project as the target. If the project contains multiple agent components, specify `sourceComponent` to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+<FileTree>
+
+- packages/my\_service
+  - project.json Adds a dependency from `my_agent-dev` on the database's `dev` target
+  - 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
+
+</FileTree>
+
+## Using the Database in Agent Tools
+
+Import `session_context` from your database package and use it inside your agent tools:
+
+```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 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()]
+```
+
+## Infrastructure
+
+The generated agent 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 myAgent = new MyAgent(this, 'MyAgent', {
+  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(this, {
+    vpc,
+    vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
+    securityGroups: [
+      new SecurityGroup(this, 'MyAgentSecurityGroup', { vpc, allowAllOutbound: true }),
+    ],
+  }),
+});
+
+db.allowDefaultPortFrom(myAgent);
+db.grantConnect(myAgent);
+```
+
+`allowDefaultPortFrom` opens the security group rule so the agent runtime can reach the database port. `grantConnect` grants IAM `rds-db:connect` permission to the agent's execution role.
+
+
+</Fragment>
+<Fragment slot="terraform">
+
+Run the agent 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_agent" {
+  source     = "../../common/terraform/src/app/agents/my-agent"
+  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" "agent_to_database" {
+  description                  = "Allow the agent runtime to connect to the database"
+  security_group_id            = module.my_database.security_group_id
+  referenced_security_group_id = module.my_agent.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" "agent_to_database" {
+  description                  = "Allow outbound traffic from the agent runtime to the database"
+  security_group_id            = module.my_agent.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. That application exposes the `database` namespace by default, so the database module's runtime configuration entry is deployed without further configuration.
+
+</Fragment>
+</Infrastructure>
+
+### SSL Requirements When Connecting Without RDS Proxy
+
+When the agent connects directly to the Aurora cluster (without RDS Proxy), the connection generator updates the generated agent 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 agent runtime.
+
+## Local Development
+
+<NxCommands commands={["<agent-name>-dev <project-name>"]} />
+
+This starts the agent 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/py-fast-api-dynamodb.mdx

@@ -0,0 +1,56 @@
+---
+title: FastAPI to DynamoDB
+description: Connect a FastAPI to a Python DynamoDB project
+when:
+  sourceType: py#fast-api
+  targetType: py#dynamodb
+---
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import Snippet from '@components/snippet.astro';
+
+The `connection` generator wires a <Link path="guides/fastapi">FastAPI</Link> to a <Link path="guides/py-dynamodb">Python DynamoDB</Link> project, configuring local development so both start together automatically.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A FastAPI project (generated with `py#api --framework=fastapi`), see the <Link path="guides/fastapi">`py#api`</Link> guide
+2. A <Link path="guides/py-dynamodb">`py#dynamodb`</Link> project
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your FastAPI project as the source and your DynamoDB project as the target.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator updates the FastAPI's `project.json` to add a dependency from its `dev` target to the DynamoDB project's `dev` target, and adds the DynamoDB package as a workspace dependency. No source files are modified.
+
+## Using DynamoDB in Route Handlers
+
+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
+
+@app.get("/examples")
+def list_examples():
+    return list(ExampleModel.scan())
+```
+
+## Infrastructure
+
+<Snippet name="connection/lambda-dynamodb-access" />
+
+## Local Development
+
+<Snippet name="connection/py-dynamodb-local-development" />