@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.
Files changed (195) hide show
  1. package/bin/aws-nx-mcp.js +12317 -10933
  2. package/docs/get_started/building-with-ai.mdx +116 -0
  3. package/docs/get_started/concepts.mdx +67 -0
  4. package/docs/get_started/existing-project.mdx +180 -0
  5. package/docs/get_started/graph-builder.mdx +39 -0
  6. package/docs/get_started/quick-start.mdx +277 -0
  7. package/docs/get_started/tutorials/contribute-generator.mdx +408 -0
  8. package/docs/get_started/tutorials/dungeon-game/1.mdx +1301 -0
  9. package/docs/get_started/tutorials/dungeon-game/2.mdx +237 -0
  10. package/docs/get_started/tutorials/dungeon-game/3.mdx +76 -0
  11. package/docs/get_started/tutorials/dungeon-game/4.mdx +164 -0
  12. package/docs/get_started/tutorials/dungeon-game/overview.mdx +145 -0
  13. package/docs/get_started/tutorials/dungeon-game/wrap-up.mdx +41 -0
  14. package/docs/get_started/tutorials/existing-project.mdx +4 -0
  15. package/docs/get_started/upgrading.mdx +147 -0
  16. package/docs/guides/agentcore-gateway.mdx +490 -0
  17. package/docs/guides/agentcore-harness.mdx +275 -0
  18. package/docs/guides/astro-docs.mdx +8 -0
  19. package/docs/guides/connection/agentcore-gateway-agent.mdx +222 -0
  20. package/docs/guides/connection/agentcore-gateway-gateway.mdx +154 -0
  21. package/docs/guides/connection/agentcore-gateway-mcp.mdx +134 -0
  22. package/docs/guides/connection/py-agent-a2a.mdx +48 -16
  23. package/docs/guides/connection/py-agent-dynamodb.mdx +116 -0
  24. package/docs/guides/connection/py-agent-gateway.mdx +178 -0
  25. package/docs/guides/connection/py-agent-mcp.mdx +43 -14
  26. package/docs/guides/connection/py-agent-rdb.mdx +178 -0
  27. package/docs/guides/connection/py-fast-api-dynamodb.mdx +56 -0
  28. package/docs/guides/connection/py-fast-api-rdb.mdx +184 -0
  29. package/docs/guides/connection/py-mcp-server-dynamodb.mdx +116 -0
  30. package/docs/guides/connection/py-mcp-server-rdb.mdx +187 -0
  31. package/docs/guides/connection/react-agentcore-gateway.mdx +112 -0
  32. package/docs/guides/connection/react-agui.mdx +13 -13
  33. package/docs/guides/connection/react-fastapi.mdx +38 -2
  34. package/docs/guides/connection/react-py-agent.mdx +9 -15
  35. package/docs/guides/connection/react-smithy.mdx +3 -3
  36. package/docs/guides/connection/react-trpc.mdx +1 -1
  37. package/docs/guides/connection/react-ts-agent.mdx +8 -8
  38. package/docs/guides/connection/smithy-dynamodb.mdx +5 -5
  39. package/docs/guides/connection/smithy-rdb.mdx +9 -9
  40. package/docs/guides/connection/trpc-dynamodb.mdx +5 -5
  41. package/docs/guides/connection/trpc-rdb.mdx +6 -6
  42. package/docs/guides/connection/ts-agent-a2a.mdx +14 -11
  43. package/docs/guides/connection/ts-agent-dynamodb.mdx +5 -5
  44. package/docs/guides/connection/ts-agent-gateway.mdx +143 -0
  45. package/docs/guides/connection/ts-agent-mcp.mdx +12 -9
  46. package/docs/guides/connection/ts-agent-rdb.mdx +70 -25
  47. package/docs/guides/connection/ts-mcp-server-dynamodb.mdx +5 -5
  48. package/docs/guides/connection/ts-mcp-server-rdb.mdx +68 -18
  49. package/docs/guides/connection.mdx +122 -5
  50. package/docs/guides/docker-bundling.mdx +69 -12
  51. package/docs/guides/fastapi.mdx +249 -9
  52. package/docs/guides/local-development.mdx +87 -0
  53. package/docs/guides/nx-generator.mdx +4 -3
  54. package/docs/guides/nx-migration.mdx +165 -0
  55. package/docs/guides/py-agent.mdx +264 -49
  56. package/docs/guides/py-dynamodb.mdx +476 -0
  57. package/docs/guides/py-mcp-server.mdx +61 -2
  58. package/docs/guides/py-rdb.mdx +265 -0
  59. package/docs/guides/python-lambda-function.mdx +1 -1
  60. package/docs/guides/react-website-auth.mdx +65 -4
  61. package/docs/guides/react-website.mdx +149 -30
  62. package/docs/guides/runtime-config.mdx +1 -1
  63. package/docs/guides/security.mdx +75 -0
  64. package/docs/guides/smithy-project.mdx +167 -0
  65. package/docs/guides/terraform-project.mdx +2 -2
  66. package/docs/guides/trpc.mdx +53 -16
  67. package/docs/guides/ts-agent.mdx +183 -10
  68. package/docs/guides/ts-dcr-proxy.mdx +569 -0
  69. package/docs/guides/ts-dynamodb.mdx +66 -242
  70. package/docs/guides/ts-lambda-function.mdx +1 -1
  71. package/docs/guides/ts-mcp-server.mdx +109 -29
  72. package/docs/guides/ts-nx-plugin.mdx +3 -3
  73. package/docs/guides/ts-rdb.mdx +113 -467
  74. package/docs/guides/ts-smithy-api.mdx +258 -18
  75. package/docs/guides/typescript-infrastructure.mdx +46 -24
  76. package/docs/guides/typescript-project.mdx +134 -27
  77. package/docs/guides/workspace.mdx +10 -3
  78. package/docs/snippets/agent/architecture.mdx +1 -1
  79. package/docs/snippets/agent/bedrock-deployment.mdx +9 -5
  80. package/docs/snippets/agent/runtime-arn.mdx +23 -2
  81. package/docs/snippets/agent/securing-your-agent.mdx +39 -0
  82. package/docs/snippets/api/access-logging.mdx +33 -0
  83. package/docs/snippets/api/cors-configuration-cdk-note.mdx +1 -1
  84. package/docs/snippets/api/cors-configuration-terraform-note.mdx +1 -1
  85. package/docs/snippets/api/type-safe-api-integrations.mdx +33 -2
  86. package/docs/snippets/api/waf-configuration.mdx +3 -3
  87. package/docs/snippets/connection/a2a-infrastructure.mdx +1 -1
  88. package/docs/snippets/connection/dynamodb-local-development.mdx +2 -2
  89. package/docs/snippets/connection/lambda-dynamodb-access.mdx +1 -1
  90. package/docs/snippets/connection/py-dynamodb-local-development.mdx +7 -0
  91. package/docs/snippets/connection/py-lambda-rdb-ssl-requirements.mdx +7 -0
  92. package/docs/snippets/connection/rdb-api-infrastructure.mdx +51 -19
  93. package/docs/snippets/dynamodb/deploying-table.mdx +166 -0
  94. package/docs/snippets/dynamodb/gsi-config.mdx +38 -0
  95. package/docs/snippets/dynamodb/infrastructure.mdx +33 -0
  96. package/docs/snippets/dynamodb/local-dev-start.mdx +13 -0
  97. package/docs/snippets/dynamodb/local-dev-windows.mdx +15 -0
  98. package/docs/snippets/lambda-function/deploying-your-function.mdx +3 -3
  99. package/docs/snippets/mcp/architecture.mdx +1 -1
  100. package/docs/snippets/mcp/bedrock-deployment.mdx +9 -5
  101. package/docs/snippets/mcp/config.mdx +3 -2
  102. package/docs/snippets/pdk-migration/example/01-migrate-api.mdx +7 -5
  103. package/docs/snippets/pdk-migration/example/02-migrate-website.mdx +29 -10
  104. package/docs/snippets/pdk-migration/example/03-migrate-infra.mdx +4 -4
  105. package/docs/snippets/pdk-migration/faq/type-safe-api.mdx +5 -111
  106. package/docs/snippets/prerequisites.mdx +1 -4
  107. package/docs/snippets/rdb/architecture.mdx +38 -0
  108. package/docs/snippets/rdb/cluster-instances.mdx +31 -0
  109. package/docs/snippets/rdb/deletion-protection.mdx +34 -0
  110. package/docs/snippets/rdb/deploying.mdx +187 -0
  111. package/docs/snippets/rdb/encryption-key-rotation.mdx +30 -0
  112. package/docs/snippets/rdb/engine-version.mdx +63 -0
  113. package/docs/snippets/rdb/infrastructure.mdx +35 -0
  114. package/docs/snippets/rdb/logging-mysql.mdx +5 -0
  115. package/docs/snippets/rdb/logging-postgres.mdx +5 -0
  116. package/docs/snippets/rdb/performance-insights.mdx +34 -0
  117. package/docs/snippets/rdb/rds-proxy.mdx +50 -0
  118. package/docs/snippets/rdb/removal-policy.mdx +57 -0
  119. package/docs/snippets/rdb/serverless-capacity.mdx +32 -0
  120. package/docs/snippets/recommended-prerequisites.mdx +10 -0
  121. package/docs/snippets/required-prerequisites.mdx +1 -4
  122. package/docs/snippets/runtime-config-app-id-note.mdx +8 -0
  123. package/docs/snippets/shared-constructs.mdx +1 -1
  124. package/docs/snippets/trivy-image-scan.mdx +37 -0
  125. package/generators.json +152 -10
  126. package/package.json +1 -1
  127. package/src/agentcore-gateway/agent-connection/schema.json +31 -0
  128. package/src/agentcore-gateway/gateway-connection/schema.json +31 -0
  129. package/src/agentcore-gateway/mcp-connection/schema.json +31 -0
  130. package/src/agentcore-gateway/react-connection/schema.json +31 -0
  131. package/src/agentcore-gateway/schema.json +72 -0
  132. package/src/agentcore-harness/schema.json +53 -0
  133. package/src/connection/schema.json +5 -0
  134. package/src/infra/app/schema.json +5 -0
  135. package/src/init/schema.json +35 -0
  136. package/src/internal/test-matrix/schema.json +21 -0
  137. package/src/license/schema.json +5 -0
  138. package/src/preset/schema.json +16 -5
  139. package/src/py/agent/a2a-connection/schema.json +5 -0
  140. package/src/py/agent/gateway-connection/schema.json +31 -0
  141. package/src/py/agent/mcp-connection/schema.json +5 -0
  142. package/src/py/agent/react-connection/schema.json +5 -0
  143. package/src/py/agent/schema.json +15 -1
  144. package/src/py/api/schema.json +5 -0
  145. package/src/py/dynamodb/agent-connection/schema.json +27 -0
  146. package/src/py/dynamodb/fast-api-connection/schema.json +23 -0
  147. package/src/py/dynamodb/mcp-server-connection/schema.json +27 -0
  148. package/src/py/dynamodb/schema.json +76 -0
  149. package/src/py/fast-api/react/schema.json +5 -0
  150. package/src/py/fast-api/schema.json +6 -0
  151. package/src/py/lambda-function/schema.json +5 -0
  152. package/src/py/mcp-server/schema.json +6 -0
  153. package/src/py/project/schema.json +5 -0
  154. package/src/py/rdb/agent-connection/schema.json +27 -0
  155. package/src/py/rdb/fast-api-connection/schema.json +23 -0
  156. package/src/py/rdb/mcp-server-connection/schema.json +27 -0
  157. package/src/py/rdb/schema.json +78 -0
  158. package/src/smithy/project/schema.json +28 -1
  159. package/src/smithy/react-connection/schema.json +5 -0
  160. package/src/smithy/ts/api/schema.json +6 -0
  161. package/src/terraform/project/schema.json +5 -0
  162. package/src/trpc/backend/schema.json +6 -0
  163. package/src/trpc/react/schema.json +5 -0
  164. package/src/ts/agent/a2a-connection/schema.json +5 -0
  165. package/src/ts/agent/gateway-connection/schema.json +31 -0
  166. package/src/ts/agent/mcp-connection/schema.json +5 -0
  167. package/src/ts/agent/react-connection/schema.json +5 -0
  168. package/src/ts/agent/schema.json +14 -0
  169. package/src/ts/api/schema.json +5 -0
  170. package/src/ts/astro-docs/schema.json +3 -3
  171. package/src/ts/dcr-proxy/schema.json +44 -0
  172. package/src/ts/docs/schema.json +3 -3
  173. package/src/ts/dynamodb/agent-connection/schema.json +5 -0
  174. package/src/ts/dynamodb/mcp-server-connection/schema.json +5 -0
  175. package/src/ts/dynamodb/schema.json +26 -2
  176. package/src/ts/dynamodb/smithy-connection/schema.json +5 -0
  177. package/src/ts/dynamodb/trpc-connection/schema.json +5 -0
  178. package/src/ts/lambda-function/schema.json +5 -0
  179. package/src/ts/lib/schema.json +5 -0
  180. package/src/ts/mcp-server/schema.json +6 -0
  181. package/src/ts/nx-generator/schema.json +5 -0
  182. package/src/ts/nx-migration/schema.json +63 -0
  183. package/src/ts/nx-plugin/schema.json +5 -0
  184. package/src/ts/rdb/agent-connection/schema.json +5 -0
  185. package/src/ts/rdb/mcp-server-connection/schema.json +5 -0
  186. package/src/ts/rdb/schema.json +7 -1
  187. package/src/ts/rdb/smithy-connection/schema.json +5 -0
  188. package/src/ts/rdb/trpc-connection/schema.json +5 -0
  189. package/src/ts/react-website/app/schema.json +12 -6
  190. package/src/ts/react-website/cognito-auth/schema.json +5 -0
  191. package/src/ts/react-website/runtime-config/schema.json +5 -0
  192. package/src/ts/website/app/schema.json +11 -6
  193. package/src/ts/website/auth/schema.json +5 -0
  194. /package/docs/snippets/connection/{lambda-rdb-ssl-requirements.mdx → ts-lambda-rdb-ssl-requirements.mdx} +0 -0
  195. /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="shared-constructs" />
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
- The generator configures a `serve-local` target that starts a [DynamoDB Local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html) instance and creates the table:
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 `SERVE_LOCAL=true`, connects to the local DynamoDB Local instance; otherwise creates an AWS client using the default credential chain.
150
- - `resolveTableName()` — returns the DynamoDB table name. When `SERVE_LOCAL=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.
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
- Stopping `serve-local` (e.g. with `Ctrl+C`) automatically removes the DynamoDB Local container, but preserves the named volume so your data persists across restarts.
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
- Start by updating `GLOBAL_SECONDARY_INDEXES` in `src/gsi.ts` — this is the source of truth for your GSI definitions, and on the next `serve-local` run the script will automatically add or remove indexes on the local table to reflect the new list. When using CDK, these changes are also automatically reflected in your AWS table on the next deployment.
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
- <OptionFilter when={{ iac: 'terraform' }}>
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 ':my-scope/my-table';
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
- :::note[Runtime config]
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
- For specific project types, use the `connection` generator to automatically wire up local development dependencies so DynamoDB Local starts automatically alongside your project:
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
- The DynamoDB generator creates CDK or Terraform infrastructure based on your selected `iac`.
201
-
202
- <Infrastructure>
203
- <Fragment slot="cdk">
204
- The CDK construct is created in `common/constructs`. Example usage:
205
-
206
- ```ts title="packages/infra/src/stacks/application-stack.ts"
207
- import { MyTable } from ':my-scope/common-constructs';
208
-
209
- export class ApplicationStack extends Stack {
210
- constructor(scope: Construct, id: string, props?: StackProps) {
211
- super(scope, id, props);
212
-
213
- const table = new MyTable(this, 'Table');
214
- }
215
- }
216
- ```
217
-
218
- This provisions a DynamoDB table with:
219
- - `pk` (partition key) and `sk` (sort key), both `String` type
220
- - 2 Global Secondary Indexes by default, as defined in `src/gsi.ts`
221
- - On-demand (`PAY_PER_REQUEST`) billing
222
- - Customer-managed KMS encryption with automatic key rotation
223
- - Point-in-time recovery enabled
224
- - Deletion protection enabled
225
- - Table name registered in Runtime Config under the `dynamodb` namespace in AWS AppConfig
226
- </Fragment>
227
- <Fragment slot="terraform">
228
- The Terraform module is created in `common/terraform`. Example usage:
229
-
230
- ```hcl title="packages/infra/src/main.tf"
231
- module "my_table" {
232
- source = "../../common/terraform/src/app/dynamodb/my-table"
233
- }
234
- ```
235
-
236
- This provisions a DynamoDB table with:
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 `iacProvider`:
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. You can add new tools in the `server.ts` file:
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
- ```typescript
84
- server.registerTool("toolName", {
85
- description: "tool description",
86
- inputSchema: { param1: z.string(), param2: z.number() } // Input schema using Zod
87
- },
88
- async ({ param1, param2 }) => {
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
- const exampleContext = 'some context to return';
115
+ ```typescript title="resources/my-resource.ts"
116
+ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
103
117
 
104
- server.registerResource('resource-name', 'example://resource', {}, async (uri) => ({
105
- contents: [{ uri: uri.href, text: exampleContext }],
106
- }));
118
+ export const registerMyResource = (server: McpServer) => {
119
+ const exampleContext = 'some context to return';
107
120
 
108
- // Dynamic resource
109
- server.registerResource('dynamic-resource', 'dynamic://resource', {}, async (uri) => {
110
- const data = await fetchSomeData();
111
- return {
112
- contents: [{ uri: uri.href, text: data }],
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) with the configuration to connect to your MCP server using STDIO transport.
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 with MCP server binary
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/ts-nx-generator">`ts#nx-generator`</Link> generator:
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/ts-nx-generator">`ts#nx-generator` guide</Link> for details about how to implement generators.
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.