@aws/nx-plugin-mcp 1.0.0 → 1.0.1

package/docs/guides/open-api-py-client.mdx

@@ -0,0 +1,270 @@
+---
+title: OpenAPI Python Client
+description: Reference documentation for the OpenAPI Python client generator
+generator: open-api#py-client
+sidebar:
+  # Hidden until a connection generator vends this client, matching the
+  # generator's own `hidden: true`.
+  hidden: true
+---
+import { FileTree } from '@astrojs/starlight/components';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import RunGenerator from '@components/run-generator.astro';
+import Drawer from '@components/drawer.astro';
+
+Generate a type-safe Python client for any OpenAPI specification, built on [httpx](https://www.python-httpx.org/) and [pydantic](https://docs.pydantic.dev/).
+
+The client is the Python counterpart of the `open-api#ts-client` generator: one class per API, keyword-only methods, typed errors you can narrow, and a single extension point — your own `httpx` client — for authentication and anything else you need on the wire.
+
+## Usage
+
+<RunGenerator generator="open-api#py-client" />
+
+### Options
+
+<GeneratorParameters generator="open-api#py-client" />
+
+## Generator Output
+
+<FileTree>
+
+- \<outputPath>
+  - \_\_init\_\_.py Exports the clients, `ApiError` and the `types` module
+  - types.py pydantic models for every schema in the specification
+  - errors.py `ApiError` and a subclass per operation
+  - client.py Synchronous client, using `httpx.Client`
+  - async_client.py Asynchronous client, using `httpx.AsyncClient`
+
+</FileTree>
+
+Pass `--clientType=sync` or `--clientType=async` to emit just one of the two clients.
+
+:::tip[Generated Client in Git]
+The client is ignored from version control by default, since it is regenerated from the specification. Remove the entry from your `.gitignore` to check it in instead — but note that any manual edits will be overwritten the next time it is generated.
+:::
+
+### Dependencies
+
+The generated code imports `httpx` and `pydantic`, so add both to the project you generate into:
+
+```toml
+# pyproject.toml
+dependencies = [
+  "httpx>=0.28.1",
+  "pydantic>=2.13.4",
+]
+```
+
+Nothing else is required — no runtime of its own, and no framework to adopt.
+
+## Using the Generated Client
+
+Instantiate the client with the API's base URL:
+
+```python
+from my_api import MyApi, MyApiConfig
+
+api = MyApi(MyApiConfig(url="https://api.example.com"))
+
+pet = api.pet.add_pet(name="rex", status="available")
+print(pet.id, pet.name)
+```
+
+Methods are **keyword-only**, so a call reads as the specification does, and required parameters come first:
+
+```python
+pets = api.pet.list_pets(status=["available"], limit=10)
+pet = api.pet.get_pet_by_id(pet_id=42)
+api.pet.delete_pet(pet_id=42)
+```
+
+Operations tagged in the specification are grouped into namespaces — `api.pet.add_pet(...)` above comes from the `pet` tag. Untagged operations sit directly on the client, as `api.health()`.
+
+An operation whose body is an object has its fields flattened into the call, so there is no wrapper to construct. Where the body is a list or a dictionary it is passed positionally instead:
+
+```python
+created = api.pet.batch_create([types.Pet(name="a"), types.Pet(name="b")])
+```
+
+### Types
+
+Every schema becomes a pydantic model in `types`, so results are validated and your editor knows their shape:
+
+```python
+from my_api import types
+
+pet = api.pet.add_pet(name="rex", owner=types.Owner(name="ann"))
+
+reveal_type(pet)         # types.Pet
+reveal_type(pet.owner)   # types.Owner | None
+```
+
+Enums become `Literal` types, so an invalid value is a type error rather than a failed request:
+
+```python
+api.pet.list_pets(status=["available"])   # ok
+api.pet.list_pets(status=["on-mars"])     # rejected before it is sent
+```
+
+Dates and date-times are `datetime.date` / `datetime.datetime` on the way in and out — the client handles the ISO-8601 conversion:
+
+```python
+event = api.create_event(day=datetime.date(2026, 4, 18))
+reveal_type(event.day)   # datetime.date
+```
+
+### Errors
+
+A non-success response raises an exception. Catch `ApiError` to handle any failure from either client:
+
+```python
+from my_api import ApiError
+
+try:
+    pet = api.pet.get_pet_by_id(pet_id=42)
+except ApiError as e:
+    print(e.status, e.error)
+```
+
+Each operation also has its own subclass, whose `.error` narrows to the responses that operation declares. `isinstance` picks out one status:
+
+```python {8,10}
+from my_api import types
+from my_api.errors import GetPetByIdApiError
+
+try:
+    pet = api.pet.get_pet_by_id(pet_id=42)
+except GetPetByIdApiError as e:
+    if isinstance(e.error, types.GetPetById404Error):
+        print("no such pet:", e.error.error.detail)
+    else:
+        print("failed with", e.status)
+```
+
+There is one class per response the operation declares, named after its status code — a declared `4XX` range becomes `GetPetById4XXError`.
+
+A body that doesn't match the schema the specification declares still raises the typed exception, carrying whatever the server actually sent — so a proxy's HTML error page surfaces as an error rather than a validation failure inside your error handler.
+
+### Streaming
+
+An operation that streams returns an iterator of parsed items, so you can consume the response as it arrives:
+
+```python
+for chunk in api.stream_chunks(count=4):
+    print(chunk.index, chunk.message)
+```
+
+### Async
+
+The async client mirrors the sync one, method for method:
+
+```python
+from my_api import AsyncMyApi, AsyncMyApiConfig
+
+async with AsyncMyApi(AsyncMyApiConfig(url="https://api.example.com")) as api:
+    pet = await api.pet.add_pet(name="rex")
+
+    async for chunk in api.stream_chunks(count=4):
+        print(chunk.message)
+```
+
+Both clients raise from the same hierarchy, so `except ApiError` catches either.
+
+## Authentication
+
+Authentication is the one thing every API does differently, so the client doesn't invent an abstraction for it. Supply your own `httpx` client and whatever you configure on it applies to every request:
+
+```python {6,13}
+import httpx
+from my_api import MyApi, MyApiConfig
+
+
+class BearerAuth(httpx.Auth):
+    def __init__(self, token: str) -> None:
+        self.token = token
+
+    def auth_flow(self, request):
+        request.headers["Authorization"] = f"Bearer {self.token}"
+        yield request
+
+
+with httpx.Client(auth=BearerAuth("my-token")) as http:
+    api = MyApi(MyApiConfig(url="https://api.example.com", httpx_client=http))
+    pet = api.pet.add_pet(name="rex")
+```
+
+This is the Python equivalent of passing a custom `fetch` to the TypeScript client. An [`httpx.Auth`](https://www.python-httpx.org/advanced/authentication/), event hooks, a custom transport, timeouts, retries, proxies, HTTP/2, and the client's own headers and query parameters all apply — including on multipart uploads and streaming responses.
+
+A client you supply is never closed by the generated one, so it is safe to share across several clients.
+
+<Drawer title="Signing requests with AWS SigV4" trigger="Click here for an example which signs requests with AWS IAM credentials.">
+
+`httpx.Auth` is all a signer needs to be. For an API behind IAM authentication:
+
+```python
+import hashlib
+from collections.abc import Generator
+
+import boto3
+import httpx
+from botocore.auth import SigV4Auth
+from botocore.awsrequest import AWSRequest
+
+from my_api import MyApi, MyApiConfig
+
+
+class SigV4HTTPXAuth(httpx.Auth):
+    requires_request_body = True
+
+    def __init__(self, credentials, service: str, region: str):
+        self.signer = SigV4Auth(credentials, service, region)
+
+    def auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response]:
+        headers = dict(request.headers)
+        headers.pop("connection", None)
+        headers["x-amz-content-sha256"] = hashlib.sha256(
+            request.content or b""
+        ).hexdigest()
+
+        aws_request = AWSRequest(
+            method=request.method,
+            url=str(request.url),
+            data=request.content,
+            headers=headers,
+        )
+        self.signer.add_auth(aws_request)
+
+        request.headers.clear()
+        request.headers.update(dict(aws_request.headers))
+        yield request
+
+
+session = boto3.Session()
+auth = SigV4HTTPXAuth(session.get_credentials(), "execute-api", session.region_name)
+
+with httpx.Client(auth=auth) as http:
+    api = MyApi(MyApiConfig(url="https://api.example.com", httpx_client=http))
+    pet = api.pet.add_pet(name="rex")
+```
+
+</Drawer>
+
+### Other configuration
+
+`Config` carries a small number of options beyond the URL and the client:
+
+```python
+api = MyApi(
+    MyApiConfig(
+        url="https://api.example.com",
+        # Sent with every request, where the operation sets no header of its own
+        headers={"x-tenant-id": "acme"},
+        # Omit the Content-Type the specification declares for each request
+        omit_content_type_header=False,
+    )
+)
+```
+
+A header an operation sets always wins over the same header here, so a per-call value is never merged into the configured one.

package/docs/guides/py-dynamodb.mdx

@@ -11,6 +11,7 @@ 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';
+import ArchitectureDiagram from '@components/architecture-diagram.astro';
 
 This generator creates a new Python project backed by [Amazon DynamoDB](https://aws.amazon.com/dynamodb/), using [PynamoDB](https://pynamodb.readthedocs.io/) for entity modelling. It generates the application code and infrastructure needed to provision and manage a DynamoDB table using AWS CDK or Terraform, with single-table design support and built-in local development via DynamoDB Local.
 
@@ -53,6 +54,12 @@ The local development scripts are shared across all DynamoDB projects (both Type
 
 <Snippet name="dynamodb/infrastructure" />
 
+#### Architecture
+
+The deployed project provisions the table itself, which any project it is connected to reads and writes:
+
+<ArchitectureDiagram />
+
 ## Local Development
 
 ### Starting Local DynamoDB

package/docs/guides/react-website-auth.mdx

@@ -10,6 +10,7 @@ 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';
+import ArchitectureDiagram from '@components/architecture-diagram.astro';
 
 The React Website Authentication generator adds authentication to your React website using [Amazon Cognito](https://aws.amazon.com/cognito/).
 
@@ -71,38 +72,7 @@ You will also find the following infrastructure code generated based on your sel
 
 This generator adds an Amazon Cognito user pool (for sign-in) and an identity pool (for federating signed-in users to scoped IAM credentials) to the existing static-website architecture:
 
-```d2 inline=true
-direction: right
-
-browser: Web Browser {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/client.svg
-}
-
-waf: WAF {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/waf.svg
-}
-
-cognito: Cognito\n(User + Identity Pool) {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/cognito.svg
-}
-
-iam: Scoped IAM\nCredentials {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/iam.svg
-}
-
-backend: Authenticated\nAWS Resources {
-  shape: rectangle
-}
-
-browser -> waf: Sign in
-waf -> cognito
-cognito -> iam
-browser -> backend: IAM/Cognito
-```
+<ArchitectureDiagram name="my-website" />
 
 #### Threat protection
 
@@ -255,7 +225,7 @@ In order to grant authenticated users access to perform certain actions, such as
 
 <Infrastructure>
 <Fragment slot="cdk">
-```ts title="packages/infra/src/stacks/application-stack.ts" {12}
+```ts title="packages/infra/src/stacks/application-stack.ts" {14}
 import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 import { MyWebsite, UserIdentity, MyApi } from '@my-scope/common-constructs';

package/docs/guides/react-website.mdx

@@ -17,6 +17,7 @@ import PackageManagerShortCommand from '@components/package-manager-short-comman
 import Infrastructure from '@components/infrastructure.astro';
 import Snippet from '@components/snippet.astro';
 import OptionFilter from '@components/option-filter.astro';
+import ArchitectureDiagram from '@components/architecture-diagram.astro';
 
 This generator creates a new [React](https://react.dev/) website with [shadcn/ui](https://ui.shadcn.com/) configured by default, along with the AWS CDK or Terraform infrastructure to deploy your website to the cloud as a static website hosted in [S3](https://aws.amazon.com/s3/), served by [CloudFront](https://aws.amazon.com/cloudfront/) and protected by [WAF](https://aws.amazon.com/waf/).
 
@@ -106,35 +107,9 @@ The generator creates infrastructure as code for deploying your website based on
 
 #### Architecture
 
-The deployed website has the following architecture:
+The deployed website has the following architecture: your built assets in an S3 bucket, served by a CloudFront distribution with an AWS WAFv2 Web ACL in front of it.
 
-```d2 inline=true
-direction: right
-
-browser: Web Browser {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/client.svg
-}
-
-waf: WAF {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/waf.svg
-}
-
-cloudfront: CloudFront {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/cloudfront.svg
-}
-
-s3: Static Assets\n(S3) {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/s3.svg
-}
-
-browser -> waf
-waf -> cloudfront
-cloudfront -> s3
-```
+<ArchitectureDiagram />
 
 ## Implementing your Website
 

package/docs/guides/runtime-config.mdx

@@ -5,6 +5,7 @@ description: How runtime configuration connects your generated projects using AW
 import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';
 import Infrastructure from '@components/infrastructure.astro';
 import Link from '@components/link.astro';
+import EmbeddedGraph from '@components/embedded-graph.astro';
 
 Runtime configuration is the mechanism used by Nx Plugin for AWS to pass deploy-time values between generated projects and components so they can connect to one another. For example, when you generate an API, its URL is automatically registered in the runtime configuration so that a connected website can discover it.
 
@@ -26,40 +27,7 @@ The `connection` namespace is also deployed as a `runtime-config.json` file to y
 
 You can define as many additional namespaces as you like, providing a convenient alternative to environment variables for passing deploy-time values to your Lambda functions or other compute resources.
 
-```d2
-direction: down
-
-iac: "Infrastructure as code\nRuntimeConfig.set(...)"
-
-appconfig: "AWS AppConfig" {
-  shape: cylinder
-  connection: "connection namespace"
-  agentcore: "agentcore namespace"
-  custom: "custom namespaces"
-}
-
-s3: "website S3 bucket" {
-  shape: cylinder
-  rcj: runtime-config.json {
-    shape: page
-  }
-}
-
-website: React website
-
-server: Lambda / agent
-
-iac -> appconfig.connection
-iac -> appconfig.agentcore
-iac -> appconfig.custom
-
-appconfig.connection -> s3.rcj: deployed
-s3.rcj -> website: fetched at load
-
-appconfig.connection -> server
-appconfig.agentcore -> server: Powertools getAppConfig
-appconfig.custom -> server
-```
+<EmbeddedGraph diagram="runtime-config" />
 
 ## Infrastructure
 

package/docs/guides/terraform-project.mdx

@@ -89,7 +89,7 @@ Application projects include full deployment capabilities with remote state mana
 
 You can start writing your Terraform infrastructure inside `src/main.tf`, for example:
 
-```diff title="src/main.tf" {16-19}
+```diff title="src/main.tf"
 -locals {
 -  account_id = data.aws_caller_identity.current.account_id
 -  aws_region = data.aws_region.current.id

package/docs/guides/ts-dynamodb.mdx

@@ -11,6 +11,7 @@ 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';
+import ArchitectureDiagram from '@components/architecture-diagram.astro';
 
 This generator creates a new TypeScript DynamoDB project backed by [Amazon DynamoDB](https://aws.amazon.com/dynamodb/), using [ElectroDB](https://electrodb.dev/) for type-safe entity modelling. It generates the application code and infrastructure needed to provision and manage a DynamoDB table using AWS CDK or Terraform, with single-table design support and built-in local development via DynamoDB Local.
 
@@ -53,6 +54,12 @@ The local development scripts are shared across all DynamoDB projects (both Type
 
 <Snippet name="dynamodb/infrastructure" />
 
+#### Architecture
+
+The deployed project provisions the table itself, which any project it is connected to reads and writes:
+
+<ArchitectureDiagram />
+
 ## Local Development
 
 ### Starting Local DynamoDB

package/docs/guides/ts-smithy-api.mdx

@@ -20,6 +20,7 @@ import Snippet from '@components/snippet.astro';
 import OptionFilter from '@components/option-filter.astro';
 import InstallCommand from '@components/install-command.astro';
 import { TS_VERSIONS } from '../../../../../../packages/nx-plugin/src/utils/versions';
+import ArchitectureDiagram from '@components/architecture-diagram.astro';
 
 [Smithy](https://smithy.io/) is a protocol-agnostic interface definition language for authoring APIs in a model driven fashion.
 
@@ -126,47 +127,7 @@ This project is generated using the <Link path="/guides/terraform-project">`terr
 
 The deployed Smithy API has the following architecture, with an [AWS WAFv2](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) Web ACL in front of the API Gateway stage:
 
-```d2 inline=true
-direction: right
-
-client: Client {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/client.svg
-}
-
-waf: WAF {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/waf.svg
-}
-
-apigw: API Gateway\n(REST API) {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/api-gateway.svg
-}
-
-lambda: Lambda\n(Smithy Server SDK) {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/lambda.svg
-}
-
-cw: CloudWatch\n(Logs, Metrics) {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/cloudwatch.svg
-  near: top-right
-}
-
-xray: X-Ray\n(Traces) {
-  shape: image
-  icon: /nx-plugin-for-aws/icons/aws/xray.svg
-  near: bottom-right
-}
-
-client -> waf
-waf -> apigw
-apigw -> lambda
-lambda -> cw
-lambda -> xray
-```
+<ArchitectureDiagram options={{ infra: 'rest-lambda' }} />
 
 ## Implementing your Smithy API
 
@@ -315,7 +276,7 @@ You must construct the context yourself in both `handler.ts` (the Lambda functio
 
 The generator configures structured logging using AWS Lambda Powertools with automatic context injection via Middy middleware.
 
-```typescript {3}
+```typescript {4}
 // handler.ts
 export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
   .use(captureLambdaHandler(tracer))
@@ -326,7 +287,7 @@ export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
 
 You can reference the logger from your operation implementations via the context:
 
-```typescript {5}
+```typescript {6}
 // operations/echo.ts
 import { ServiceContext } from '../context.js';
 import { Echo as EchoOperation } from '../generated/ssdk/index.js';
@@ -341,7 +302,7 @@ export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
 
 AWS X-Ray tracing is configured automatically via the `captureLambdaHandler` middleware.
 
-```typescript {2}
+```typescript {3}
 // handler.ts
 export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
   .use(captureLambdaHandler(tracer))
@@ -352,7 +313,7 @@ export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
 
 You can add custom subsegments to your traces in your operations:
 
-```typescript {6, 10, 13}
+```typescript {7, 11, 14}
 // operations/echo.ts
 import { ServiceContext } from '../context.js';
 import { Echo as EchoOperation } from '../generated/ssdk/index.js';
@@ -375,7 +336,7 @@ export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
 
 CloudWatch metrics are collected automatically for each request via the `logMetrics` middleware.
 
-```typescript {4}
+```typescript {5}
 // handler.ts
 export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
   .use(captureLambdaHandler(tracer))
@@ -386,7 +347,7 @@ export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
 
 You can add custom metrics in your operations:
 
-```typescript {6}
+```typescript {7}
 // operations/echo.ts
 import { MetricUnit } from '@aws-lambda-powertools/metrics';
 import { ServiceContext } from '../context.js';

package/docs/guides/typescript-project.mdx

@@ -228,9 +228,9 @@ npm has no catalog feature, so versions are declared directly in each `package.j
 
 ##### Opting out of catalogs
 
-Catalogs are enabled by default. To turn them off, create your workspace with `--catalog false`:
+Catalogs are enabled by default. To turn them off, create your workspace with `--catalog=false`:
 
-<CreateNxWorkspaceCommand workspace="my-project" extraArgs="--catalog false" />
+<CreateNxWorkspaceCommand workspace="my-project" values={{ catalog: false }} />
 
 Or set it in `aws-nx-plugin.config.mts` at any time:
 

package/docs/guides/workspace.mdx

@@ -27,6 +27,7 @@ When you create a new workspace with `@aws/nx-plugin`, the preset generator sets
   - package.json Root package.json for your monorepo
   - nx.json Nx configuration (common targets, sync generators, caching)
   - tsconfig.base.json Root TypeScript configuration
+  - biome.json Biome configuration for linting and formatting
   - aws-nx-plugin.config.mts Nx Plugin for AWS configuration
   - .git-secrets/ Vendored git-secrets bash script for credential scanning
   - .gitallowed Patterns git-secrets treats as false positives
@@ -72,7 +73,7 @@ For details on how TypeScript and Python projects are set up, refer to the <Link
 
 ### Caching
 
-Nx caches the output of previously executed targets and replays them when the inputs haven't changed. This dramatically speeds up builds, tests, and linting — especially in CI. If you encounter stale or unexpected behaviour, reset the cache with:
+Nx caches the output of previously executed targets and replays them when the inputs haven't changed. This dramatically speeds up builds, tests, and linting. If you encounter stale or unexpected behaviour, reset the cache with:
 
 <NxCommands commands={['reset']} />
 
@@ -88,15 +89,7 @@ New workspaces set `parallel` in `nx.json`, which controls how many tasks Nx run
 }
 ```
 
-Lower it if you're building on a machine with fewer cores or limited memory:
-
-```json title="nx.json"
-{
-  "parallel": 3
-}
-```
-
-You can also override it per-invocation:
+Lower it if you're building on a machine with fewer cores or limited memory. You can also override it per-invocation:
 
 <NxCommands commands={['run-many --target build --parallel=4']} />
 
@@ -166,6 +159,10 @@ This will run the chosen target as well as the targets it depends on.
 
 New workspaces are configured with [Biome](https://biomejs.dev/) for static analysis and code formatting. Running `lint` checks all projects for issues, and `lint --configuration=fix` auto-fixes them.
 
+### MCP Configuration
+
+The plugin's <Link path="get_started/building-with-ai">MCP server</Link> is configured as a project level MCP server for Claude Code, Cursor, Kiro, Gemini CLI, GitHub Copilot and OpenAI Codex, so your coding assistant can discover and run the plugin's generators without any setup. The configuration is committed with your workspace, giving everyone on your team the same setup. Remove any configurations for coding assistants you and your team do not use.
+
 ### Git Secrets
 
 Workspaces are set up with [git-secrets](https://github.com/awslabs/git-secrets) pre-commit hooks that scan staged files for AWS credential patterns before each commit. This prevents accidentally committing access keys, secret keys, and other sensitive values.