@aws/nx-plugin-mcp 0.119.0 → 0.121.0

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

@@ -0,0 +1,169 @@
+---
+title: TypeScript MCP Server
+description: Generate a TypeScript Model Context Protocol (MCP) server for providing context to Large Language Models
+generator: ts#mcp-server
+---
+
+import { FileTree } from '@astrojs/starlight/components';
+import RunGenerator from '@components/run-generator.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Link from '@components/link.astro';
+import Snippet from '@components/snippet.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import OptionFilter from '@components/option-filter.astro';
+
+Generate a TypeScript [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for providing context to Large Language Models (LLMs), and optionally deploy it to [Amazon Bedrock AgentCore](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/).
+
+## What is MCP?
+
+The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that allows AI assistants to interact with external tools and resources. It provides a consistent way for LLMs to:
+
+- Execute tools (functions) that perform actions or retrieve information
+- Access resources that provide context or data
+
+## Usage
+
+### Generate an MCP Server
+
+You can generate a TypeScript MCP server in two ways:
+
+<RunGenerator generator="ts#mcp-server" />
+
+:::tip[Project Prerequisite]
+First use the <Link path="/guides/typescript-project">`ts#project`</Link> generator to create a project to add your MCP server to.
+:::
+
+### Options
+
+<GeneratorParameters generator="ts#mcp-server" />
+
+## Generator Output
+
+The generator will add the following files to your existing TypeScript project:
+
+<FileTree>
+  - your-project/
+    - src/
+      - mcp-server/ (or custom name if specified)
+        - index.ts Exports your server
+        - server.ts Main server definition
+        - stdio.ts Entry point for STDIO transport, useful for simple local MCP servers
+        - http.ts Entry point for Streamable HTTP transport, useful for hosting your MCP server
+        - tools/
+          - divide.ts Sample tool
+        - resources/
+          - sample-guidance.ts Sample resource
+        - Dockerfile Entry point for hosting your MCP server (excluded when `computeType` is set to `None`)
+    - package.json Updated with bin entry and MCP dependencies
+    - project.json Updated with MCP server serve target
+</FileTree>
+
+### Infrastructure
+
+<OptionFilter when={{ computeType: 'BedrockAgentCoreRuntime' }} description="Bedrock AgentCore Runtime deployment">
+<Snippet name="shared-constructs" />
+
+<Snippet name="mcp/shared-constructs" />
+</OptionFilter>
+
+<OptionFilter when={{ computeType: 'None' }} description="No infrastructure is vended for computeType=None">
+If you selected `None` for `computeType`, no CDK constructs or Terraform modules are generated — the MCP server is configured for local STDIO / HTTP use only. The `auth` option is ignored in this mode since there is no hosted endpoint to authenticate.
+</OptionFilter>
+
+#### Architecture
+
+<Snippet name="mcp/architecture" />
+
+## Working with Your MCP Server
+
+### 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" }]
+    };
+  }
+);
+```
+
+### Adding Resources
+
+Resources provide context to the AI assistant. You can add static resources from files or dynamic resources:
+
+```typescript
+const exampleContext = 'some context to return';
+
+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 }],
+  };
+});
+```
+
+## Configuring with AI Assistants
+
+<Snippet name="mcp/configuration-ts" parentHeading="Configuring with AI Assistants" />
+
+## Running Your MCP Server
+
+### Inspector
+
+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.
+
+<NxCommands commands={['your-server-name-inspect your-project']} />
+
+This will start the inspector at `http://localhost:6274`. Get started by clicking on the "Connect" button.
+
+### STDIO
+
+The easiest way to test and use an MCP server is by using the inspector or configuring it with an AI assistant (as above).
+
+You can however run your server with [STDIO transport](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio) directly using the `<your-server-name>-serve-stdio` target.
+
+<NxCommands commands={['your-server-name-serve-stdio your-project']} />
+
+This command uses `tsx --watch` to automatically restart the server when files change.
+
+### Streamable HTTP
+
+If you would like to run your MCP server locally using [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http), you can use the `<your-server-name>-serve` target.
+
+<NxCommands commands={['your-server-name-serve your-project']} />
+
+This command uses `tsx --watch` to automatically restart the server when files change.
+
+<OptionFilter when={{ computeType: 'BedrockAgentCoreRuntime' }} description="Bedrock AgentCore Runtime deployment details">
+## Deploying Your MCP Server to Bedrock AgentCore Runtime
+
+<Snippet name="mcp/bedrock-deployment" parentHeading="Deploying Your MCP Server to Bedrock AgentCore Runtime" />
+
+### Bundle Target
+
+<Snippet name="ts-bundle" />
+
+The bundle target uses `http.ts` as the entrypoint for the Streamable HTTP MCP server to host on Bedrock AgentCore Runtime.
+
+### Docker Target
+
+The generator configures a `<your-server-name>-docker` target which copies the `Dockerfile` from your MCP server source directory into the bundle output directory. This co-locates the `Dockerfile` with the bundled artifacts, allowing CDK to build the Docker image directly using `AgentRuntimeArtifact.fromAsset`.
+
+A `docker` target is also generated which prepares the docker context for all MCP servers if you have multiple defined.
+
+### Observability
+
+<Snippet name="mcp/observability" parentHeading="Observability" />
+</OptionFilter>

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

