@aws/nx-plugin-mcp 0.119.0 → 0.121.0

package/bin/aws-nx-mcp.js

@@ -19408,10 +19408,10 @@ const buildInstallCommand = (pm, pkg, dev) => {
 * The package manager is auto-detected by @aws/create-nx-workspace from the
 * invoking command, so --pm is not needed.
 */
-const buildCreateNxWorkspaceCommand = (pm, workspace, iacProvider) => {
+const buildCreateNxWorkspaceCommand = (pm, workspace, iacProvider, tag) => {
 	return [
 		PACKAGE_MANAGER_COMMANDS[pm]?.create ?? `${pm} create`,
-		"@aws/nx-workspace",
+		tag ? `@aws/nx-workspace@${tag}` : "@aws/nx-workspace",
 		...pm === "npm" ? ["--"] : [],
 		workspace,
 		...iacProvider ? [`--iacProvider=${iacProvider}`] : []
@@ -52676,12 +52676,12 @@ const fetchGuideFrontmatters = async (info) => {
 	}));
 };
 /**
-* Read a guide's raw MDX, local filesystem first, GitHub fallback.
+* Read a guide's raw MDX from the local filesystem (bundled or monorepo).
 */
 const fetchGuideRaw = async (page) => {
 	const local = fetchLocalGuide(page);
 	if (local !== void 0) return local;
-	return await (await fetch(`https://raw.githubusercontent.com/awslabs/nx-plugin-for-aws/refs/heads/main/docs/src/content/docs/en/guides/${page}.mdx`)).text();
+	return "";
 };
 /**
 * Parse a guide's MDX once and return the body, the frontmatter, and the
@@ -52707,17 +52707,16 @@ const parseGuide = async (raw) => {
 	};
 };
 /**
-* Search the monorepo-relative guides directory for a page before falling
-* back to GitHub. This is the common case during local development
-* (`pnpm nx mcp-inspect @aws/nx-plugin`), and it also means test workspaces
-* that link the built plugin read the guides they're actually iterating on
-* instead of whatever is currently on `main`.
-*
-* When running as the published `@aws/nx-plugin-mcp` package, `__dirname`
-* resolves somewhere inside `node_modules/@aws/nx-plugin-mcp`, the local
-* probe misses, and we fall back to GitHub.
+* Probe paths for finding guide MDX files locally. Checked in order:
+* 1. Bundled docs in the published @aws/nx-plugin-mcp package
+* 2. Source checkout when running from the monorepo (dev/test)
+* 3. Rolldown-bundled binary in dist/ (monorepo layout)
 */
-const GUIDES_RELATIVE_PROBES = ["../../../docs/src/content/docs/en/guides", "../../../../docs/src/content/docs/en/guides"];
+const GUIDES_RELATIVE_PROBES = [
+	"../docs/guides",
+	"../../../docs/src/content/docs/en/guides",
+	"../../../../docs/src/content/docs/en/guides"
+];
 const fetchLocalGuide = (guide) => {
 	for (const rel of GUIDES_RELATIVE_PROBES) {
 		const candidate = path.default.resolve(__dirname, rel, `${guide}.mdx`);
@@ -52727,24 +52726,19 @@ const fetchLocalGuide = (guide) => {
 	}
 };
 /**
-* Fetch markdown guide pages. Prefers local files (see `fetchLocalGuide`)
-* and falls back to fetching from the repo on `main` when no local copy
-* is available.
+* Fetch markdown guide pages from the local filesystem (bundled or monorepo).
 */
 const fetchGuidePages = async (guidePages, generators, packageManager, snippetContentProvider, options) => {
-	const fulfilled = (await Promise.allSettled(guidePages.map(async (guide) => {
-		const local = fetchLocalGuide(guide);
-		if (local !== void 0) return local;
-		return await (await fetch(`https://raw.githubusercontent.com/awslabs/nx-plugin-for-aws/refs/heads/main/docs/src/content/docs/en/guides/${guide}.mdx`)).text();
-	}))).filter((result) => result.status === "fulfilled");
-	return (await Promise.all(fulfilled.map((result) => postProcessGuide(result.value, generators, packageManager, snippetContentProvider, options)))).join("\n\n");
+	const guides = guidePages.map((guide) => fetchLocalGuide(guide)).filter((content) => content !== void 0);
+	return (await Promise.all(guides.map((content) => postProcessGuide(content, generators, packageManager, snippetContentProvider, options)))).join("\n\n");
 };
-const SNIPPETS_RELATIVE_PROBES = ["../../../docs/src/content/docs/en/snippets", "../../../../docs/src/content/docs/en/snippets"];
-const SNIPPET_BASE_URL = "https://raw.githubusercontent.com/awslabs/nx-plugin-for-aws/refs/heads/main/docs/src/content/docs/en/snippets";
+const SNIPPETS_RELATIVE_PROBES = [
+	"../docs/snippets",
+	"../../../docs/src/content/docs/en/snippets",
+	"../../../../docs/src/content/docs/en/snippets"
+];
 /**
-* Fetch a snippet's content. Tries the local repo checkout first (when
-* running under `mcp-inspect` or a linked test workspace) before falling
-* back to the copy on `main`.
+* Fetch a snippet's content from the local filesystem (bundled or monorepo).
 */
 const fetchSnippet = async (snippetName) => {
 	for (const rel of SNIPPETS_RELATIVE_PROBES) {
@@ -52753,13 +52747,7 @@ const fetchSnippet = async (snippetName) => {
 			if (fs.default.existsSync(candidate)) return fs.default.readFileSync(candidate, "utf-8");
 		} catch {}
 	}
-	try {
-		const response = await fetch(`${SNIPPET_BASE_URL}/${snippetName}.mdx`);
-		if (!response.ok) return "";
-		return await response.text();
-	} catch {
-		return "";
-	}
+	return "";
 };
 /**
 * Post-process a guide page. Thin wrapper around the unified/remark-mdx

package/docs/guides/astro-docs.mdx

@@ -0,0 +1,142 @@
+---
+title: Astro Docs
+description: Reference documentation for an Astro + Starlight documentation site
+generator: ts#astro-docs
+---
+import { FileTree } from '@astrojs/starlight/components';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+
+This generator scaffolds a documentation site powered by [Astro](https://astro.build/)
+and the [Starlight](https://starlight.astro.build/) docs theme. It wires up
+localisation, reusable content snippets, locale-aware internal links and a
+[`starlight-blog`](https://starlight-blog-docs.vercel.app/) plugin by default.
+
+By default it also scaffolds an automated translation pipeline powered by a
+[Strands Agent](https://strandsagents.com/) on
+[Amazon Bedrock](https://aws.amazon.com/bedrock/).
+
+## Usage
+
+### Generate an Astro docs site
+
+You can generate a new Astro docs site in two ways:
+
+<RunGenerator generator="ts#astro-docs" />
+
+### Options
+
+<GeneratorParameters generator="ts#astro-docs" />
+
+## Generator Output
+
+By default the generator creates the following project structure at `docs/` in the
+workspace root (configurable via the `name`, `directory` and `subDirectory` options):
+
+<FileTree>
+  - astro.config.mjs Astro + Starlight configuration (locales, sidebar, blog plugin)
+  - tsconfig.json Extends astro/tsconfigs/strict with @components / @assets path aliases
+  - project.json Nx project with `build`, `start`, `preview` (and `translate` if enabled) targets
+  - scripts
+    - translate.ts Translation driver — a Strands agent with a scoped file-editor tool (omitted with `--noTranslation`)
+    - translate.config.json Source/target locales, glob patterns, model id, region (omitted with `--noTranslation`)
+  - src
+    - components
+      - link.astro Locale-aware link component (resolves paths against the current locale)
+      - snippet.astro Locale-aware snippet loader component
+    - content
+      - docs
+        - en
+          - index.mdx Landing page
+          - guides
+            - getting-started.mdx Sample guide referencing the link and snippet components
+          - blog
+            - welcome.mdx Sample blog post (omitted with `--noBlog`)
+          - snippets
+            - example.mdx Sample reusable snippet
+    - styles
+      - custom.css Starlight theme overrides
+  - README.md Project README
+</FileTree>
+
+### Localisation
+
+The generator defaults to a single locale (`en`) and redirects the root URL to
+it. To add more languages:
+
+1. Add an entry under `locales` in `astro.config.mjs` (for example `ko: { label: '한국어' }`).
+2. Create a matching directory under `src/content/docs/<locale>/`.
+3. Populate it manually, or use the translation target described below.
+
+## Translation
+
+Unless you passed `--noTranslation`, the generator adds a `translate` target to
+`project.json`, so you can run:
+
+<NxCommands commands={[
+  'translate docs -- --all',
+  'translate docs -- --languages jp,ko',
+  'translate docs -- --dry-run',
+]} />
+
+When run without `--all`, the script only translates files that have changed
+since the last translation commit on the current branch — meaning you can
+safely re-run it on every docs PR without re-translating the whole site.
+
+### Configuring translation
+
+Edit `scripts/translate.config.json` to change:
+
+| Field | Purpose |
+| --- | --- |
+| `sourceLanguage` | Locale to translate **from** (default `en`). |
+| `targetLanguages` | Locales to translate **to**. Empty by default. For example `["fr", "de", "es", "ja", "ko"]`. |
+| `docsDir` | Path to the docs content directory, relative to the project root. |
+| `include` | Glob patterns (relative to `<docsDir>/<sourceLanguage>`) for files to translate. |
+| `exclude` | Glob patterns to skip. |
+| `modelId` | Bedrock model to use for translations. |
+| `awsRegion` | AWS region the Bedrock client is configured with. Can also be set via `AWS_REGION`. |
+| `concurrency` | Max number of concurrent agent invocations. |
+| `translationCommitMessage` | Commit message marker for translation commits (default `docs: update translations`). |
+
+### Locale-aware internal links
+
+The generator ships a `Link` component that automatically resolves internal
+docs paths against the current locale, so a single source of truth produces
+the right URL in every language:
+
+```mdx
+import Link from '@components/link.astro';
+
+<Link path="guides/getting-started">Read the getting-started guide</Link>
+```
+
+### Snippets
+
+Reusable content fragments live in `src/content/docs/<locale>/snippets/`. The
+generated `Snippet` component loads the snippet that matches the current
+locale:
+
+```mdx
+import Snippet from '@components/snippet.astro';
+
+<Snippet name="example" />
+```
+
+### Wiring up CI
+
+No CI workflow is generated out of the box — add one that:
+
+1. Configures AWS credentials with permission to invoke Bedrock `InvokeModel` on
+   the configured model.
+2. Runs the `translate` target on pull requests that touch your source-language
+   docs:
+
+   <NxCommands commands={['translate docs']} />
+
+3. Commits the resulting translations back to the PR branch. The commit message
+   must match the `translationCommitMessage` value in
+   `scripts/translate.config.json` (default `docs: update translations`) so that
+   subsequent incremental runs can detect the baseline commit and only
+   re-translate the files that changed since.

package/docs/guides/connection/py-agent-a2a.mdx

@@ -0,0 +1,105 @@
+---
+title: Python Agent to A2A Agent
+description: Connect a Python Agent to a remote A2A agent
+when:
+  sourceType: py#agent
+  targetType:
+    - ts#agent
+    - py#agent
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Snippet from '@components/snippet.astro';
+
+The `connection` generator can connect your <Link path="guides/py-agent">Python Agent</Link> to a remote [A2A](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-a2a.html) agent — either <Link path="guides/ts-agent">TypeScript</Link> or <Link path="guides/py-agent">Python</Link> — so your agent can delegate to another agent as a tool.
+
+The generator sets up all the necessary wiring so your agent can discover and invoke the remote A2A agent, both when deployed to AWS (via Bedrock AgentCore) and when running locally.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A Python project with a <Link path="guides/py-agent">Strands Agent</Link> component (any protocol)
+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>)
+3. Both components created with `computeType: BedrockAgentCoreRuntime`
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your host agent project as the source and your A2A agent project as the target. If your projects contain multiple components, specify the `sourceComponent` and `targetComponent` options to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator creates a shared `agent_connection` Python project at `packages/common/agent_connection/` (if it doesn't already exist). Per-connection client modules are generated into this shared project:
+
+<FileTree>
+
+- packages/common/agent\_connection
+  - \<scope>\_agent\_connection
+    - \_\_init\_\_.py Re-exports per-connection clients
+    - core
+      - agentcore\_a2a\_client.py Core AgentCore A2A client with SigV4 authentication
+    - app
+      - \<target\_agent\_name>\_client.py Per-connection client for each A2A agent
+
+</FileTree>
+
+Additionally, the generator:
+- Transforms your agent's `agent.py` to register the remote A2A agent as a tool using `@tool`
+- Adds the `agent_connection` project as a workspace dependency of your agent project
+- Updates the agent's `serve-local` target to depend on the target agent's `serve-local` target
+
+## Using the Connected A2A Agent
+
+The generator transforms your agent's `agent.py` to wrap the remote A2A agent as a tool:
+
+```python title="packages/my-project/my_module/agent/agent.py" {4,9-15,21}
+from contextlib import contextmanager
+from strands import Agent, tool
+
+from my_scope_agent_connection import RemoteAgentClient
+
+@contextmanager
+def get_agent(session_id: str):
+    remote_agent = RemoteAgentClient.create(session_id=session_id)
+
+    @tool
+    def ask_remote_agent(prompt: str) -> str:
+        """Delegate a question to the remote RemoteAgent A2A agent and return its reply."""
+        return str(remote_agent(prompt))
+
+    yield Agent(
+        system_prompt="...",
+        tools=[ask_remote_agent],
+    )
+```
+
+The `session_id` parameter is plumbed through from the caller, ensuring consistency for [Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html).
+
+Under the hood, `RemoteAgentClient.create(session_id=...)` returns a Strands `A2AAgent` configured with an `httpx.AsyncClient` that signs requests with SigV4 when deployed to AWS, and a plain `http://localhost:<port>/` endpoint when `SERVE_LOCAL=true`.
+
+## Infrastructure
+
+<Snippet name="connection/a2a-infrastructure" parentHeading="Infrastructure" />
+
+## Local Development
+
+The generator configures the host agent's `serve-local` target to:
+1. Start the connected A2A agent(s) automatically
+2. Set `SERVE_LOCAL=true` so the generated client connects directly to `http://localhost:<port>/` instead of AgentCore
+
+Run the agent locally with:
+
+<NxCommands commands={["<agent-name>-serve-local <project-name>"]} />
+
+This will start both the host agent and all connected A2A agents, with the host agent calling the remote agents over plain HTTP on their assigned local ports.

package/docs/guides/connection/py-agent-mcp.mdx

@@ -0,0 +1,147 @@
+---
+title: Python Agent to MCP
+description: Connect a Python Agent to an MCP server
+when:
+  sourceType: py#agent
+  targetType:
+    - ts#mcp-server
+    - py#mcp-server
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Infrastructure from '@components/infrastructure.astro';
+
+The `connection` generator can connect your <Link path="guides/py-agent">Python Agent</Link> to an MCP server (either <Link path="guides/ts-mcp-server">TypeScript</Link> or <Link path="guides/py-mcp-server">Python</Link>).
+
+The generator sets up all the necessary wiring so your agent can discover and invoke the MCP server's tools, both when deployed to AWS (via Bedrock AgentCore) and when running locally.
+
+## Prerequisites
+
+Before using this generator, ensure you have:
+
+1. A Python project with a <Link path="guides/py-agent">Strands Agent</Link> component
+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>)
+3. Both components created with `computeType: BedrockAgentCoreRuntime`
+
+## Usage
+
+### Run the Generator
+
+<RunGenerator generator="connection" />
+
+Select your agent project as the source and your MCP server project as the target. If your projects contain multiple components, specify the `sourceComponent` and `targetComponent` options to disambiguate.
+
+### Options
+
+<GeneratorParameters generator="connection" />
+
+## Generator Output
+
+The generator creates a shared `agent_connection` Python project at `packages/common/agent_connection/` (if it doesn't already exist). Per-connection client modules are generated into this shared project:
+
+<FileTree>
+
+- packages/common/agent\_connection
+  - \<scope>\_agent\_connection
+    - \_\_init\_\_.py Re-exports per-connection clients
+    - core
+      - agentcore\_mcp\_client.py Core AgentCore MCP client
+    - app
+      - \<mcp\_server\_name>\_client.py Per-connection client for each MCP server
+
+</FileTree>
+
+Additionally, the generator:
+- Transforms your agent's `agent.py` to import and use the MCP server's tools via a class-based client
+- Adds the `agent_connection` project as a workspace dependency of your agent project
+- Updates the agent's `serve-local` target to depend on the MCP server's serve target
+
+## Using the Connected MCP Server
+
+The generator transforms your agent's `agent.py` to use the MCP server's tools:
+
+```python title="packages/my-project/my_module/agent/agent.py" {4,10-14}
+from contextlib import contextmanager
+from strands import Agent
+
+from my_scope_agent_connection import MyMcpServerClient
+
+@contextmanager
+def get_agent(session_id: str):
+    my_mcp_server = MyMcpServerClient.create(session_id=session_id)
+    with (
+        my_mcp_server,
+    ):
+        yield Agent(
+            system_prompt="...",
+            tools=[*my_mcp_server.list_tools_sync()],
+        )
+```
+
+The `session_id` parameter is plumbed through from the caller, ensuring consistency for [Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html).
+
+## Infrastructure
+
+<Infrastructure>
+<Fragment slot="cdk">
+After running the connection generator, you need to grant the agent permission to invoke the MCP server:
+
+```ts title="packages/infra/src/stacks/application-stack.ts" {5}
+const mcpServer = new MyMcpServer(this, 'MyMcpServer');
+const myAgent = new MyAgent(this, 'MyAgent');
+
+// Grant the agent permissions to invoke the MCP server
+mcpServer.grantInvokeAccess(myAgent);
+```
+
+The MCP server's AgentCore runtime ARN is automatically registered in the `agentcore` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link> by the generated CDK construct, so the agent can discover it at runtime.
+</Fragment>
+<Fragment slot="terraform">
+After running the connection generator, you need to grant the agent permission to invoke the MCP server in your Terraform configuration:
+
+```hcl title="packages/infra/src/main.tf" {12-24}
+module "inventory_mcp_server" {
+  source = "../../common/terraform/src/app/mcp-servers/inventory-mcp"
+}
+
+module "story_agent" {
+  source = "../../common/terraform/src/app/agents/story-agent"
+}
+
+# Grant the agent permissions to invoke the MCP server
+resource "aws_iam_policy" "agent_invoke_mcp" {
+  name = "AgentInvokeMcpPolicy"
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect   = "Allow"
+      Action   = "bedrock-agentcore:InvokeAgent"
+      Resource = module.inventory_mcp_server.agent_core_runtime_arn
+    }]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "agent_invoke_mcp" {
+  role       = module.story_agent.agent_core_runtime_role_arn
+  policy_arn = aws_iam_policy.agent_invoke_mcp.arn
+}
+```
+
+The MCP server's AgentCore runtime ARN is automatically registered in the `agentcore` namespace of <Link path="guides/runtime-config">Runtime Configuration</Link> by the generated Terraform module, so the agent can discover it at runtime.
+</Fragment>
+</Infrastructure>
+
+## Local Development
+
+The generator configures the agent's `serve-local` target to:
+1. Start the connected MCP server(s) automatically
+2. Set `SERVE_LOCAL=true` so the generated client uses direct HTTP transport instead of AgentCore
+
+Run the agent locally with:
+
+<NxCommands commands={["<agent-name>-serve-local <project-name>"]} />
+
+This will start both the agent and all connected MCP servers, with the agent connecting to the MCP servers directly via HTTP on their assigned local ports.