@aws/nx-plugin-mcp 1.0.0-rc.45 → 1.0.0-rc.47

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

@@ -53,7 +53,7 @@ Additionally, the agent's `<agent-name>-dev` target is updated to depend on the
 The Prisma client is instantiated inside `getAgent()`. Since the `ts#agent` generator configures a single Agent per session, the client is also reused for the lifetime of the session:
 
 ```ts title="packages/my-service/src/my-agent/agent.ts" {1,4}
-import { getPrisma as getMyDb } from ':my-scope/my-db';
+import { getPrisma as getMyDb } from '@my-scope/my-db';
 
 export const getAgent = async () => {
   const myDb = await getMyDb();
@@ -67,8 +67,8 @@ export const getAgent = async () => {
 Running the generator again with a different target adds the second database alongside the first:
 
 ```ts title="packages/my-service/src/my-agent/agent.ts" {1,2,5,6}
-import { getPrisma as getMyDb } from ':my-scope/my-db';
-import { getPrisma as getOtherDb } from ':my-scope/other-db';
+import { getPrisma as getMyDb } from '@my-scope/my-db';
+import { getPrisma as getOtherDb } from '@my-scope/other-db';
 
 export const getAgent = async () => {
   const myDb = await getMyDb();
@@ -88,7 +88,7 @@ The generated agent construct implements `IGrantable` and `IConnectable`, so you
 ```ts title="packages/infra/src/stacks/application-stack.ts"
 import { SecurityGroup } from 'aws-cdk-lib/aws-ec2';
 import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';
-import { MyDatabase } from ':my-scope/common-constructs';
+import { MyDatabase } from '@my-scope/common-constructs';
 
 const db = new MyDatabase(this, 'Db', { vpc, ... });
 

package/docs/guides/connection/ts-mcp-server-dynamodb.mdx

@@ -42,7 +42,7 @@ The generator updates the MCP server's `<mcp-server-name>-dev` target in `projec
 Import entity factories from the DynamoDB package and use them inside `createServer`:
 
 ```ts title="packages/my-service/src/my-mcp/server.ts"
-import { createExampleEntity } from ':my-scope/my-table';
+import { createExampleEntity } from '@my-scope/my-table';
 
 export const createServer = async () => {
   const server = new McpServer({ name: 'my-service', version: '1.0.0' });
@@ -67,7 +67,7 @@ To allow the MCP server to access the DynamoDB table, grant the necessary permis
 <Fragment slot="cdk">
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyTable } from ':my-scope/common-constructs';
+import { MyTable } from '@my-scope/common-constructs';
 
 const table = new MyTable(this, 'Table');
 const myMcpServer = new MyMcpServer(this, 'MyMcpServer');

package/docs/guides/connection/ts-mcp-server-rdb.mdx

@@ -53,7 +53,7 @@ Additionally, the `<mcp-server-name>-dev` target is updated to depend on the dat
 The Prisma client is fetched inside `createServer` and available to all tools and resources registered there:
 
 ```ts title="packages/my-service/src/my-mcp/server.ts" {1,4}
-import { getPrisma as getMyDb } from ':my-scope/my-db';
+import { getPrisma as getMyDb } from '@my-scope/my-db';
 
 export const createServer = async () => {
   const myDb = await getMyDb();
@@ -87,7 +87,7 @@ The generated MCP server construct implements `IGrantable` and `IConnectable`, s
 ```ts title="packages/infra/src/stacks/application-stack.ts"
 import { SecurityGroup } from 'aws-cdk-lib/aws-ec2';
 import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';
-import { MyDatabase } from ':my-scope/common-constructs';
+import { MyDatabase } from '@my-scope/common-constructs';
 
 const db = new MyDatabase(this, 'Db', { vpc, ... });
 

package/docs/guides/docker-bundling.mdx

@@ -342,7 +342,7 @@ infra.asset -> ecr: cdk deploy\nbuilds + pushes
 
 ```ts
 import { DockerImageAsset, Platform } from 'aws-cdk-lib/aws-ecr-assets';
-import { findWorkspaceRoot } from ':my-scope/common-constructs';
+import { findWorkspaceRoot } from '@my-scope/common-constructs';
 import * as path from 'path';
 import * as url from 'url';
 
@@ -356,7 +356,7 @@ const image = new DockerImageAsset(this, 'MyImage', {
 });
 ```
 
-The `findWorkspaceRoot` helper is generated by the <Link path="/guides/typescript-infrastructure">`ts#infra`</Link> generator and exported from `:my-scope/common-constructs`. If you are not using shared constructs, you can hardcode the path to the `dist` directory relative to where `cdk` is invoked from — typically the workspace root — and omit the `findWorkspaceRoot` call entirely.
+The `findWorkspaceRoot` helper is generated by the <Link path="/guides/typescript-infrastructure">`ts#infra`</Link> generator and exported from `@my-scope/common-constructs`. If you are not using shared constructs, you can hardcode the path to the `dist` directory relative to where `cdk` is invoked from — typically the workspace root — and omit the `findWorkspaceRoot` call entirely.
 
 :::note[Running bundle before synth]
 CDK does not run the `bundle`/`docker` targets automatically — you must run `nx build my-project` (or wire the deploy target to depend on `build`) before `cdk deploy`. The generators that use this pattern declare `docker` and `bundle` as dependencies of `build` so this happens transparently.

package/docs/guides/fastapi.mdx

@@ -445,7 +445,7 @@ The FastAPI generator creates CDK or Terraform infrastructure as code based on y
 The CDK construct for deploying your API in the `common/constructs` folder. You can use this in a CDK application:
 
 ```ts {6-8}
-import { MyApi } from ':my-scope/common-constructs';
+import { MyApi } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -473,7 +473,7 @@ This sets up:
 If you selected to use `Cognito` authentication, you will need to supply the `identity` property to the API construct:
 
 ```ts {9}
-import { MyApi, UserIdentity } from ':my-scope/common-constructs';
+import { MyApi, UserIdentity } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {

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

@@ -149,7 +149,7 @@ You will need to add the user identity infrastructure to your stack, declaring i
 ```ts title="packages/infra/src/stacks/application-stack.ts" {3,9}
 import { Stack } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { MyWebsite, UserIdentity } from ':my-scope/common-constructs';
+import { MyWebsite, UserIdentity } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -195,7 +195,7 @@ The user identity module automatically adds the necessary <Link path="guides/rea
 </Infrastructure>
 
 :::caution[Remove localhost callback URLs for production]
-The generated User Pool client allows your CloudFront distribution URL as an OAuth callback/logout URL, plus `http://localhost:4200` and `http://localhost:4300` for local development against the deployed pool.
+The generated User Pool client allows your CloudFront distribution URL (and any custom domain names configured on it) as OAuth callback/logout URLs, plus `http://localhost:4200` and `http://localhost:4300` for local development against the deployed pool.
 
 It is recommended to **remove the `http://localhost` callback/logout URLs for production stages**, keeping the allowlist limited to your real application origins.
 
@@ -218,7 +218,7 @@ In order to grant authenticated users access to perform certain actions, such as
 ```ts title="packages/infra/src/stacks/application-stack.ts" {12}
 import { Stack } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { MyWebsite, UserIdentity, MyApi } from ':my-scope/common-constructs';
+import { MyWebsite, UserIdentity, MyApi } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string) {

package/docs/guides/react-website.mdx

@@ -59,6 +59,7 @@ The generator will create the following project structure in the `<directory>/<n
   - tsconfig.json Base TypeScript configuration for source and tests
   - tsconfig.app.json TypeScript configuration for source code
   - tsconfig.spec.json TypeScript configuration for tests
+  - package.json Project manifest defining the project's package name and dependencies
 </FileTree>
 
 :::note[Without TanStack Router]
@@ -245,7 +246,7 @@ Your website CDK construct will deploy the `connection` namespace of the runtime
 ```ts title="packages/infra/src/stacks/application-stack.ts"
 import { Stack } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { MyWebsite, MyApi } from ':my-scope/common-constructs';
+import { MyWebsite, MyApi } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -427,7 +428,7 @@ You can use the CDK construct generated for you in `packages/common/constructs`
 ```ts title="packages/infra/src/stacks/application-stack.ts" {3, 9}
 import { Stack } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { MyWebsite } from ':my-scope/common-constructs';
+import { MyWebsite } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -447,7 +448,7 @@ This sets up:
 5. Automatic deployment of website files and runtime configuration
 </Fragment>
 <Fragment slot="terraform">
-To deploy your website, we recommend using the <Link path="guides/terraform-infrastructure">`terraform#project` generator</Link> to create a Terraform project.
+To deploy your website, we recommend using the <Link path="/guides/terraform-project">`terraform#project` generator</Link> to create a Terraform project.
 
 You can use the Terraform module generated for you in `packages/common/terraform` to deploy your website.
 

package/docs/guides/runtime-config.mdx

@@ -70,7 +70,7 @@ Generated constructs automatically write relevant configuration to the `connecti
 The `RuntimeConfig` CDK construct is a stage-scoped singleton. Use `set()` to write a key into a namespace:
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { RuntimeConfig } from ':my-scope/common-constructs';
+import { RuntimeConfig } from '@my-scope/common-constructs';
 
 const rc = RuntimeConfig.ensure(this);
 

package/docs/guides/trpc.mdx

@@ -66,6 +66,7 @@ The generator will create the following project structure in the `<directory>/<a
     - client
       - index.ts Type-safe client for machine-to-machine API calls
   - tsconfig.json TypeScript configuration
+  - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
 
 </FileTree>
@@ -558,7 +559,7 @@ The CDK construct for deploying your API lives in the `common/constructs` folder
 
 <OptionFilter when={{ auth: ['iam', 'custom'] }} description="CDK usage for IAM or Custom authentication">
 ```ts {6-8}
-import { MyApi } from ':my-scope/common-constructs';
+import { MyApi } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -577,7 +578,7 @@ When using `Custom` auth, the construct creates a Lambda Authorizer internally f
 
 <OptionFilter when={{ auth: 'cognito' }} description="CDK usage with Cognito authentication — pass the identity construct">
 ```ts {6,9}
-import { MyApi, UserIdentity } from ':my-scope/common-constructs';
+import { MyApi, UserIdentity } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -813,7 +814,7 @@ This will automatically reload when you make changes to your API.
 You can create a tRPC client to invoke your API in a type-safe manner. If you are calling your tRPC API from another backend, you can use the client in `src/client/index.ts`, for example:
 
 ```ts
-import { createMyApiClient } from ':my-scope/my-api';
+import { createMyApiClient } from '@my-scope/my-api';
 
 const client = createMyApiClient({ url: 'https://my-api-url.example.com/' });
 

package/docs/guides/ts-dcr-proxy.mdx

@@ -28,7 +28,7 @@ MCP clients (such as Claude Code, Kiro CLI or the MCP Inspector) expect to authe
 
 ## Generator Output
 
-The generator creates a standalone <Link path="/guides/typescript-project">TypeScript project</Link> containing the Lambda handlers, and infrastructure to deploy them based on your selected `iacProvider`.
+The generator creates a standalone <Link path="/guides/typescript-project">TypeScript project</Link> containing the Lambda handlers, and infrastructure to deploy them based on your selected `iac`.
 
 <FileTree>
 

package/docs/guides/ts-dynamodb.mdx

@@ -36,6 +36,7 @@ The generator creates the following project structure in the `<directory>/<name>
       - example.ts Example ElectroDB entity definition
       - index.ts Entity exports
   - config.json Table configuration including GSI definitions and local development settings
+  - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
 </FileTree>
 
@@ -136,7 +137,7 @@ GSIs are defined in `config.json` at the project root under the `tableConfig.glo
 In any TypeScript project, import entity factories from your DynamoDB package and use them directly:
 
 ```ts
-import { createExampleEntity } from ':my-scope/my-table';
+import { createExampleEntity } from '@my-scope/my-table';
 
 const entity = await createExampleEntity();
 const result = await entity.query.primary({ id: '123' }).go();

package/docs/guides/ts-mcp-server.mdx

@@ -79,40 +79,57 @@ If you selected `none` for `infra`, no CDK constructs or Terraform modules are g
 
 ### Adding Tools
 
-Tools are functions that the AI assistant can call to perform actions. You can add new tools in the `server.ts` file:
-
-```typescript
-server.registerTool("toolName", {
-  description: "tool description",
-  inputSchema: { param1: z.string(), param2: z.number() } // Input schema using Zod
-},
-  async ({ param1, param2 }) => {
-    // Tool implementation
-    return {
-      content: [{ type: "text", text: "Result" }]
-    };
-  }
-);
+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`:
+
+```typescript title="tools/my-tool.ts"
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+export const registerMyTool = (server: McpServer) => {
+  server.registerTool("toolName", {
+    description: "tool description",
+    inputSchema: { param1: z.string(), param2: z.number() } // Input schema using Zod
+  },
+    async ({ param1, param2 }) => {
+      // Tool implementation
+      return {
+        content: [{ type: "text", text: "Result" }]
+      };
+    }
+  );
+};
+```
+
+Then register it in `server.ts`:
+
+```typescript title="server.ts"
+import { registerMyTool } from './tools/my-tool.js';
+
+registerMyTool(server);
 ```
 
 ### Adding Resources
 
-Resources provide context to the AI assistant. You can add static resources from files or dynamic resources:
+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:
+
+```typescript title="resources/my-resource.ts"
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
-```typescript
-const exampleContext = 'some context to return';
+export const registerMyResource = (server: McpServer) => {
+  const exampleContext = 'some context to return';
 
-server.registerResource('resource-name', 'example://resource', {}, async (uri) => ({
-  contents: [{ uri: uri.href, text: exampleContext }],
-}));
+  server.registerResource('resource-name', 'example://resource', {}, async (uri) => ({
+    contents: [{ uri: uri.href, text: exampleContext }],
+  }));
 
-// Dynamic resource
-server.registerResource('dynamic-resource', 'dynamic://resource', {}, async (uri) => {
-  const data = await fetchSomeData();
-  return {
-    contents: [{ uri: uri.href, text: data }],
-  };
-});
+  // Dynamic resource
+  server.registerResource('dynamic-resource', 'dynamic://resource', {}, async (uri) => {
+    const data = await fetchSomeData();
+    return {
+      contents: [{ uri: uri.href, text: data }],
+    };
+  });
+};
 ```
 
 ## Configuring with AI Assistants

package/docs/guides/ts-nx-plugin.mdx

@@ -55,14 +55,14 @@ The generator will create the following project structure:
 
 ### Adding Generators
 
-Once you have your plugin project, you can add generators using the <Link path="/guides/ts-nx-generator">`ts#nx-generator`</Link> generator:
+Once you have your plugin project, you can add generators using the <Link path="/guides/nx-generator">`ts#nx-generator`</Link> generator:
 
 <RunGenerator generator="ts#nx-generator" requiredParameters={{ pluginProject: 'your-plugin' }} />
 
 This will add a new generator to your plugin.
 
 :::tip[Generator Documentation]
-Read the <Link path="/guides/ts-nx-generator">`ts#nx-generator` guide</Link> for details about how to implement generators.
+Read the <Link path="/guides/nx-generator">`ts#nx-generator` guide</Link> for details about how to implement generators.
 :::
 
 Make sure to write a detailed `README.md` for your generator, since this is used by the MCP Server's `generator-guide` tool.

package/docs/guides/ts-rdb.mdx

@@ -47,6 +47,7 @@ The generator will create the following project structure in the `<directory>/<n
   - .gitignore Git ignore entries including generated Prisma client output
   - config.json Local development connection details and runtime config key
   - Dockerfile Container image definition for the migration handler
+  - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
   - prisma.config.ts Configuration for Prisma CLI
 </FileTree>
@@ -173,7 +174,7 @@ Replace `<engine>` with your container engine (`docker` or `finch`), `<scope>` w
 In any TypeScript project, import `getPrisma` from your database package and call it to get a type-safe Prisma client:
 
 ```ts
-import { getPrisma } from ':my-scope/db';
+import { getPrisma } from '@my-scope/db';
 
 const prisma = await getPrisma();
 const users = await prisma.user.findMany({ orderBy: { id: 'asc' } });
@@ -340,7 +341,7 @@ export const listExampleTable = publicProcedure
 If you are using the [middleware pattern](#injecting-the-prisma-client-via-middleware), add the `$disconnect()` call to the middleware so all procedures built on it are covered automatically:
 
 ```ts title="packages/api/src/middleware/db.ts"
-import { getPrisma } from ':my-scope/db';
+import { getPrisma } from '@my-scope/db';
 import { initTRPC } from '@trpc/server';
 
 export interface IDbContext {

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

@@ -46,6 +46,7 @@ The generator creates two related projects in the `<directory>/<api-name>` direc
 <FileTree>
 
 - **model/** Smithy model project
+  - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
   - smithy-build.json Smithy build configuration
   - build.Dockerfile Docker configuration for building Smithy artifacts
@@ -588,7 +589,7 @@ The generator creates CDK or Terraform infrastructure based on your selected `ia
 The CDK construct for deploying your API is in the `common/constructs` folder:
 
 ```ts {6-8}
-import { MyApi } from ':my-scope/common-constructs';
+import { MyApi } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -615,7 +616,7 @@ This sets up:
 If you selected `Cognito` authentication, you will need to supply the `identity` property to the API construct:
 
 ```ts {9}
-import { MyApi, UserIdentity } from ':my-scope/common-constructs';
+import { MyApi, UserIdentity } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {

package/docs/guides/typescript-infrastructure.mdx

@@ -38,6 +38,7 @@ The generator will create the following project structure in the `<directory>/<n
     - stacks CDK Stack definitions
       - application-stack.ts Main application stack
   - cdk.json CDK configuration
+  - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
   - checkov.yml Checkov configuration file
 
@@ -102,10 +103,11 @@ The `env` property tells CDK which AWS account and region to deploy to. `CDK_DEF
 If you generated with `stageConfig`, the `main.ts` reads account and region from a centralized config file instead, falling back to environment variables when no config is set:
 
 ```ts title="src/main.ts (with stageConfig)"
-import stagesConfig from ':my-scope/common-infra-config';
+import { resolveStage } from '@my-scope/common-infra-config';
 
-const projectStages = stagesConfig.projects?.['packages/infra']?.stages ?? {};
-const sandboxConfig = projectStages['my-app-sandbox'];
+// Looks up the stage under this project (packages/infra), falling back to
+// shared stages. Returns undefined when no config exists for the stage.
+const sandboxConfig = resolveStage('packages/infra', 'my-app-sandbox');
 
 new ApplicationStage(app, 'my-app-sandbox', {
   env: {
@@ -242,7 +244,7 @@ Each stage config includes a required `region` and an optional `account`:
 The generated `main.ts` reads these values from the config so that CDK synthesis and deployment use the same environment settings:
 
 ```ts title="src/main.ts"
-const sandboxConfig = projectStages['my-app-sandbox'];
+const sandboxConfig = resolveStage('packages/infra', 'my-app-sandbox');
 new ApplicationStage(app, 'my-app-sandbox', {
   env: {
     account: sandboxConfig?.account ?? process.env.CDK_DEFAULT_ACCOUNT,
@@ -270,7 +272,7 @@ If, for example, you created a tRPC API called `my-api`, you can simply import a
 ```ts title="src/stacks/application-stack.ts" {3, 9-12}
 import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { MyApi } from ':my-scope/common-constructs';
+import { MyApi } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
@@ -291,7 +293,7 @@ If you have used the <Link path="guides/react-website">React Website</Link> gene
 ```ts title="src/stacks/application-stack.ts" {3, 9-10}
 import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { MyWebsite } from ':my-scope/common-constructs';
+import { MyWebsite } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
@@ -338,7 +340,7 @@ There may be instances where you want to suppress certain rules on resources. Yo
 #### Supress a rule on a given construct
 
 ```typescript
-import { suppressRules } from ':my-scope/common-constructs';
+import { suppressRules } from '@my-scope/common-constructs';
 
 // suppresses the CKV_AWS_XXX for the given construct.
 suppressRules(construct, ['CKV_AWS_XXX'], 'Reason');
@@ -347,7 +349,7 @@ suppressRules(construct, ['CKV_AWS_XXX'], 'Reason');
 #### Supress a rule on a descendant construct
 
 ```typescript
-import { suppressRules } from ':my-scope/common-constructs';
+import { suppressRules } from '@my-scope/common-constructs';
 
 // Supresses the CKV_AWS_XXX for the construct or any of its descendants if it is an instance of Bucket
 suppressRules(construct, ['CKV_AWS_XXX'], 'Reason', (construct) => construct instanceof Bucket);