@aws/nx-plugin-mcp 0.119.0 → 0.121.0

package/docs/snippets/mcp/bedrock-deployment.mdx

@@ -0,0 +1,167 @@
+---
+title: MCP Bedrock Deployment
+---
+import Link from '@components/link.astro';
+import Infrastructure from '@components/infrastructure.astro';
+
+### Infrastructure as Code
+
+If you selected `BedrockAgentCoreRuntime` for `computeType`, the relevant CDK or Terraform infrastructure is generated which you can use to deploy your MCP server to [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agents-tools-runtime.html).
+
+<Infrastructure>
+<Fragment slot="cdk">
+A CDK construct is generated for your MCP Server, named based on the `name` you chose when running the generator, or `<ProjectName>McpServer` by default.
+
+You can use this CDK construct in a CDK application:
+
+```ts {6}
+import { MyProjectMcpServer } from ':my-scope/common-constructs';
+
+export class ExampleStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    // Add the MCP server to your stack
+    new MyProjectMcpServer(this, 'MyProjectMcpServer');
+  }
+}
+```
+
+:::note[CDK Construct]
+This construct uses the [`aws-cdk-lib/aws-bedrockagentcore` module](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_bedrockagentcore-readme.html).
+:::
+</Fragment>
+<Fragment slot="terraform">
+A Terraform module is generated for you, named based on the `name` you chose when running the generator, or `<ProjectName>-mcp-server` by default.
+
+Pass the shared <Link path="/guides/runtime-config#writing-configuration">`runtime_config_appconfig`</Link> module's outputs into the MCP server module:
+
+```terraform
+module "my_project_mcp_server" {
+  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
+
+  appconfig_application_id  = module.runtime_config_appconfig.application_id
+  appconfig_application_arn = module.runtime_config_appconfig.application_arn
+}
+```
+</Fragment>
+</Infrastructure>
+
+:::caution[Docker Required]
+[Docker](https://www.docker.com/) is required to build and deploy your MCP server. Make sure you have installed and launched Docker to avoid errors such as:
+
+```
+ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.
+```
+:::
+
+### Authentication
+
+The generator provides an `auth` option to configure authentication for your MCP server. You can choose between `IAM` (default) or `Cognito` authentication when generating your MCP server.
+
+#### IAM
+
+By default, your MCP server will be secured using IAM authentication, simply deploy it without any arguments:
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts {5}
+import { MyProjectMcpServer } from ':my-scope/common-constructs';
+
+export class ExampleStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    new MyProjectMcpServer(this, 'MyProjectMcpServer');
+  }
+}
+```
+
+You can grant access to invoke your MCP server on Bedrock AgentCore Runtime using the `grantInvokeAccess` method. For example you may wish for an agent generated with the <Link path="/guides/py-agent">`py#agent`</Link> generator to call your MCP server:
+
+```ts {8}
+import { MyProjectAgent, MyProjectMcpServer } from ':my-scope/common-constructs';
+
+export class ExampleStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    const agent = new MyProjectAgent(this, 'MyProjectAgent');
+    const mcpServer = new MyProjectMcpServer(this, 'MyProjectMcpServer');
+
+    mcpServer.grantInvokeAccess(agent);
+  }
+}
+```
+</Fragment>
+<Fragment slot="terraform">
+```terraform {5-6}
+# MCP Server
+module "my_project_mcp_server" {
+  # Relative path to the generated module in the common/terraform project
+  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
+
+  appconfig_application_id  = module.runtime_config_appconfig.application_id
+  appconfig_application_arn = module.runtime_config_appconfig.application_arn
+}
+```
+
+To grant access to invoke your MCP server, you will need to add a policy such as the following, referencing the `module.my_project_mcp_server.agent_core_runtime_arn` output:
+
+```terraform
+{
+  Effect = "Allow"
+  Action = [
+    "bedrock-agentcore:InvokeAgentRuntime"
+  ]
+  Resource = [
+    module.my_project_mcp_server.agent_core_runtime_arn,
+    "${module.my_project_mcp_server.agent_core_runtime_arn}/*"
+  ]
+}
+```
+</Fragment>
+</Infrastructure>
+
+#### Cognito Authentication
+
+When you select `Cognito` authentication, the generator configures the MCP server to use Cognito for authentication.
+
+<Infrastructure>
+<Fragment slot="cdk">
+The generated construct accepts an `identity` prop which configures Cognito authentication:
+
+```ts {8}
+import { MyProjectMcpServer, UserIdentity } from ':my-scope/common-constructs';
+
+export class ExampleStack extends Stack {
+  constructor(scope: Construct, id: string) {
+    const identity = new UserIdentity(this, 'Identity');
+
+    new MyProjectMcpServer(this, 'MyProjectMcpServer', {
+      identity,
+    });
+  }
+}
+```
+
+The `UserIdentity` construct can be generated using the <Link path="/guides/react-website-auth">`ts#react-website#auth` generator</Link>, or you can create your own CDK `UserPool` and `UserPoolClient`.
+</Fragment>
+<Fragment slot="terraform">
+The generated module accepts `user_pool_id` and `user_pool_client_ids` variables for Cognito authentication:
+
+```terraform {8-9}
+module "user_identity" {
+  source = "../../common/terraform/src/core/user-identity"
+}
+
+module "my_project_mcp_server" {
+  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
+
+  appconfig_application_id  = module.runtime_config_appconfig.application_id
+  appconfig_application_arn = module.runtime_config_appconfig.application_arn
+
+  user_pool_id         = module.user_identity.user_pool_id
+  user_pool_client_ids = [module.user_identity.user_pool_client_id]
+}
+```
+</Fragment>
+</Infrastructure>
+
+:::note[Custom OIDC Providers]
+If you require custom JWT authentication with a non-Cognito OIDC provider, you can modify the generated CDK construct or Terraform module for your MCP server directly. Note that the connection generator will only support `IAM` or `Cognito` authentication.
+:::

