@aws/nx-plugin-mcp 1.0.0-rc.7 → 1.0.0-rc.71
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/aws-nx-mcp.js +12317 -10933
- package/docs/get_started/building-with-ai.mdx +116 -0
- package/docs/get_started/concepts.mdx +67 -0
- package/docs/get_started/existing-project.mdx +180 -0
- package/docs/get_started/graph-builder.mdx +39 -0
- package/docs/get_started/quick-start.mdx +277 -0
- package/docs/get_started/tutorials/contribute-generator.mdx +408 -0
- package/docs/get_started/tutorials/dungeon-game/1.mdx +1301 -0
- package/docs/get_started/tutorials/dungeon-game/2.mdx +237 -0
- package/docs/get_started/tutorials/dungeon-game/3.mdx +76 -0
- package/docs/get_started/tutorials/dungeon-game/4.mdx +164 -0
- package/docs/get_started/tutorials/dungeon-game/overview.mdx +145 -0
- package/docs/get_started/tutorials/dungeon-game/wrap-up.mdx +41 -0
- package/docs/get_started/tutorials/existing-project.mdx +4 -0
- package/docs/get_started/upgrading.mdx +147 -0
- package/docs/guides/agentcore-gateway.mdx +490 -0
- package/docs/guides/agentcore-harness.mdx +275 -0
- package/docs/guides/astro-docs.mdx +8 -0
- package/docs/guides/connection/agentcore-gateway-agent.mdx +222 -0
- package/docs/guides/connection/agentcore-gateway-gateway.mdx +154 -0
- package/docs/guides/connection/agentcore-gateway-mcp.mdx +134 -0
- package/docs/guides/connection/py-agent-a2a.mdx +48 -16
- package/docs/guides/connection/py-agent-dynamodb.mdx +116 -0
- package/docs/guides/connection/py-agent-gateway.mdx +178 -0
- package/docs/guides/connection/py-agent-mcp.mdx +43 -14
- package/docs/guides/connection/py-agent-rdb.mdx +178 -0
- package/docs/guides/connection/py-fast-api-dynamodb.mdx +56 -0
- package/docs/guides/connection/py-fast-api-rdb.mdx +184 -0
- package/docs/guides/connection/py-mcp-server-dynamodb.mdx +116 -0
- package/docs/guides/connection/py-mcp-server-rdb.mdx +187 -0
- package/docs/guides/connection/react-agentcore-gateway.mdx +112 -0
- package/docs/guides/connection/react-agui.mdx +13 -13
- package/docs/guides/connection/react-fastapi.mdx +38 -2
- package/docs/guides/connection/react-py-agent.mdx +9 -15
- package/docs/guides/connection/react-smithy.mdx +3 -3
- package/docs/guides/connection/react-trpc.mdx +1 -1
- package/docs/guides/connection/react-ts-agent.mdx +8 -8
- package/docs/guides/connection/smithy-dynamodb.mdx +5 -5
- package/docs/guides/connection/smithy-rdb.mdx +9 -9
- package/docs/guides/connection/trpc-dynamodb.mdx +5 -5
- package/docs/guides/connection/trpc-rdb.mdx +6 -6
- package/docs/guides/connection/ts-agent-a2a.mdx +14 -11
- package/docs/guides/connection/ts-agent-dynamodb.mdx +5 -5
- package/docs/guides/connection/ts-agent-gateway.mdx +143 -0
- package/docs/guides/connection/ts-agent-mcp.mdx +12 -9
- package/docs/guides/connection/ts-agent-rdb.mdx +70 -25
- package/docs/guides/connection/ts-mcp-server-dynamodb.mdx +5 -5
- package/docs/guides/connection/ts-mcp-server-rdb.mdx +68 -18
- package/docs/guides/connection.mdx +122 -5
- package/docs/guides/docker-bundling.mdx +69 -12
- package/docs/guides/fastapi.mdx +249 -9
- package/docs/guides/local-development.mdx +87 -0
- package/docs/guides/nx-generator.mdx +4 -3
- package/docs/guides/nx-migration.mdx +165 -0
- package/docs/guides/py-agent.mdx +264 -49
- package/docs/guides/py-dynamodb.mdx +476 -0
- package/docs/guides/py-mcp-server.mdx +61 -2
- package/docs/guides/py-rdb.mdx +265 -0
- package/docs/guides/python-lambda-function.mdx +1 -1
- package/docs/guides/react-website-auth.mdx +65 -4
- package/docs/guides/react-website.mdx +149 -30
- package/docs/guides/runtime-config.mdx +1 -1
- package/docs/guides/security.mdx +75 -0
- package/docs/guides/smithy-project.mdx +167 -0
- package/docs/guides/terraform-project.mdx +2 -2
- package/docs/guides/trpc.mdx +53 -16
- package/docs/guides/ts-agent.mdx +183 -10
- package/docs/guides/ts-dcr-proxy.mdx +569 -0
- package/docs/guides/ts-dynamodb.mdx +66 -242
- package/docs/guides/ts-lambda-function.mdx +1 -1
- package/docs/guides/ts-mcp-server.mdx +109 -29
- package/docs/guides/ts-nx-plugin.mdx +3 -3
- package/docs/guides/ts-rdb.mdx +113 -467
- package/docs/guides/ts-smithy-api.mdx +258 -18
- package/docs/guides/typescript-infrastructure.mdx +46 -24
- package/docs/guides/typescript-project.mdx +134 -27
- package/docs/guides/workspace.mdx +10 -3
- package/docs/snippets/agent/architecture.mdx +1 -1
- package/docs/snippets/agent/bedrock-deployment.mdx +9 -5
- package/docs/snippets/agent/runtime-arn.mdx +23 -2
- package/docs/snippets/agent/securing-your-agent.mdx +39 -0
- package/docs/snippets/api/access-logging.mdx +33 -0
- package/docs/snippets/api/cors-configuration-cdk-note.mdx +1 -1
- package/docs/snippets/api/cors-configuration-terraform-note.mdx +1 -1
- package/docs/snippets/api/type-safe-api-integrations.mdx +33 -2
- package/docs/snippets/api/waf-configuration.mdx +3 -3
- package/docs/snippets/connection/a2a-infrastructure.mdx +1 -1
- package/docs/snippets/connection/dynamodb-local-development.mdx +2 -2
- package/docs/snippets/connection/lambda-dynamodb-access.mdx +1 -1
- package/docs/snippets/connection/py-dynamodb-local-development.mdx +7 -0
- package/docs/snippets/connection/py-lambda-rdb-ssl-requirements.mdx +7 -0
- package/docs/snippets/connection/rdb-api-infrastructure.mdx +51 -19
- package/docs/snippets/dynamodb/deploying-table.mdx +166 -0
- package/docs/snippets/dynamodb/gsi-config.mdx +38 -0
- package/docs/snippets/dynamodb/infrastructure.mdx +33 -0
- package/docs/snippets/dynamodb/local-dev-start.mdx +13 -0
- package/docs/snippets/dynamodb/local-dev-windows.mdx +15 -0
- package/docs/snippets/lambda-function/deploying-your-function.mdx +3 -3
- package/docs/snippets/mcp/architecture.mdx +1 -1
- package/docs/snippets/mcp/bedrock-deployment.mdx +9 -5
- package/docs/snippets/mcp/config.mdx +3 -2
- package/docs/snippets/pdk-migration/example/01-migrate-api.mdx +7 -5
- package/docs/snippets/pdk-migration/example/02-migrate-website.mdx +29 -10
- package/docs/snippets/pdk-migration/example/03-migrate-infra.mdx +4 -4
- package/docs/snippets/pdk-migration/faq/type-safe-api.mdx +5 -111
- package/docs/snippets/prerequisites.mdx +1 -4
- package/docs/snippets/rdb/architecture.mdx +38 -0
- package/docs/snippets/rdb/cluster-instances.mdx +31 -0
- package/docs/snippets/rdb/deletion-protection.mdx +34 -0
- package/docs/snippets/rdb/deploying.mdx +187 -0
- package/docs/snippets/rdb/encryption-key-rotation.mdx +30 -0
- package/docs/snippets/rdb/engine-version.mdx +63 -0
- package/docs/snippets/rdb/infrastructure.mdx +35 -0
- package/docs/snippets/rdb/logging-mysql.mdx +5 -0
- package/docs/snippets/rdb/logging-postgres.mdx +5 -0
- package/docs/snippets/rdb/performance-insights.mdx +34 -0
- package/docs/snippets/rdb/rds-proxy.mdx +50 -0
- package/docs/snippets/rdb/removal-policy.mdx +57 -0
- package/docs/snippets/rdb/serverless-capacity.mdx +32 -0
- package/docs/snippets/recommended-prerequisites.mdx +10 -0
- package/docs/snippets/required-prerequisites.mdx +1 -4
- package/docs/snippets/runtime-config-app-id-note.mdx +8 -0
- package/docs/snippets/shared-constructs.mdx +1 -1
- package/docs/snippets/trivy-image-scan.mdx +37 -0
- package/generators.json +152 -10
- package/package.json +1 -1
- package/src/agentcore-gateway/agent-connection/schema.json +31 -0
- package/src/agentcore-gateway/gateway-connection/schema.json +31 -0
- package/src/agentcore-gateway/mcp-connection/schema.json +31 -0
- package/src/agentcore-gateway/react-connection/schema.json +31 -0
- package/src/agentcore-gateway/schema.json +72 -0
- package/src/agentcore-harness/schema.json +53 -0
- package/src/connection/schema.json +5 -0
- package/src/infra/app/schema.json +5 -0
- package/src/init/schema.json +35 -0
- package/src/internal/test-matrix/schema.json +21 -0
- package/src/license/schema.json +5 -0
- package/src/preset/schema.json +16 -5
- package/src/py/agent/a2a-connection/schema.json +5 -0
- package/src/py/agent/gateway-connection/schema.json +31 -0
- package/src/py/agent/mcp-connection/schema.json +5 -0
- package/src/py/agent/react-connection/schema.json +5 -0
- package/src/py/agent/schema.json +15 -1
- package/src/py/api/schema.json +5 -0
- package/src/py/dynamodb/agent-connection/schema.json +27 -0
- package/src/py/dynamodb/fast-api-connection/schema.json +23 -0
- package/src/py/dynamodb/mcp-server-connection/schema.json +27 -0
- package/src/py/dynamodb/schema.json +76 -0
- package/src/py/fast-api/react/schema.json +5 -0
- package/src/py/fast-api/schema.json +6 -0
- package/src/py/lambda-function/schema.json +5 -0
- package/src/py/mcp-server/schema.json +6 -0
- package/src/py/project/schema.json +5 -0
- package/src/py/rdb/agent-connection/schema.json +27 -0
- package/src/py/rdb/fast-api-connection/schema.json +23 -0
- package/src/py/rdb/mcp-server-connection/schema.json +27 -0
- package/src/py/rdb/schema.json +78 -0
- package/src/smithy/project/schema.json +28 -1
- package/src/smithy/react-connection/schema.json +5 -0
- package/src/smithy/ts/api/schema.json +6 -0
- package/src/terraform/project/schema.json +5 -0
- package/src/trpc/backend/schema.json +6 -0
- package/src/trpc/react/schema.json +5 -0
- package/src/ts/agent/a2a-connection/schema.json +5 -0
- package/src/ts/agent/gateway-connection/schema.json +31 -0
- package/src/ts/agent/mcp-connection/schema.json +5 -0
- package/src/ts/agent/react-connection/schema.json +5 -0
- package/src/ts/agent/schema.json +14 -0
- package/src/ts/api/schema.json +5 -0
- package/src/ts/astro-docs/schema.json +3 -3
- package/src/ts/dcr-proxy/schema.json +44 -0
- package/src/ts/docs/schema.json +3 -3
- package/src/ts/dynamodb/agent-connection/schema.json +5 -0
- package/src/ts/dynamodb/mcp-server-connection/schema.json +5 -0
- package/src/ts/dynamodb/schema.json +26 -2
- package/src/ts/dynamodb/smithy-connection/schema.json +5 -0
- package/src/ts/dynamodb/trpc-connection/schema.json +5 -0
- package/src/ts/lambda-function/schema.json +5 -0
- package/src/ts/lib/schema.json +5 -0
- package/src/ts/mcp-server/schema.json +6 -0
- package/src/ts/nx-generator/schema.json +5 -0
- package/src/ts/nx-migration/schema.json +63 -0
- package/src/ts/nx-plugin/schema.json +5 -0
- package/src/ts/rdb/agent-connection/schema.json +5 -0
- package/src/ts/rdb/mcp-server-connection/schema.json +5 -0
- package/src/ts/rdb/schema.json +7 -1
- package/src/ts/rdb/smithy-connection/schema.json +5 -0
- package/src/ts/rdb/trpc-connection/schema.json +5 -0
- package/src/ts/react-website/app/schema.json +12 -6
- package/src/ts/react-website/cognito-auth/schema.json +5 -0
- package/src/ts/react-website/runtime-config/schema.json +5 -0
- package/src/ts/website/app/schema.json +11 -6
- package/src/ts/website/auth/schema.json +5 -0
- /package/docs/snippets/connection/{lambda-rdb-ssl-requirements.mdx → ts-lambda-rdb-ssl-requirements.mdx} +0 -0
- /package/docs/snippets/connection/{mcp-server-rdb-ssl-requirements.mdx → ts-mcp-server-rdb-ssl-requirements.mdx} +0 -0
|
@@ -1,23 +1,22 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: DynamoDB
|
|
3
|
-
description: Create a DynamoDB project
|
|
2
|
+
title: TypeScript DynamoDB
|
|
3
|
+
description: Create a TypeScript DynamoDB project
|
|
4
4
|
generator: ts#dynamodb
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
import { FileTree } from '@astrojs/starlight/components';
|
|
7
|
+
import { FileTree, CardGrid } from '@astrojs/starlight/components';
|
|
8
|
+
import Astro from '@astrojs/react';
|
|
9
|
+
import ConnectionCard from '@components/connection-card.astro';
|
|
8
10
|
import Link from '@components/link.astro';
|
|
9
11
|
import RunGenerator from '@components/run-generator.astro';
|
|
10
12
|
import GeneratorParameters from '@components/generator-parameters.astro';
|
|
11
|
-
import Infrastructure from '@components/infrastructure.astro';
|
|
12
|
-
import NxCommands from '@components/nx-commands.astro';
|
|
13
13
|
import Snippet from '@components/snippet.astro';
|
|
14
|
-
import OptionFilter from '@components/option-filter.astro';
|
|
15
14
|
|
|
16
|
-
This generator creates a new TypeScript 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.
|
|
15
|
+
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.
|
|
17
16
|
|
|
18
17
|
## Usage
|
|
19
18
|
|
|
20
|
-
### Generate a DynamoDB Project
|
|
19
|
+
### Generate a TypeScript DynamoDB Project
|
|
21
20
|
|
|
22
21
|
<RunGenerator generator="ts#dynamodb" />
|
|
23
22
|
|
|
@@ -30,65 +29,39 @@ This generator creates a new TypeScript project backed by [Amazon DynamoDB](http
|
|
|
30
29
|
The generator creates the following project structure in the `<directory>/<name>` directory:
|
|
31
30
|
|
|
32
31
|
<FileTree>
|
|
33
|
-
- scripts
|
|
34
|
-
- create-local-table.ts Creates the DynamoDB table in the local DynamoDB Local instance
|
|
35
|
-
- pull-image.ts Pulls the DynamoDB Local image
|
|
36
|
-
- start-container.ts Starts the DynamoDB Local container
|
|
37
32
|
- src
|
|
38
33
|
- index.ts Project entry point and exports
|
|
39
|
-
- constants.ts Local development constants and runtime config key
|
|
40
34
|
- client.ts DynamoDB client singleton and table name resolution
|
|
41
35
|
- entities
|
|
42
36
|
- example.ts Example ElectroDB entity definition
|
|
43
37
|
- index.ts Entity exports
|
|
38
|
+
- config.json Table configuration including GSI definitions and local development settings
|
|
39
|
+
- package.json Project manifest defining the project's package name and dependencies
|
|
44
40
|
- project.json Project configuration and build targets
|
|
45
41
|
</FileTree>
|
|
46
42
|
|
|
43
|
+
The local development scripts are shared across all DynamoDB projects (both TypeScript and Python) and generated once into:
|
|
44
|
+
|
|
45
|
+
<FileTree>
|
|
46
|
+
- packages/common/scripts/src/dynamodb
|
|
47
|
+
- create-local-table.ts Creates the DynamoDB table in the local DynamoDB Local instance
|
|
48
|
+
- pull-image.ts Pulls the DynamoDB Local image
|
|
49
|
+
- start-container.ts Starts the DynamoDB Local container
|
|
50
|
+
</FileTree>
|
|
51
|
+
|
|
47
52
|
### Infrastructure
|
|
48
53
|
|
|
49
|
-
<Snippet name="
|
|
50
|
-
|
|
51
|
-
<Infrastructure>
|
|
52
|
-
<Fragment slot="cdk">
|
|
53
|
-
<FileTree>
|
|
54
|
-
- packages/common/constructs/src
|
|
55
|
-
- app
|
|
56
|
-
- dynamodb
|
|
57
|
-
- \<name>.ts Infrastructure specific to your table
|
|
58
|
-
- core
|
|
59
|
-
- dynamodb.ts Generic DynamoDB table construct
|
|
60
|
-
</FileTree>
|
|
61
|
-
</Fragment>
|
|
62
|
-
<Fragment slot="terraform">
|
|
63
|
-
<FileTree>
|
|
64
|
-
- packages/common/terraform/src
|
|
65
|
-
- app
|
|
66
|
-
- dynamodb
|
|
67
|
-
- \<name>
|
|
68
|
-
- \<name>.tf Module specific to your table
|
|
69
|
-
- core
|
|
70
|
-
- dynamodb
|
|
71
|
-
- dynamodb.tf Generic DynamoDB module
|
|
72
|
-
</FileTree>
|
|
73
|
-
</Fragment>
|
|
74
|
-
</Infrastructure>
|
|
54
|
+
<Snippet name="dynamodb/infrastructure" />
|
|
75
55
|
|
|
76
56
|
## Local Development
|
|
77
57
|
|
|
78
58
|
### Starting Local DynamoDB
|
|
79
59
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
<NxCommands commands={['run <project-name>:serve-local']} />
|
|
83
|
-
|
|
84
|
-
This automatically:
|
|
85
|
-
1. Pulls the DynamoDB Local image (`pull-image` target)
|
|
86
|
-
2. Starts a container
|
|
87
|
-
3. Creates a local table with pre-defined indexes
|
|
60
|
+
<Snippet name="dynamodb/local-dev-start" />
|
|
88
61
|
|
|
89
62
|
### Data Modelling
|
|
90
63
|
|
|
91
|
-
The generated project uses [ElectroDB](https://electrodb.dev/) for type-safe entity modelling on a single DynamoDB table. Add or update entity files under `src/entities/`, using the generated example entity as a starting point.
|
|
64
|
+
The generated project uses [ElectroDB](https://electrodb.dev/) for type-safe entity modelling on a single DynamoDB table, following [DynamoDB's single-table design](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/data-modeling-foundations.html). Add or update entity files under `src/entities/`, using the generated example entity as a starting point.
|
|
92
65
|
|
|
93
66
|
Example entity definition:
|
|
94
67
|
|
|
@@ -146,219 +119,70 @@ For more details, see the [ElectroDB entity documentation](https://electrodb.dev
|
|
|
146
119
|
|
|
147
120
|
The generated `src/client.ts` exports two key utilities:
|
|
148
121
|
|
|
149
|
-
- `getDynamoDBClient()` — returns a cached singleton `DynamoDBClient`. When `
|
|
150
|
-
- `resolveTableName()` — returns the DynamoDB table name. When `
|
|
122
|
+
- `getDynamoDBClient()` — returns a cached singleton `DynamoDBClient`. When `LOCAL_DEV=true`, connects to the local DynamoDB Local instance; otherwise creates an AWS client using the default credential chain.
|
|
123
|
+
- `resolveTableName()` — returns the DynamoDB table name. When `LOCAL_DEV=true`, returns the local table name constant; otherwise fetches the name from AWS AppConfig using the `RUNTIME_CONFIG_APP_ID` environment variable and caches it for subsequent calls.
|
|
151
124
|
|
|
152
125
|
### Stopping Local DynamoDB
|
|
153
126
|
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
:::caution[Windows]
|
|
157
|
-
Due to limitations with signal handling on Windows, the container is not automatically removed when `serve-local` is stopped. You will need to remove it manually:
|
|
158
|
-
|
|
159
|
-
```bash
|
|
160
|
-
<engine> rm -f <scope>-dynamodb
|
|
161
|
-
```
|
|
162
|
-
|
|
163
|
-
Replace `<engine>` with your container engine (`docker` or `finch`) and `<scope>` with your Nx workspace scope (e.g. `proj`).
|
|
164
|
-
:::
|
|
127
|
+
<Snippet name="dynamodb/local-dev-windows" />
|
|
165
128
|
|
|
166
129
|
## Adding/Removing Global Secondary Indexes
|
|
167
130
|
|
|
168
|
-
|
|
131
|
+
GSIs are defined in `config.json` at the project root under the `tableConfig.globalSecondaryIndexes` key. Add an entry for each GSI, following the [single-table design](https://electrodb.dev/en/core-concepts/single-table-relationships/) naming convention for GSI keys:
|
|
169
132
|
|
|
170
|
-
<
|
|
171
|
-
Unlike CDK, changes to `src/gsi.ts` are not automatically reflected in your Terraform module. You must also manually update your Terraform module to add or remove the corresponding GSI definitions before deploying.
|
|
172
|
-
</OptionFilter>
|
|
133
|
+
<Snippet name="dynamodb/gsi-config" parentHeading="Adding/Removing Global Secondary Indexes" />
|
|
173
134
|
|
|
174
135
|
## Connecting to the Table
|
|
175
136
|
|
|
176
137
|
In any TypeScript project, import entity factories from your DynamoDB package and use them directly:
|
|
177
138
|
|
|
178
139
|
```ts
|
|
179
|
-
import { createExampleEntity } from '
|
|
140
|
+
import { createExampleEntity } from '@my-scope/my-table';
|
|
180
141
|
|
|
181
142
|
const entity = await createExampleEntity();
|
|
182
143
|
const result = await entity.query.primary({ id: '123' }).go();
|
|
183
144
|
```
|
|
184
145
|
|
|
185
|
-
|
|
186
|
-
When running in AWS, `resolveTableName()` fetches the table name from AWS AppConfig using the `RUNTIME_CONFIG_APP_ID` environment variable. Projects built with this plugin (tRPC APIs, Smithy APIs, agents, MCP servers) already have this variable configured automatically. For other TypeScript projects, ensure `RUNTIME_CONFIG_APP_ID` is set in the runtime environment with the AppConfig application ID provisioned by your infrastructure. For more information, see the <Link path="guides/runtime-config">Runtime Configuration guide</Link>.
|
|
187
|
-
:::
|
|
188
|
-
|
|
189
|
-
### Connection Generators
|
|
146
|
+
Behind the scenes, `createExampleEntity()` calls `resolveTableName()` to fetch the table name from AWS AppConfig at runtime.
|
|
190
147
|
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
- <Link path="guides/connection/trpc-dynamodb">tRPC API → DynamoDB</Link>
|
|
194
|
-
- <Link path="guides/connection/smithy-dynamodb">Smithy API → DynamoDB</Link>
|
|
195
|
-
- <Link path="guides/connection/ts-agent-dynamodb">TypeScript Agent → DynamoDB</Link>
|
|
196
|
-
- <Link path="guides/connection/ts-mcp-server-dynamodb">MCP Server → DynamoDB</Link>
|
|
148
|
+
<Snippet name="runtime-config-app-id-note" parentHeading="Connecting to the Table" />
|
|
197
149
|
|
|
198
150
|
## Deploying your Table
|
|
199
151
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
- `pk` (partition key) and `sk` (sort key), both `String` type
|
|
238
|
-
- 2 Global Secondary Indexes by default, as defined in `src/gsi.ts`
|
|
239
|
-
- On-demand (`PAY_PER_REQUEST`) billing
|
|
240
|
-
- Customer-managed KMS encryption with automatic key rotation
|
|
241
|
-
- Point-in-time recovery enabled
|
|
242
|
-
- Deletion protection enabled
|
|
243
|
-
- Table name registered in Runtime Config
|
|
244
|
-
</Fragment>
|
|
245
|
-
</Infrastructure>
|
|
246
|
-
|
|
247
|
-
### Granting Access
|
|
248
|
-
|
|
249
|
-
<Snippet name="connection/lambda-dynamodb-access" />
|
|
250
|
-
|
|
251
|
-
### Deletion Protection
|
|
252
|
-
|
|
253
|
-
Deletion protection is enabled by default to prevent accidental table deletion.
|
|
254
|
-
|
|
255
|
-
#### Disable Deletion Protection
|
|
256
|
-
|
|
257
|
-
Disable it for environments where table deletion is expected, such as short-lived development or preview stacks.
|
|
258
|
-
|
|
259
|
-
<Infrastructure>
|
|
260
|
-
<Fragment slot="cdk">
|
|
261
|
-
|
|
262
|
-
```ts title="packages/infra/src/stacks/application-stack.ts"
|
|
263
|
-
import { MyTable } from ':my-scope/common-constructs';
|
|
264
|
-
|
|
265
|
-
const table = new MyTable(this, 'Table', {
|
|
266
|
-
deletionProtection: false,
|
|
267
|
-
});
|
|
268
|
-
```
|
|
269
|
-
</Fragment>
|
|
270
|
-
<Fragment slot="terraform">
|
|
271
|
-
|
|
272
|
-
```hcl title="packages/infra/src/main.tf"
|
|
273
|
-
module "my_table" {
|
|
274
|
-
source = "../../common/terraform/src/app/dynamodb/my-table"
|
|
275
|
-
deletion_protection_enabled = false
|
|
276
|
-
}
|
|
277
|
-
```
|
|
278
|
-
</Fragment>
|
|
279
|
-
</Infrastructure>
|
|
280
|
-
|
|
281
|
-
### Billing Mode
|
|
282
|
-
|
|
283
|
-
The table defaults to on-demand (`PAY_PER_REQUEST`) billing. Switch to provisioned capacity for predictable, high-throughput workloads.
|
|
284
|
-
|
|
285
|
-
<Infrastructure>
|
|
286
|
-
<Fragment slot="cdk">
|
|
287
|
-
|
|
288
|
-
```ts title="packages/infra/src/stacks/application-stack.ts"
|
|
289
|
-
import { BillingMode } from 'aws-cdk-lib/aws-dynamodb';
|
|
290
|
-
import { MyTable } from ':my-scope/common-constructs';
|
|
291
|
-
|
|
292
|
-
const table = new MyTable(this, 'Table', {
|
|
293
|
-
billingMode: BillingMode.PROVISIONED,
|
|
294
|
-
readCapacity: 5,
|
|
295
|
-
writeCapacity: 5,
|
|
296
|
-
});
|
|
297
|
-
```
|
|
298
|
-
</Fragment>
|
|
299
|
-
<Fragment slot="terraform">
|
|
300
|
-
|
|
301
|
-
```hcl title="packages/infra/src/main.tf"
|
|
302
|
-
module "my_table" {
|
|
303
|
-
source = "../../common/terraform/src/app/dynamodb/my-table"
|
|
304
|
-
billing_mode = "PROVISIONED"
|
|
305
|
-
}
|
|
306
|
-
```
|
|
307
|
-
</Fragment>
|
|
308
|
-
</Infrastructure>
|
|
309
|
-
|
|
310
|
-
### Point-in-time Recovery
|
|
311
|
-
|
|
312
|
-
[Point-in-time recovery](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Point-in-time-recovery.html) is enabled by default, allowing you to restore the table to any point in the last 35 days.
|
|
313
|
-
|
|
314
|
-
#### Disable Point-in-time Recovery
|
|
315
|
-
|
|
316
|
-
<Infrastructure>
|
|
317
|
-
<Fragment slot="cdk">
|
|
318
|
-
|
|
319
|
-
```ts title="packages/infra/src/stacks/application-stack.ts"
|
|
320
|
-
import { MyTable } from ':my-scope/common-constructs';
|
|
321
|
-
|
|
322
|
-
const table = new MyTable(this, 'Table', {
|
|
323
|
-
pointInTimeRecoverySpecification: { pointInTimeRecoveryEnabled: false },
|
|
324
|
-
});
|
|
325
|
-
```
|
|
326
|
-
</Fragment>
|
|
327
|
-
<Fragment slot="terraform">
|
|
328
|
-
|
|
329
|
-
```hcl title="packages/infra/src/main.tf"
|
|
330
|
-
module "my_table" {
|
|
331
|
-
source = "../../common/terraform/src/app/dynamodb/my-table"
|
|
332
|
-
point_in_time_recovery_enabled = false
|
|
333
|
-
}
|
|
334
|
-
```
|
|
335
|
-
</Fragment>
|
|
336
|
-
</Infrastructure>
|
|
337
|
-
|
|
338
|
-
### Encryption Key Rotation
|
|
339
|
-
|
|
340
|
-
The KMS key used to encrypt the table has automatic key rotation enabled by default. Disable it if your security policy manages rotation externally.
|
|
341
|
-
|
|
342
|
-
#### Disable Encryption Key Rotation
|
|
343
|
-
|
|
344
|
-
<Infrastructure>
|
|
345
|
-
<Fragment slot="cdk">
|
|
346
|
-
|
|
347
|
-
```ts title="packages/infra/src/stacks/application-stack.ts"
|
|
348
|
-
import { MyTable } from ':my-scope/common-constructs';
|
|
349
|
-
|
|
350
|
-
const table = new MyTable(this, 'Table', {
|
|
351
|
-
enableKeyRotation: false,
|
|
352
|
-
});
|
|
353
|
-
```
|
|
354
|
-
</Fragment>
|
|
355
|
-
<Fragment slot="terraform">
|
|
356
|
-
|
|
357
|
-
```hcl title="packages/infra/src/main.tf"
|
|
358
|
-
module "my_table" {
|
|
359
|
-
source = "../../common/terraform/src/app/dynamodb/my-table"
|
|
360
|
-
enable_key_rotation = false
|
|
361
|
-
}
|
|
362
|
-
```
|
|
363
|
-
</Fragment>
|
|
364
|
-
</Infrastructure>
|
|
152
|
+
<Snippet name="dynamodb/deploying-table" parentHeading="Deploying your Table" />
|
|
153
|
+
|
|
154
|
+
## Connections
|
|
155
|
+
|
|
156
|
+
Use the <Link path="guides/connection">`connection`</Link> generator to integrate this project with others in your workspace. The following connections involve this project:
|
|
157
|
+
|
|
158
|
+
<CardGrid>
|
|
159
|
+
<ConnectionCard
|
|
160
|
+
title="tRPC API to TypeScript DynamoDB"
|
|
161
|
+
description="Connect a tRPC API to a DynamoDB table"
|
|
162
|
+
href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/trpc-dynamodb`}
|
|
163
|
+
source="trpc"
|
|
164
|
+
target="dynamodb"
|
|
165
|
+
/>
|
|
166
|
+
<ConnectionCard
|
|
167
|
+
title="Smithy API to TypeScript DynamoDB"
|
|
168
|
+
description="Connect a Smithy API to a DynamoDB table"
|
|
169
|
+
href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/smithy-dynamodb`}
|
|
170
|
+
source="smithy"
|
|
171
|
+
target="dynamodb"
|
|
172
|
+
/>
|
|
173
|
+
<ConnectionCard
|
|
174
|
+
title="TypeScript Agent to TypeScript DynamoDB"
|
|
175
|
+
description="Connect a TypeScript Agent to a DynamoDB table"
|
|
176
|
+
href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-dynamodb`}
|
|
177
|
+
source="strands"
|
|
178
|
+
sourceBadge="typescript"
|
|
179
|
+
target="dynamodb"
|
|
180
|
+
/>
|
|
181
|
+
<ConnectionCard
|
|
182
|
+
title="MCP Server to TypeScript DynamoDB"
|
|
183
|
+
description="Connect a TypeScript MCP Server to a DynamoDB table"
|
|
184
|
+
href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-mcp-server-dynamodb`}
|
|
185
|
+
source="mcp"
|
|
186
|
+
target="dynamodb"
|
|
187
|
+
/>
|
|
188
|
+
</CardGrid>
|
|
@@ -56,7 +56,7 @@ If the `functionPath` option is provided, the generator will add the handler to
|
|
|
56
56
|
|
|
57
57
|
<Snippet name="shared-constructs" />
|
|
58
58
|
|
|
59
|
-
The generator creates infrastructure as code for deploying your function based on your selected `
|
|
59
|
+
The generator creates infrastructure as code for deploying your function based on your selected `iac`:
|
|
60
60
|
|
|
61
61
|
<Infrastructure>
|
|
62
62
|
<Fragment slot="cdk">
|
|
@@ -4,7 +4,9 @@ description: Generate a TypeScript Model Context Protocol (MCP) server for provi
|
|
|
4
4
|
generator: ts#mcp-server
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
import { FileTree } from '@astrojs/starlight/components';
|
|
7
|
+
import { FileTree, CardGrid } from '@astrojs/starlight/components';
|
|
8
|
+
import Astro from '@astrojs/react';
|
|
9
|
+
import ConnectionCard from '@components/connection-card.astro';
|
|
8
10
|
import RunGenerator from '@components/run-generator.astro';
|
|
9
11
|
import NxCommands from '@components/nx-commands.astro';
|
|
10
12
|
import Link from '@components/link.astro';
|
|
@@ -54,7 +56,6 @@ The generator will add the following files to your existing TypeScript project:
|
|
|
54
56
|
- resources/
|
|
55
57
|
- sample-guidance.ts Sample resource
|
|
56
58
|
- Dockerfile Entry point for hosting your MCP server (excluded when `infra` is set to `None`)
|
|
57
|
-
- package.json Updated with bin entry and MCP dependencies
|
|
58
59
|
- project.json Updated with MCP server serve target
|
|
59
60
|
</FileTree>
|
|
60
61
|
|
|
@@ -78,40 +79,57 @@ If you selected `none` for `infra`, no CDK constructs or Terraform modules are g
|
|
|
78
79
|
|
|
79
80
|
### Adding Tools
|
|
80
81
|
|
|
81
|
-
Tools are functions that the AI assistant can call to perform actions.
|
|
82
|
+
Tools are functions that the AI assistant can call to perform actions. Each tool lives in its own file under `tools/` that exports a `register<Name>Tool` function, which you then call from `server.ts`. For example, add `tools/my-tool.ts`:
|
|
83
|
+
|
|
84
|
+
```typescript title="tools/my-tool.ts"
|
|
85
|
+
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
86
|
+
import { z } from 'zod';
|
|
87
|
+
|
|
88
|
+
export const registerMyTool = (server: McpServer) => {
|
|
89
|
+
server.registerTool("toolName", {
|
|
90
|
+
description: "tool description",
|
|
91
|
+
inputSchema: { param1: z.string(), param2: z.number() } // Input schema using Zod
|
|
92
|
+
},
|
|
93
|
+
async ({ param1, param2 }) => {
|
|
94
|
+
// Tool implementation
|
|
95
|
+
return {
|
|
96
|
+
content: [{ type: "text", text: "Result" }]
|
|
97
|
+
};
|
|
98
|
+
}
|
|
99
|
+
);
|
|
100
|
+
};
|
|
101
|
+
```
|
|
82
102
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
// Tool implementation
|
|
90
|
-
return {
|
|
91
|
-
content: [{ type: "text", text: "Result" }]
|
|
92
|
-
};
|
|
93
|
-
}
|
|
94
|
-
);
|
|
103
|
+
Then register it in `server.ts`:
|
|
104
|
+
|
|
105
|
+
```typescript title="server.ts"
|
|
106
|
+
import { registerMyTool } from './tools/my-tool.js';
|
|
107
|
+
|
|
108
|
+
registerMyTool(server);
|
|
95
109
|
```
|
|
96
110
|
|
|
97
111
|
### Adding Resources
|
|
98
112
|
|
|
99
|
-
Resources provide context to the AI assistant. You can add static resources from files or dynamic resources:
|
|
113
|
+
Resources provide context to the AI assistant. Like tools, each resource lives in its own file under `resources/` that exports a `register<Name>Resource` function called from `server.ts`. You can add static resources from files or dynamic resources:
|
|
100
114
|
|
|
101
|
-
```typescript
|
|
102
|
-
|
|
115
|
+
```typescript title="resources/my-resource.ts"
|
|
116
|
+
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
103
117
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
}));
|
|
118
|
+
export const registerMyResource = (server: McpServer) => {
|
|
119
|
+
const exampleContext = 'some context to return';
|
|
107
120
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
}
|
|
114
|
-
|
|
121
|
+
server.registerResource('resource-name', 'example://resource', {}, async (uri) => ({
|
|
122
|
+
contents: [{ uri: uri.href, text: exampleContext }],
|
|
123
|
+
}));
|
|
124
|
+
|
|
125
|
+
// Dynamic resource
|
|
126
|
+
server.registerResource('dynamic-resource', 'dynamic://resource', {}, async (uri) => {
|
|
127
|
+
const data = await fetchSomeData();
|
|
128
|
+
return {
|
|
129
|
+
contents: [{ uri: uri.href, text: data }],
|
|
130
|
+
};
|
|
131
|
+
});
|
|
132
|
+
};
|
|
115
133
|
```
|
|
116
134
|
|
|
117
135
|
## Configuring with AI Assistants
|
|
@@ -120,14 +138,28 @@ server.registerResource('dynamic-resource', 'dynamic://resource', {}, async (uri
|
|
|
120
138
|
|
|
121
139
|
## Running Your MCP Server
|
|
122
140
|
|
|
141
|
+
### Local Development
|
|
142
|
+
|
|
143
|
+
To run your MCP server (and everything connected to it, such as a local database) locally, use the project's `dev` target:
|
|
144
|
+
|
|
145
|
+
<NxCommands commands={['dev your-project']} />
|
|
146
|
+
|
|
147
|
+
If you have added multiple components to your project (MCP servers, agents, etc.), this starts them all. To run just this MCP server, target its `<your-server-name>-dev` target:
|
|
148
|
+
|
|
149
|
+
<NxCommands commands={['your-server-name-dev your-project']} />
|
|
150
|
+
|
|
123
151
|
### Inspector
|
|
124
152
|
|
|
125
|
-
The generator configures a target named `<your-server-name>-inspect`, which starts the [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
|
|
153
|
+
The generator configures a target named `<your-server-name>-inspect`, which starts your MCP server locally (via the `<your-server-name>-dev` target, including any connected dependencies such as a local database) and launches the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) pre-configured to connect to it over Streamable HTTP transport.
|
|
126
154
|
|
|
127
155
|
<NxCommands commands={['your-server-name-inspect your-project']} />
|
|
128
156
|
|
|
129
157
|
This will start the inspector at `http://localhost:6274`. Get started by clicking on the "Connect" button.
|
|
130
158
|
|
|
159
|
+
:::tip
|
|
160
|
+
To inspect the server using STDIO transport instead, use the `<your-server-name>-inspect-stdio` target, which launches the inspector against a STDIO instance of your server.
|
|
161
|
+
:::
|
|
162
|
+
|
|
131
163
|
### STDIO
|
|
132
164
|
|
|
133
165
|
The easiest way to test and use an MCP server is by using the inspector or configuring it with an AI assistant (as above).
|
|
@@ -163,7 +195,55 @@ The generator configures a `<your-server-name>-docker` target which copies the `
|
|
|
163
195
|
|
|
164
196
|
A `docker` target is also generated which prepares the docker context for all MCP servers if you have multiple defined.
|
|
165
197
|
|
|
198
|
+
### Image Scanning
|
|
199
|
+
|
|
200
|
+
<Snippet name="trivy-image-scan" parentHeading="Image Scanning" />
|
|
201
|
+
|
|
166
202
|
### Observability
|
|
167
203
|
|
|
168
204
|
<Snippet name="mcp/observability" parentHeading="Observability" />
|
|
169
205
|
</OptionFilter>
|
|
206
|
+
|
|
207
|
+
## Connections
|
|
208
|
+
|
|
209
|
+
Use the <Link path="guides/connection">`connection`</Link> generator to integrate this project with others in your workspace. The following connections involve this project:
|
|
210
|
+
|
|
211
|
+
<CardGrid>
|
|
212
|
+
<ConnectionCard
|
|
213
|
+
title="TypeScript Agent to MCP"
|
|
214
|
+
description="Connect a TypeScript Agent to an MCP server"
|
|
215
|
+
href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-mcp`}
|
|
216
|
+
source="strands"
|
|
217
|
+
sourceBadge="typescript"
|
|
218
|
+
target="mcp"
|
|
219
|
+
/>
|
|
220
|
+
<ConnectionCard
|
|
221
|
+
title="Python Agent to MCP"
|
|
222
|
+
description="Connect a Python Agent to an MCP server"
|
|
223
|
+
href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/py-agent-mcp`}
|
|
224
|
+
source="strands"
|
|
225
|
+
sourceBadge="python"
|
|
226
|
+
target="mcp"
|
|
227
|
+
/>
|
|
228
|
+
<ConnectionCard
|
|
229
|
+
title="MCP Server to Relational Database"
|
|
230
|
+
description="Connect a TypeScript MCP Server to an Aurora relational database"
|
|
231
|
+
href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-mcp-server-rdb`}
|
|
232
|
+
source="mcp"
|
|
233
|
+
target="aurora"
|
|
234
|
+
/>
|
|
235
|
+
<ConnectionCard
|
|
236
|
+
title="MCP Server to TypeScript DynamoDB"
|
|
237
|
+
description="Connect a TypeScript MCP Server to a DynamoDB table"
|
|
238
|
+
href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-mcp-server-dynamodb`}
|
|
239
|
+
source="mcp"
|
|
240
|
+
target="dynamodb"
|
|
241
|
+
/>
|
|
242
|
+
<ConnectionCard
|
|
243
|
+
title="AgentCore Gateway to MCP Server"
|
|
244
|
+
description="Aggregate an MCP server behind an AgentCore Gateway"
|
|
245
|
+
href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/agentcore-gateway-mcp`}
|
|
246
|
+
source="agentcore"
|
|
247
|
+
target="mcp"
|
|
248
|
+
/>
|
|
249
|
+
</CardGrid>
|
|
@@ -46,7 +46,7 @@ The generator will create the following project structure:
|
|
|
46
46
|
- generator-guide.ts Tool for detailed generator information
|
|
47
47
|
- utils.ts Utility functions for the MCP server
|
|
48
48
|
- generators.json Nx generator configuration (initially empty)
|
|
49
|
-
- package.json Plugin package configuration
|
|
49
|
+
- package.json Plugin package configuration
|
|
50
50
|
- tsconfig.json TypeScript configuration (CommonJS for Nx compatibility)
|
|
51
51
|
- project.json Nx project configuration with build and package targets
|
|
52
52
|
</FileTree>
|
|
@@ -55,14 +55,14 @@ The generator will create the following project structure:
|
|
|
55
55
|
|
|
56
56
|
### Adding Generators
|
|
57
57
|
|
|
58
|
-
Once you have your plugin project, you can add generators using the <Link path="/guides/
|
|
58
|
+
Once you have your plugin project, you can add generators using the <Link path="/guides/nx-generator">`ts#nx-generator`</Link> generator:
|
|
59
59
|
|
|
60
60
|
<RunGenerator generator="ts#nx-generator" requiredParameters={{ pluginProject: 'your-plugin' }} />
|
|
61
61
|
|
|
62
62
|
This will add a new generator to your plugin.
|
|
63
63
|
|
|
64
64
|
:::tip[Generator Documentation]
|
|
65
|
-
Read the <Link path="/guides/
|
|
65
|
+
Read the <Link path="/guides/nx-generator">`ts#nx-generator` guide</Link> for details about how to implement generators.
|
|
66
66
|
:::
|
|
67
67
|
|
|
68
68
|
Make sure to write a detailed `README.md` for your generator, since this is used by the MCP Server's `generator-guide` tool.
|