@aws/nx-plugin-mcp 1.0.0-rc.0 → 1.0.0-rc.10
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 +3556 -2476
- package/docs/guides/connection/py-agent-a2a.mdx +1 -1
- package/docs/guides/connection/py-agent-mcp.mdx +1 -1
- package/docs/guides/connection/react-agui.mdx +1 -1
- package/docs/guides/connection/react-py-agent.mdx +1 -1
- package/docs/guides/connection/react-smithy.mdx +1 -1
- package/docs/guides/connection/react-trpc.mdx +2 -2
- package/docs/guides/connection/react-ts-agent.mdx +1 -1
- package/docs/guides/connection/smithy-dynamodb.mdx +68 -0
- package/docs/guides/connection/smithy-rdb.mdx +1 -1
- package/docs/guides/connection/trpc-dynamodb.mdx +62 -0
- package/docs/guides/connection/trpc-rdb.mdx +1 -1
- package/docs/guides/connection/ts-agent-a2a.mdx +1 -1
- package/docs/guides/connection/ts-agent-dynamodb.mdx +128 -0
- package/docs/guides/connection/ts-agent-mcp.mdx +1 -1
- package/docs/guides/connection/ts-mcp-server-dynamodb.mdx +125 -0
- package/docs/guides/connection.mdx +29 -0
- package/docs/guides/docker-bundling.mdx +1 -1
- package/docs/guides/fastapi.mdx +11 -11
- package/docs/guides/license.mdx +264 -109
- package/docs/guides/nx-generator.mdx +4 -0
- package/docs/guides/py-agent.mdx +18 -18
- package/docs/guides/py-mcp-server.mdx +10 -6
- package/docs/guides/python-lambda-function.mdx +4 -4
- package/docs/guides/react-website-auth.mdx +15 -0
- package/docs/guides/react-website.mdx +12 -6
- package/docs/guides/trpc.mdx +19 -18
- package/docs/guides/ts-agent.mdx +18 -18
- package/docs/guides/ts-dynamodb.mdx +364 -0
- package/docs/guides/ts-lambda-function.mdx +4 -4
- package/docs/guides/ts-mcp-server.mdx +10 -6
- package/docs/guides/ts-rdb.mdx +53 -9
- package/docs/guides/ts-smithy-api.mdx +9 -8
- package/docs/guides/typescript-project.mdx +5 -10
- package/docs/guides/workspace.mdx +9 -3
- package/docs/snippets/agent/architecture.mdx +4 -4
- package/docs/snippets/agent/bedrock-deployment.mdx +1 -1
- package/docs/snippets/api/api-architecture.mdx +2 -2
- package/docs/snippets/api/type-safe-api-integrations.mdx +2 -2
- package/docs/snippets/connection/dynamodb-local-development.mdx +7 -0
- package/docs/snippets/connection/lambda-dynamodb-access.mdx +80 -0
- package/docs/snippets/lambda-function/deploying-your-function.mdx +2 -2
- package/docs/snippets/mcp/architecture.mdx +4 -4
- package/docs/snippets/mcp/bedrock-deployment.mdx +1 -1
- package/docs/snippets/mcp/config.mdx +1 -1
- package/docs/snippets/required-prerequisites.mdx +1 -1
- package/generators.json +44 -5
- package/package.json +1 -1
- package/src/infra/app/schema.json +1 -1
- package/src/license/schema.json +6 -0
- package/src/preset/schema.json +9 -4
- package/src/py/agent/schema.json +18 -18
- package/src/py/api/schema.json +15 -15
- package/src/py/fast-api/schema.json +15 -15
- package/src/py/lambda-function/schema.json +15 -7
- package/src/py/mcp-server/schema.json +15 -15
- package/src/py/project/schema.json +2 -2
- package/src/smithy/ts/api/schema.json +15 -15
- package/src/trpc/backend/schema.json +15 -15
- package/src/ts/agent/schema.json +18 -18
- package/src/ts/api/schema.json +15 -15
- package/src/ts/dynamodb/agent-connection/schema.json +22 -0
- package/src/ts/dynamodb/mcp-server-connection/schema.json +22 -0
- package/src/ts/dynamodb/schema.json +52 -0
- package/src/ts/dynamodb/smithy-connection/schema.json +18 -0
- package/src/ts/dynamodb/trpc-connection/schema.json +18 -0
- package/src/ts/lambda-function/schema.json +15 -7
- package/src/ts/mcp-server/schema.json +15 -15
- package/src/ts/rdb/schema.json +13 -13
- package/src/ts/react-website/app/schema.json +13 -13
- package/src/ts/react-website/cognito-auth/schema.json +4 -4
- package/src/ts/website/app/schema.json +21 -13
- package/src/ts/website/auth/schema.json +4 -4
|
@@ -24,7 +24,7 @@ Before using this generator, ensure you have:
|
|
|
24
24
|
|
|
25
25
|
1. A Python project with a <Link path="guides/py-agent">Strands Agent</Link> component (any protocol)
|
|
26
26
|
2. A project with an Agent component generated with `--protocol=A2A` and `--auth=IAM` (either <Link path="guides/ts-agent">`ts#agent`</Link> or <Link path="guides/py-agent">`py#agent`</Link>)
|
|
27
|
-
3. Both components created with `
|
|
27
|
+
3. Both components created with `infra: agentcore`
|
|
28
28
|
|
|
29
29
|
## Usage
|
|
30
30
|
|
|
@@ -24,7 +24,7 @@ Before using this generator, ensure you have:
|
|
|
24
24
|
|
|
25
25
|
1. A Python project with a <Link path="guides/py-agent">Strands Agent</Link> component
|
|
26
26
|
2. A project with an MCP server component (either <Link path="guides/ts-mcp-server">`ts#mcp-server`</Link> or <Link path="guides/py-mcp-server">`py#mcp-server`</Link>)
|
|
27
|
-
3. Both components created with `
|
|
27
|
+
3. Both components created with `infra: agentcore`
|
|
28
28
|
|
|
29
29
|
## Usage
|
|
30
30
|
|
|
@@ -21,7 +21,7 @@ The `connection` generator provides a way to quickly integrate your React websit
|
|
|
21
21
|
Before using this generator, ensure your React application has:
|
|
22
22
|
|
|
23
23
|
1. A `main.tsx` file that renders your application
|
|
24
|
-
2. A working Smithy TypeScript API backend (generated using the <Link path="/guides/ts-smithy-api">`ts#
|
|
24
|
+
2. A working Smithy TypeScript API backend (generated using the <Link path="/guides/ts-smithy-api">`ts#api` generator</Link> with `--framework=smithy`)
|
|
25
25
|
3. Cognito Auth added via the <Link path="/guides/react-website-auth">`ts#website#auth` generator</Link> if connecting an API which uses Cognito or IAM auth
|
|
26
26
|
|
|
27
27
|
<details>
|
|
@@ -170,12 +170,12 @@ function MyComponent() {
|
|
|
170
170
|
### Subscriptions (Streaming)
|
|
171
171
|
|
|
172
172
|
:::caution[Subscriptions Compute Type]
|
|
173
|
-
Subscriptions are only supported when the tRPC API uses `
|
|
173
|
+
Subscriptions are only supported when the tRPC API uses `rest-lambda` (REST API) as the compute type. API Gateway HTTP APIs do not support response streaming.
|
|
174
174
|
:::
|
|
175
175
|
|
|
176
176
|
When connecting to a REST API tRPC backend, the generated client is automatically configured with a `splitLink` that routes subscription operations through `httpSubscriptionLink` (using SSE) and regular queries/mutations through `httpLink`. This means subscriptions work out of the box with no additional configuration.
|
|
177
177
|
|
|
178
|
-
For information on how to define subscription procedures in your backend, see the <Link path="guides/trpc"
|
|
178
|
+
For information on how to define subscription procedures in your backend, see the <Link path="guides/trpc">tRPC API generator guide</Link>.
|
|
179
179
|
|
|
180
180
|
#### Using the useSubscription Hook
|
|
181
181
|
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Smithy API to DynamoDB
|
|
3
|
+
description: Connect a Smithy API to a DynamoDB table
|
|
4
|
+
when:
|
|
5
|
+
sourceType: smithy
|
|
6
|
+
targetType: ts#dynamodb
|
|
7
|
+
---
|
|
8
|
+
import { FileTree } from '@astrojs/starlight/components';
|
|
9
|
+
import Link from '@components/link.astro';
|
|
10
|
+
import RunGenerator from '@components/run-generator.astro';
|
|
11
|
+
import GeneratorParameters from '@components/generator-parameters.astro';
|
|
12
|
+
import NxCommands from '@components/nx-commands.astro';
|
|
13
|
+
import Snippet from '@components/snippet.astro';
|
|
14
|
+
|
|
15
|
+
The `connection` generator wires a <Link path="guides/ts-smithy-api">Smithy API</Link> to a <Link path="guides/ts-dynamodb">DynamoDB</Link> project, configuring local development so both start together automatically.
|
|
16
|
+
|
|
17
|
+
## Prerequisites
|
|
18
|
+
|
|
19
|
+
Before using this generator, ensure you have:
|
|
20
|
+
|
|
21
|
+
1. A <Link path="guides/ts-smithy-api">Smithy TypeScript API</Link> project (generated with `ts#api` using `--framework=smithy`)
|
|
22
|
+
2. A <Link path="guides/ts-dynamodb">`ts#dynamodb`</Link> project
|
|
23
|
+
|
|
24
|
+
## Usage
|
|
25
|
+
|
|
26
|
+
### Run the Generator
|
|
27
|
+
|
|
28
|
+
<RunGenerator generator="connection" />
|
|
29
|
+
|
|
30
|
+
Select your Smithy API backend project as the source and your DynamoDB project as the target.
|
|
31
|
+
|
|
32
|
+
### Options
|
|
33
|
+
|
|
34
|
+
<GeneratorParameters generator="connection" />
|
|
35
|
+
|
|
36
|
+
## Generator Output
|
|
37
|
+
|
|
38
|
+
The generator updates your Smithy API's `project.json` to add a dependency from its `serve-local` target to the DynamoDB project's `serve-local` target. No source files are modified.
|
|
39
|
+
|
|
40
|
+
## Using DynamoDB in Operations
|
|
41
|
+
|
|
42
|
+
Import entity factories from the DynamoDB package and use them inside your operation implementations:
|
|
43
|
+
|
|
44
|
+
```ts title="packages/api/src/operations/list-examples.ts"
|
|
45
|
+
import { createExampleEntity } from ':my-scope/my-table';
|
|
46
|
+
import {
|
|
47
|
+
ListExamplesOperationInput,
|
|
48
|
+
ListExamplesOperationOutput,
|
|
49
|
+
} from '../generated/ssdk/index.js';
|
|
50
|
+
import { ServiceContext } from '../context.js';
|
|
51
|
+
|
|
52
|
+
export const listExamples = async (
|
|
53
|
+
_input: ListExamplesOperationInput,
|
|
54
|
+
_ctx: ServiceContext,
|
|
55
|
+
): Promise<ListExamplesOperationOutput> => {
|
|
56
|
+
const entity = await createExampleEntity();
|
|
57
|
+
const result = await entity.scan.go();
|
|
58
|
+
return { items: result.data };
|
|
59
|
+
};
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Infrastructure
|
|
63
|
+
|
|
64
|
+
<Snippet name="connection/lambda-dynamodb-access" />
|
|
65
|
+
|
|
66
|
+
## Local Development
|
|
67
|
+
|
|
68
|
+
<Snippet name="connection/dynamodb-local-development" />
|
|
@@ -18,7 +18,7 @@ The `connection` generator wires a <Link path="guides/ts-smithy-api">Smithy API<
|
|
|
18
18
|
|
|
19
19
|
Before using this generator, ensure you have:
|
|
20
20
|
|
|
21
|
-
1. A <Link path="guides/ts-smithy-api"
|
|
21
|
+
1. A <Link path="guides/ts-smithy-api">Smithy TypeScript API</Link> project (generated with `ts#api` using `--framework=smithy`)
|
|
22
22
|
2. A <Link path="guides/ts-rdb">`ts#rdb`</Link> project
|
|
23
23
|
|
|
24
24
|
## Usage
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: tRPC API to DynamoDB
|
|
3
|
+
description: Connect a tRPC API to a DynamoDB table
|
|
4
|
+
when:
|
|
5
|
+
sourceType: ts#trpc-api
|
|
6
|
+
targetType: ts#dynamodb
|
|
7
|
+
---
|
|
8
|
+
import { FileTree } from '@astrojs/starlight/components';
|
|
9
|
+
import Link from '@components/link.astro';
|
|
10
|
+
import RunGenerator from '@components/run-generator.astro';
|
|
11
|
+
import GeneratorParameters from '@components/generator-parameters.astro';
|
|
12
|
+
import NxCommands from '@components/nx-commands.astro';
|
|
13
|
+
import Snippet from '@components/snippet.astro';
|
|
14
|
+
|
|
15
|
+
The `connection` generator wires a <Link path="guides/trpc">tRPC API</Link> to a <Link path="guides/ts-dynamodb">DynamoDB</Link> project, configuring local development so both start together automatically.
|
|
16
|
+
|
|
17
|
+
## Prerequisites
|
|
18
|
+
|
|
19
|
+
Before using this generator, ensure you have:
|
|
20
|
+
|
|
21
|
+
1. A <Link path="guides/trpc">tRPC API</Link> project (generated with `ts#api`)
|
|
22
|
+
2. A <Link path="guides/ts-dynamodb">`ts#dynamodb`</Link> project
|
|
23
|
+
|
|
24
|
+
## Usage
|
|
25
|
+
|
|
26
|
+
### Run the Generator
|
|
27
|
+
|
|
28
|
+
<RunGenerator generator="connection" />
|
|
29
|
+
|
|
30
|
+
Select your tRPC API project as the source and your DynamoDB project as the target.
|
|
31
|
+
|
|
32
|
+
### Options
|
|
33
|
+
|
|
34
|
+
<GeneratorParameters generator="connection" />
|
|
35
|
+
|
|
36
|
+
## Generator Output
|
|
37
|
+
|
|
38
|
+
The generator updates your tRPC API's `project.json` to add a dependency from its `serve-local` target to the DynamoDB project's `serve-local` target. No source files are modified.
|
|
39
|
+
|
|
40
|
+
## Using DynamoDB in Procedures
|
|
41
|
+
|
|
42
|
+
Import entity factories from the DynamoDB package and use them inside your tRPC procedures:
|
|
43
|
+
|
|
44
|
+
```ts title="packages/api/src/procedures/example.ts"
|
|
45
|
+
import { createExampleEntity } from ':my-scope/my-table';
|
|
46
|
+
import { publicProcedure } from '../init.js';
|
|
47
|
+
|
|
48
|
+
export const listExamples = publicProcedure
|
|
49
|
+
.query(async () => {
|
|
50
|
+
const entity = await createExampleEntity();
|
|
51
|
+
const result = await entity.scan.go();
|
|
52
|
+
return result.data;
|
|
53
|
+
});
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Infrastructure
|
|
57
|
+
|
|
58
|
+
<Snippet name="connection/lambda-dynamodb-access" />
|
|
59
|
+
|
|
60
|
+
## Local Development
|
|
61
|
+
|
|
62
|
+
<Snippet name="connection/dynamodb-local-development" />
|
|
@@ -18,7 +18,7 @@ The `connection` generator wires a <Link path="guides/trpc">tRPC API</Link> to a
|
|
|
18
18
|
|
|
19
19
|
Before using this generator, ensure you have:
|
|
20
20
|
|
|
21
|
-
1. A <Link path="guides/trpc"
|
|
21
|
+
1. A <Link path="guides/trpc">tRPC API</Link> project (generated with `ts#api`)
|
|
22
22
|
2. A <Link path="guides/ts-rdb">`ts#rdb`</Link> project
|
|
23
23
|
|
|
24
24
|
## Usage
|
|
@@ -24,7 +24,7 @@ Before using this generator, ensure you have:
|
|
|
24
24
|
|
|
25
25
|
1. A TypeScript project with a <Link path="guides/ts-agent">Strands Agent</Link> component (any protocol)
|
|
26
26
|
2. A project with an Agent component generated with `--protocol=A2A` and `--auth=IAM` (either <Link path="guides/ts-agent">`ts#agent`</Link> or <Link path="guides/py-agent">`py#agent`</Link>)
|
|
27
|
-
3. Both components created with `
|
|
27
|
+
3. Both components created with `infra: agentcore`
|
|
28
28
|
|
|
29
29
|
## Usage
|
|
30
30
|
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: TypeScript Agent to DynamoDB
|
|
3
|
+
description: Connect a TypeScript Agent to a DynamoDB table
|
|
4
|
+
when:
|
|
5
|
+
sourceType: ts#agent
|
|
6
|
+
targetType: ts#dynamodb
|
|
7
|
+
---
|
|
8
|
+
import Link from '@components/link.astro';
|
|
9
|
+
import RunGenerator from '@components/run-generator.astro';
|
|
10
|
+
import GeneratorParameters from '@components/generator-parameters.astro';
|
|
11
|
+
import NxCommands from '@components/nx-commands.astro';
|
|
12
|
+
import Infrastructure from '@components/infrastructure.astro';
|
|
13
|
+
import Snippet from '@components/snippet.astro';
|
|
14
|
+
|
|
15
|
+
The `connection` generator wires a <Link path="guides/ts-agent">TypeScript Agent</Link> to a <Link path="guides/ts-dynamodb">DynamoDB</Link> project, configuring local development so both start together automatically.
|
|
16
|
+
|
|
17
|
+
## Prerequisites
|
|
18
|
+
|
|
19
|
+
Before using this generator, ensure you have:
|
|
20
|
+
|
|
21
|
+
1. A <Link path="guides/ts-agent">`ts#agent`</Link> project
|
|
22
|
+
2. A <Link path="guides/ts-dynamodb">`ts#dynamodb`</Link> project
|
|
23
|
+
|
|
24
|
+
## Usage
|
|
25
|
+
|
|
26
|
+
### Run the Generator
|
|
27
|
+
|
|
28
|
+
<RunGenerator generator="connection" />
|
|
29
|
+
|
|
30
|
+
Select your Agent project as the source and your DynamoDB project as the target. If the project contains multiple agent components, specify `sourceComponent` to disambiguate.
|
|
31
|
+
|
|
32
|
+
### Options
|
|
33
|
+
|
|
34
|
+
<GeneratorParameters generator="connection" />
|
|
35
|
+
|
|
36
|
+
## Generator Output
|
|
37
|
+
|
|
38
|
+
The generator updates the agent's `<agent-name>-serve-local` target in `project.json` to depend on the DynamoDB project's `serve-local` target. No source files are modified.
|
|
39
|
+
|
|
40
|
+
## Using DynamoDB in Agents
|
|
41
|
+
|
|
42
|
+
Import entity factories from the DynamoDB package and use them inside your agent definition:
|
|
43
|
+
|
|
44
|
+
```ts title="packages/my-service/src/my-agent/agent.ts"
|
|
45
|
+
import { createExampleEntity } from ':my-scope/my-table';
|
|
46
|
+
|
|
47
|
+
export const getAgent = async () => {
|
|
48
|
+
// ...
|
|
49
|
+
return new Agent({
|
|
50
|
+
tools: [
|
|
51
|
+
tool({
|
|
52
|
+
name: 'list_examples',
|
|
53
|
+
description: 'List all example items',
|
|
54
|
+
func: async () => {
|
|
55
|
+
const entity = await createExampleEntity();
|
|
56
|
+
const result = await entity.scan.go();
|
|
57
|
+
return result.data;
|
|
58
|
+
},
|
|
59
|
+
}),
|
|
60
|
+
],
|
|
61
|
+
});
|
|
62
|
+
};
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Infrastructure
|
|
66
|
+
|
|
67
|
+
To allow the agent's Lambda function to access the DynamoDB table, grant the necessary permissions in your infrastructure.
|
|
68
|
+
|
|
69
|
+
<Infrastructure>
|
|
70
|
+
<Fragment slot="cdk">
|
|
71
|
+
|
|
72
|
+
```ts title="packages/infra/src/stacks/application-stack.ts"
|
|
73
|
+
import { MyTable } from ':my-scope/common-constructs';
|
|
74
|
+
|
|
75
|
+
const table = new MyTable(this, 'Table');
|
|
76
|
+
const myAgent = new MyAgent(this, 'MyAgent');
|
|
77
|
+
|
|
78
|
+
table.grantReadWriteData(myAgent);
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
`grantReadWriteData` grants both the DynamoDB and KMS permissions to the agent's execution role.
|
|
82
|
+
</Fragment>
|
|
83
|
+
<Fragment slot="terraform">
|
|
84
|
+
|
|
85
|
+
```hcl title="packages/infra/src/main.tf"
|
|
86
|
+
module "my_table" {
|
|
87
|
+
source = "../../common/terraform/src/app/dynamodb/my-table"
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
resource "aws_iam_role_policy" "dynamodb_access" {
|
|
91
|
+
role = module.my_agent.lambda_role_name
|
|
92
|
+
|
|
93
|
+
policy = jsonencode({
|
|
94
|
+
Version = "2012-10-17"
|
|
95
|
+
Statement = [
|
|
96
|
+
{
|
|
97
|
+
Effect = "Allow"
|
|
98
|
+
Action = [
|
|
99
|
+
"dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:UpdateItem",
|
|
100
|
+
"dynamodb:DeleteItem", "dynamodb:Query", "dynamodb:Scan",
|
|
101
|
+
"dynamodb:BatchGetItem", "dynamodb:BatchWriteItem",
|
|
102
|
+
]
|
|
103
|
+
Resource = [
|
|
104
|
+
module.my_table.table_arn,
|
|
105
|
+
"${module.my_table.table_arn}/index/*",
|
|
106
|
+
]
|
|
107
|
+
},
|
|
108
|
+
{
|
|
109
|
+
Effect = "Allow"
|
|
110
|
+
Action = [
|
|
111
|
+
"kms:Encrypt",
|
|
112
|
+
"kms:Decrypt",
|
|
113
|
+
"kms:ReEncrypt*",
|
|
114
|
+
"kms:GenerateDataKey*",
|
|
115
|
+
"kms:DescribeKey"
|
|
116
|
+
]
|
|
117
|
+
Resource = [module.my_table.kms_key_arn]
|
|
118
|
+
},
|
|
119
|
+
]
|
|
120
|
+
})
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
</Fragment>
|
|
124
|
+
</Infrastructure>
|
|
125
|
+
|
|
126
|
+
## Local Development
|
|
127
|
+
|
|
128
|
+
<Snippet name="connection/dynamodb-local-development" />
|
|
@@ -24,7 +24,7 @@ Before using this generator, ensure you have:
|
|
|
24
24
|
|
|
25
25
|
1. A TypeScript project with a <Link path="guides/ts-agent">Strands Agent</Link> component
|
|
26
26
|
2. A project with an MCP server component (either <Link path="guides/ts-mcp-server">`ts#mcp-server`</Link> or <Link path="guides/py-mcp-server">`py#mcp-server`</Link>)
|
|
27
|
-
3. Both components created with `
|
|
27
|
+
3. Both components created with `infra: agentcore`
|
|
28
28
|
|
|
29
29
|
## Usage
|
|
30
30
|
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: MCP Server to DynamoDB
|
|
3
|
+
description: Connect a TypeScript MCP Server to a DynamoDB table
|
|
4
|
+
when:
|
|
5
|
+
sourceType: ts#mcp-server
|
|
6
|
+
targetType: ts#dynamodb
|
|
7
|
+
---
|
|
8
|
+
import Link from '@components/link.astro';
|
|
9
|
+
import RunGenerator from '@components/run-generator.astro';
|
|
10
|
+
import GeneratorParameters from '@components/generator-parameters.astro';
|
|
11
|
+
import NxCommands from '@components/nx-commands.astro';
|
|
12
|
+
import Infrastructure from '@components/infrastructure.astro';
|
|
13
|
+
import Snippet from '@components/snippet.astro';
|
|
14
|
+
|
|
15
|
+
The `connection` generator wires a <Link path="guides/ts-mcp-server">TypeScript MCP Server</Link> to a <Link path="guides/ts-dynamodb">DynamoDB</Link> project, configuring local development so both start together automatically.
|
|
16
|
+
|
|
17
|
+
## Prerequisites
|
|
18
|
+
|
|
19
|
+
Before using this generator, ensure you have:
|
|
20
|
+
|
|
21
|
+
1. A <Link path="guides/ts-mcp-server">`ts#mcp-server`</Link> project
|
|
22
|
+
2. A <Link path="guides/ts-dynamodb">`ts#dynamodb`</Link> project
|
|
23
|
+
|
|
24
|
+
## Usage
|
|
25
|
+
|
|
26
|
+
### Run the Generator
|
|
27
|
+
|
|
28
|
+
<RunGenerator generator="connection" />
|
|
29
|
+
|
|
30
|
+
Select your MCP server project as the source and your DynamoDB project as the target. If the project contains multiple MCP server components, specify `sourceComponent` to disambiguate.
|
|
31
|
+
|
|
32
|
+
### Options
|
|
33
|
+
|
|
34
|
+
<GeneratorParameters generator="connection" />
|
|
35
|
+
|
|
36
|
+
## Generator Output
|
|
37
|
+
|
|
38
|
+
The generator updates the MCP server's `<mcp-server-name>-serve-local` target in `project.json` to depend on the DynamoDB project's `serve-local` target. No source files are modified.
|
|
39
|
+
|
|
40
|
+
## Using DynamoDB in Tools
|
|
41
|
+
|
|
42
|
+
Import entity factories from the DynamoDB package and use them inside `createServer`:
|
|
43
|
+
|
|
44
|
+
```ts title="packages/my-service/src/my-mcp/server.ts"
|
|
45
|
+
import { createExampleEntity } from ':my-scope/my-table';
|
|
46
|
+
|
|
47
|
+
export const createServer = async () => {
|
|
48
|
+
const server = new McpServer({ name: 'my-service', version: '1.0.0' });
|
|
49
|
+
|
|
50
|
+
server.tool('list_examples', 'List all example items', {}, async () => {
|
|
51
|
+
const entity = await createExampleEntity();
|
|
52
|
+
const result = await entity.scan.go();
|
|
53
|
+
return {
|
|
54
|
+
content: [{ type: 'text', text: JSON.stringify(result.data) }],
|
|
55
|
+
};
|
|
56
|
+
});
|
|
57
|
+
|
|
58
|
+
return server;
|
|
59
|
+
};
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Infrastructure
|
|
63
|
+
|
|
64
|
+
To allow the MCP server to access the DynamoDB table, grant the necessary permissions in your infrastructure.
|
|
65
|
+
|
|
66
|
+
<Infrastructure>
|
|
67
|
+
<Fragment slot="cdk">
|
|
68
|
+
|
|
69
|
+
```ts title="packages/infra/src/stacks/application-stack.ts"
|
|
70
|
+
import { MyTable } from ':my-scope/common-constructs';
|
|
71
|
+
|
|
72
|
+
const table = new MyTable(this, 'Table');
|
|
73
|
+
const myMcpServer = new MyMcpServer(this, 'MyMcpServer');
|
|
74
|
+
|
|
75
|
+
table.grantReadWriteData(myMcpServer);
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`grantReadWriteData` grants both the DynamoDB and KMS permissions to the MCP server's execution role.
|
|
79
|
+
</Fragment>
|
|
80
|
+
<Fragment slot="terraform">
|
|
81
|
+
|
|
82
|
+
```hcl title="packages/infra/src/main.tf"
|
|
83
|
+
module "my_table" {
|
|
84
|
+
source = "../../common/terraform/src/app/dynamodb/my-table"
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
resource "aws_iam_role_policy" "dynamodb_access" {
|
|
88
|
+
role = module.my_mcp_server.lambda_role_name
|
|
89
|
+
|
|
90
|
+
policy = jsonencode({
|
|
91
|
+
Version = "2012-10-17"
|
|
92
|
+
Statement = [
|
|
93
|
+
{
|
|
94
|
+
Effect = "Allow"
|
|
95
|
+
Action = [
|
|
96
|
+
"dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:UpdateItem",
|
|
97
|
+
"dynamodb:DeleteItem", "dynamodb:Query", "dynamodb:Scan",
|
|
98
|
+
"dynamodb:BatchGetItem", "dynamodb:BatchWriteItem",
|
|
99
|
+
]
|
|
100
|
+
Resource = [
|
|
101
|
+
module.my_table.table_arn,
|
|
102
|
+
"${module.my_table.table_arn}/index/*",
|
|
103
|
+
]
|
|
104
|
+
},
|
|
105
|
+
{
|
|
106
|
+
Effect = "Allow"
|
|
107
|
+
Action = [
|
|
108
|
+
"kms:Encrypt",
|
|
109
|
+
"kms:Decrypt",
|
|
110
|
+
"kms:ReEncrypt*",
|
|
111
|
+
"kms:GenerateDataKey*",
|
|
112
|
+
"kms:DescribeKey",
|
|
113
|
+
]
|
|
114
|
+
Resource = [module.my_table.kms_key_arn]
|
|
115
|
+
},
|
|
116
|
+
]
|
|
117
|
+
})
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
</Fragment>
|
|
121
|
+
</Infrastructure>
|
|
122
|
+
|
|
123
|
+
## Local Development
|
|
124
|
+
|
|
125
|
+
<Snippet name="connection/dynamodb-local-development" />
|
|
@@ -119,6 +119,35 @@ The Connection generator supports the following connections:
|
|
|
119
119
|
source="mcp"
|
|
120
120
|
target="aurora"
|
|
121
121
|
/>
|
|
122
|
+
<ConnectionCard
|
|
123
|
+
title="tRPC API to DynamoDB"
|
|
124
|
+
description="Connect a tRPC API to a DynamoDB table"
|
|
125
|
+
href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/trpc-dynamodb`}
|
|
126
|
+
source="trpc"
|
|
127
|
+
target="dynamodb"
|
|
128
|
+
/>
|
|
129
|
+
<ConnectionCard
|
|
130
|
+
title="Smithy API to DynamoDB"
|
|
131
|
+
description="Connect a Smithy API to a DynamoDB table"
|
|
132
|
+
href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/smithy-dynamodb`}
|
|
133
|
+
source="smithy"
|
|
134
|
+
target="dynamodb"
|
|
135
|
+
/>
|
|
136
|
+
<ConnectionCard
|
|
137
|
+
title="TypeScript Agent to DynamoDB"
|
|
138
|
+
description="Connect a TypeScript Agent to a DynamoDB table"
|
|
139
|
+
href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-agent-dynamodb`}
|
|
140
|
+
source="strands"
|
|
141
|
+
sourceBadge="typescript"
|
|
142
|
+
target="dynamodb"
|
|
143
|
+
/>
|
|
144
|
+
<ConnectionCard
|
|
145
|
+
title="MCP Server to DynamoDB"
|
|
146
|
+
description="Connect a TypeScript MCP Server to a DynamoDB table"
|
|
147
|
+
href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/ts-mcp-server-dynamodb`}
|
|
148
|
+
source="mcp"
|
|
149
|
+
target="dynamodb"
|
|
150
|
+
/>
|
|
122
151
|
</CardGrid>
|
|
123
152
|
|
|
124
153
|
:::note[Runtime Configuration]
|
|
@@ -8,7 +8,7 @@ import NxCommands from '@components/nx-commands.astro';
|
|
|
8
8
|
import Link from '@components/link.astro';
|
|
9
9
|
import Infrastructure from '@components/infrastructure.astro';
|
|
10
10
|
|
|
11
|
-
Several generators (such as <Link path="/guides/ts-agent">`ts#agent`</Link> and <Link path="/guides/py-agent">`py#agent`</Link>) produce a Docker image that is pushed to Amazon ECR and consumed by AWS infrastructure. This guide describes the pattern they follow so that you can apply it to other use cases — for example, running a <Link path="/guides/fastapi"
|
|
11
|
+
Several generators (such as <Link path="/guides/ts-agent">`ts#agent`</Link> and <Link path="/guides/py-agent">`py#agent`</Link>) produce a Docker image that is pushed to Amazon ECR and consumed by AWS infrastructure. This guide describes the pattern they follow so that you can apply it to other use cases — for example, running a <Link path="/guides/fastapi">FastAPI</Link> project on Amazon ECS, or deploying a containerised Express server.
|
|
12
12
|
|
|
13
13
|
:::tip[Docker or Finch]
|
|
14
14
|
The container engine used to build images is chosen at workspace creation time via the `--containerEngine` flag (`docker`, `finch`, or `infer` — the default — which auto-detects what's installed). [Finch](https://runfinch.com/) is an open-source, drop-in alternative to Docker. The selection is recorded in `aws-nx-plugin.config.mts` and applied to every generator that emits container build commands. CDK image asset builds honour the choice via the `CDK_DOCKER` environment variable.
|
package/docs/guides/fastapi.mdx
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: FastAPI
|
|
3
3
|
description: Reference documentation for FastAPI
|
|
4
|
-
generator: py#
|
|
4
|
+
generator: py#api
|
|
5
5
|
when:
|
|
6
6
|
framework: [fastapi]
|
|
7
7
|
---
|
|
@@ -26,16 +26,16 @@ The FastAPI generator creates a new FastAPI with AWS CDK or Terraform infrastruc
|
|
|
26
26
|
|
|
27
27
|
You can generate a new FastAPI in two ways:
|
|
28
28
|
|
|
29
|
-
<RunGenerator generator="py#
|
|
29
|
+
<RunGenerator generator="py#api" requiredParameters={{ framework: 'fastapi' }} />
|
|
30
30
|
|
|
31
31
|
### Options
|
|
32
32
|
|
|
33
|
-
<GeneratorParameters generator="py#
|
|
33
|
+
<GeneratorParameters generator="py#api" />
|
|
34
34
|
|
|
35
35
|
<Snippet name="api/api-choice-note" />
|
|
36
36
|
|
|
37
37
|
:::tip[API Type]
|
|
38
|
-
Select `
|
|
38
|
+
Select `rest-lambda` (default) as your `infra` if you intend to build any streaming operations.
|
|
39
39
|
:::
|
|
40
40
|
|
|
41
41
|
:::tip[Integration Pattern]
|
|
@@ -185,7 +185,7 @@ Unhandled exceptions are caught by the middleware and:
|
|
|
185
185
|
It's recommended to specify response models for your API operations for better code generation if using the `connection` generator. <Link path="guides/connection/react-fastapi#errors">See here for more details</Link>.
|
|
186
186
|
:::
|
|
187
187
|
|
|
188
|
-
<OptionFilter when={{
|
|
188
|
+
<OptionFilter when={{ infra: 'rest-lambda' }} description="Streaming — REST API only">
|
|
189
189
|
### Streaming
|
|
190
190
|
|
|
191
191
|
The generated FastAPI supports streaming responses out of the box when using a REST API. The infrastructure is configured to use the [AWS Lambda Web Adapter](https://github.com/awslabs/aws-lambda-web-adapter) to run your FastAPI via uvicorn inside Lambda, with `ResponseTransferMode.STREAM` in API Gateway for all REST API operations, which enables streaming to work alongside non-streaming operations.
|
|
@@ -256,7 +256,7 @@ This sets up:
|
|
|
256
256
|
|
|
257
257
|
<Snippet name="api/cors-configuration-cdk-note" />
|
|
258
258
|
|
|
259
|
-
<OptionFilter when={{ auth: '
|
|
259
|
+
<OptionFilter when={{ auth: 'cognito' }} description="Cognito identity construct wiring">
|
|
260
260
|
:::note[Cognito Authentication]
|
|
261
261
|
If you selected to use `Cognito` authentication, you will need to supply the `identity` property to the API construct:
|
|
262
262
|
|
|
@@ -279,7 +279,7 @@ The `UserIdentity` construct can be generated using the <Link path="/guides/reac
|
|
|
279
279
|
:::
|
|
280
280
|
</OptionFilter>
|
|
281
281
|
|
|
282
|
-
<OptionFilter when={{ auth: '
|
|
282
|
+
<OptionFilter when={{ auth: 'custom' }} description="Custom Lambda Authorizer CDK usage">
|
|
283
283
|
:::caution[Custom Lambda Authorizer]
|
|
284
284
|
When using `Custom` auth, the construct creates a Lambda Authorizer internally from the generated `authorizer.py` file, which **denies all requests by default**. You must implement your authorization logic in that file before your API will accept any traffic.
|
|
285
285
|
:::
|
|
@@ -326,7 +326,7 @@ This sets up:
|
|
|
326
326
|
|
|
327
327
|
<Snippet name="api/cors-configuration-terraform-note" />
|
|
328
328
|
|
|
329
|
-
<OptionFilter when={{ auth: '
|
|
329
|
+
<OptionFilter when={{ auth: 'cognito' }} description="Cognito module wiring">
|
|
330
330
|
:::note[Cognito Authentication]
|
|
331
331
|
If you selected to use `Cognito` authentication, you will need to supply the Cognito configuration:
|
|
332
332
|
|
|
@@ -392,7 +392,7 @@ module "my_api" {
|
|
|
392
392
|
}
|
|
393
393
|
```
|
|
394
394
|
|
|
395
|
-
<OptionFilter when={{ auth: '
|
|
395
|
+
<OptionFilter when={{ auth: 'custom' }} description="Custom Lambda Authorizer usage with Terraform">
|
|
396
396
|
:::caution[Custom Lambda Authorizer]
|
|
397
397
|
When using `Custom` auth, your API is protected by a Lambda Authorizer that **denies all requests by default**. You must implement your authorization logic in the generated `authorizer.py` file before your API will accept any traffic.
|
|
398
398
|
:::
|
|
@@ -400,7 +400,7 @@ When using `Custom` auth, your API is protected by a Lambda Authorizer that **de
|
|
|
400
400
|
</Fragment>
|
|
401
401
|
</Infrastructure>
|
|
402
402
|
|
|
403
|
-
<OptionFilter when={{
|
|
403
|
+
<OptionFilter when={{ infra: 'rest-lambda' }} description="WAF — REST APIs get a WAF Web ACL by default">
|
|
404
404
|
### WAF
|
|
405
405
|
|
|
406
406
|
<Snippet name="api/waf-configuration" parentHeading="WAF" />
|
|
@@ -442,7 +442,7 @@ We do not support type-safe integrations for Terraform, and therefore no code ge
|
|
|
442
442
|
</Fragment>
|
|
443
443
|
</Infrastructure>
|
|
444
444
|
|
|
445
|
-
<OptionFilter when={{ auth: '
|
|
445
|
+
<OptionFilter when={{ auth: 'iam' }} description="IAM-authenticated APIs only">
|
|
446
446
|
### Granting Access (IAM Only)
|
|
447
447
|
|
|
448
448
|
If you selected to use `IAM` authentication, you can use the `grantInvokeAccess` method to grant access to your API:
|