@@ -0,0 +1,159 @@
+---
+title: TypeScript Nx Plugin
+description: Generate an Nx Plugin of your own! Build custom generators automatically made available for AI vibe-coding via MCP
+generator: ts#nx-plugin
+---
+
+import { FileTree } from '@astrojs/starlight/components';
+import RunGenerator from '@components/run-generator.astro';
+import NxCommands from '@components/nx-commands.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import Link from '@components/link.astro';
+import Snippet from '@components/snippet.astro';
+import InstallCommand from '@components/install-command.astro';
+
+Generate a complete TypeScript [Nx Plugin](https://nx.dev/extending-nx/intro/getting-started) with an integrated [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server. This generator creates a foundation for building custom generators that can be seamlessly used by AI assistants for automated code generation and project scaffolding.
+
+## Usage
+
+### Generate an Nx Plugin
+
+You can generate a TypeScript Nx Plugin in two ways:
+
+<RunGenerator generator="ts#nx-plugin" />
+
+### Options
+
+<GeneratorParameters generator="ts#nx-plugin" />
+
+## Generator Output
+
+The generator will create the following project structure:
+
+<FileTree>
+- your-plugin/
+  - src/
+    - index.ts Empty entry point for your plugin
+    - mcp-server/
+      - index.ts Exports your server
+      - server.ts Main MCP server configuration
+      - stdio.ts Entry point for your MCP server with STDIO transport
+      - http.ts Entry point for your MCP server with Streamable HTTP transport
+      - tools/
+        - create-workspace-command.ts Tool for workspace creation guidance
+        - general-guidance.ts Tool for general Nx and plugin guidance
+        - list-generators.ts Tool to list available generators
+        - generator-guide.ts Tool for detailed generator information
+      - utils.ts Utility functions for the MCP server
+  - generators.json Nx generator configuration (initially empty)
+  - package.json Plugin package configuration with MCP server binary
+  - tsconfig.json TypeScript configuration (CommonJS for Nx compatibility)
+  - project.json Nx project configuration with build and package targets
+</FileTree>
+
+## Working with Your Nx Plugin
+
+### 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:
+
+<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.
+:::
+
+Make sure to write a detailed `README.md` for your generator, since this is used by the MCP Server's `generator-guide` tool.
+
+### Project Targets
+
+The generated plugin includes several important targets:
+
+#### Build Target
+Compiles your TypeScript code and prepares the plugin for use:
+
+<NxCommands commands={['build your-plugin']} />
+
+#### Package Target
+Creates a distributable package ready for NPM publishing:
+
+<NxCommands commands={['package your-plugin']} />
+
+The package target includes all necessary assets:
+- Compiled JavaScript files
+- TypeScript declaration files
+- Generator and executor configuration files
+- Documentation and license files
+
+## MCP Server Integration
+
+The plugin configures an MCP server using the <Link path="/guides/ts-mcp-server">`ts#mcp-server`</Link> generator.
+
+### Tools
+
+The plugin includes a complete MCP server that provides AI assistants the following tools:
+
+- `general-guidance`: Get best practices for working with Nx and your plugin
+- `create-workspace-command`: Learn how to create new workspaces that can use your plugin
+- `list-generators`: List all available generators in your plugin
+- `generator-guide`: Get detailed information about specific generators including schemas and usage
+
+### Configuring with AI Assistants
+
+<Snippet name="mcp/configuration-ts" parentHeading="Configuring with AI Assistants" />
+
+### Customizing the MCP Server
+
+You can extend the MCP server by modifying `server.ts` to add additional tools or resources specific to your plugin's domain.
+
+For more details about writing MCP Servers, refer to the <Link path="/guides/ts-mcp-server">`ts#mcp-server` guide</Link>.
+
+## Publishing Your Plugin
+
+### Preparing for Publication
+
+1. **Update Package Information**: Edit your plugin's [`package.json`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json) with proper name, version, description, and repository information.
+
+2. **Build the Package**:
+   <NxCommands commands={['package your-plugin']} />
+
+3. **Test Locally**: You can test your plugin locally by installing it in another workspace:
+   ```bash
+   npm install /path/to/your/workspace/dist/your-plugin/package
+   ```
+
+### Publishing to NPM
+
+Once your plugin is ready:
+
+```bash
+cd dist/your-plugin/package
+npm publish
+```
+
+### Using Published Plugins
+
+After publishing, others can install and use your plugin:
+
+<InstallCommand pkg="your-plugin-name" />
+
+Then use your generators:
+
+<RunGenerator namespace="your-plugin-name" generator="your-generator-name" />
+
+#### Configure AI Assistants with your Published Plugin
+
+Your published plugin's MCP server can be configured as follows:
+
+```json {3-6}
+{
+  "mcpServers": {
+    "aws-nx-mcp": {
+      "command": "npx",
+      "args": ["-y", "-p", "your-plugin-name", "your-plugin-name-mcp-server"]
+    }
+  }
+}
+```