package/docs/snippets/mcp/config.mdx

@@ -0,0 +1,13 @@
+---
+title: MCP Server Configuration
+---
+```json {3-6}
+{
+  "mcpServers": {
+    "nx-plugin-for-aws": {
+      "command": "npx",
+      "args": ["-y", "@aws/nx-plugin-mcp"]
+    }
+  }
+}
+```

package/docs/snippets/mcp/configuration-py.mdx

@@ -0,0 +1,42 @@
+---
+title: MCP Server Configuration
+---
+
+### Configuration Files
+
+Most AI assistants that support MCP use a similar configuration approach. You'll need to create or update a configuration file with your MCP server details:
+
+```json
+{
+  "mcpServers": {
+    "your-mcp-server": {
+      "command": "uv",
+      "args": [
+        "run",
+        "python",
+        "-m",
+        "my_module.mcp_server.stdio"
+      ],
+      "env": {
+        "VIRTUAL_ENV": "/path/to/your/project/.venv"
+      }
+    }
+  }
+}
+```
+
+:::caution[Path Resolution]
+If you receive an error such as `ENOENT uv` when connecting to your server, you might need to specify the full path to `uv`, which you can obtain by running `which uv` in your terminal.
+:::
+
+### Assistant-Specific Configuration
+
+Please refer to the following documentation for configuring MCP with specific AI Assistants:
+
+import Snippet from '@components/snippet.astro';
+
+<Snippet name="mcp/assistant-docs" />
+
+:::tip[Workspace Configuration]
+Some AI Assistants, such as Kiro, allow you to specify workspace level MCP server configuration, which is particularly useful for defining the relevant MCP servers for a particular project.
+:::

package/docs/snippets/mcp/configuration-ts.mdx

@@ -0,0 +1,53 @@
+---
+title: MCP Server Configuration
+---
+
+### Configuration Files
+
+Most AI assistants that support MCP use a similar configuration approach. You'll need to create or update a configuration file with your MCP server details:
+
+```json
+{
+  "mcpServers": {
+    "your-mcp-server": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/your-mcp-server/stdio.ts"]
+    }
+  }
+}
+```
+
+:::caution[Path Resolution]
+If you receive an error such as `ENOENT npx` when connecting to your server, you might need to specify the full path to `npx`, which you can obtain by running `which npx` in your terminal.
+:::
+
+### Hot Reload
+
+While developing your MCP server, you may wish to configure the `--watch` flag so that the AI assistant always sees the latest versions of tools/resources:
+
+```json {5}
+{
+  "mcpServers": {
+    "your-mcp-server": {
+      "command": "npx",
+      "args": ["tsx", "--watch", "/path/to/your-mcp-server/stdio.ts"]
+    }
+  }
+}
+```
+
+:::note[Refreshing Tools]
+If you add new tools or resources you may need to refresh your MCP server in the AI assistant.
+:::
+
+### Assistant-Specific Configuration
+
+Please refer to the following documentation for configuring MCP with specific AI Assistants:
+
+import Snippet from '@components/snippet.astro';
+
+<Snippet name="mcp/assistant-docs" />
+
+:::tip[Workspace Configuration]
+Some AI Assistants, such as Kiro, allow you to specify workspace level MCP server configuration, which is particularly useful for defining the relevant MCP servers for a particular project.
+:::

package/docs/snippets/mcp/observability.mdx

@@ -0,0 +1,8 @@
+---
+title: MCP Observability
+---
+Your MCP server is automatically configured with observability using the [AWS Distro for Open Telemetry](https://aws.amazon.com/otel/) (ADOT), by configuring auto-instrumentation in your `Dockerfile`.
+
+You can find traces in the CloudWatch AWS Console, by selecting "GenAI Observability" in the menu. Note that for traces to be populated you will need to enable [Transaction Search](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html).
+
+For more details, refer to the [AgentCore documentation on observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html).

package/docs/snippets/mcp/shared-constructs.mdx

@@ -0,0 +1,32 @@
+---
+title: MCP Shared Constructs
+---
+import { FileTree } from '@astrojs/starlight/components';
+import Infrastructure from '@components/infrastructure.astro';
+
+For deploying your MCP Server, the following files are generated:
+
+<Infrastructure>
+<Fragment slot="cdk">
+<FileTree>
+  - packages/common/constructs/src
+    - app
+      - mcp-servers
+        - \<project-name>
+          - \<project-name>.ts CDK construct for deploying your MCP Server
+          - Dockerfile Passthrough docker file used by the CDK construct
+</FileTree>
+</Fragment>
+<Fragment slot="terraform">
+<FileTree>
+  - packages/common/terraform/src
+    - app
+      - mcp-servers
+        - \<project-name>
+          - \<project-name>.tf Module for deploying your MCP Server
+    - core
+      - agent-core
+        - runtime.tf Generic module for deploying to Bedrock AgentCore Runtime
+</FileTree>
+</Fragment>
+</Infrastructure>