Skip to content
@aws/nx-plugin
Blog

ts#mcp-server

TypeScript MCP Server Generator

Generate a TypeScript Model Context Protocol (MCP) server for providing context to Large Language Models (LLMs).

What is MCP?

The Model Context Protocol (MCP) 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:

  1. Install the Nx Console VSCode Plugin if you haven't already
  2. Open the Nx Console in VSCode
  3. Click Generate (UI) in the "Common Nx Commands" section
  4. Search for @aws/nx-plugin - ts#mcp-server
  5. Fill in the required parameters
    • Click Generate

    Options

    Parameter Type Default Description
    name Required string - MCP server project name.
    directory string packages Parent directory where the MCP server is placed.
    subDirectory string - The sub directory the MCP server is placed in. By default this is the MCP server project name.

    Generator Output

    The generator will create the following project files:

    • Directorypackages/<name>/
      • README.md Documentation for the MCP server with usage instructions
      • project.json Nx project configuration with build, bundle, and dev targets
      • Directorysrc/
        • index.ts Entry point for the MCP server
        • server.ts Main server definition, defining tools and resources
        • global.d.ts TypeScript type declarations for importing markdown files
        • Directoryresources/
          • example-context.md Example markdown file used as a resource for the MCP server

    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:

    server.tool("toolName",
      { 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:

    // Static resource from a file
    import exampleContext from './resources/example-context.md';
    

    server.resource('resource-name', 'example://resource', async (uri) => ({
      contents: [{ uri: uri.href, text: exampleContext }],
    }));
    

    // Dynamic resource
    server.resource('dynamic-resource', 'dynamic://resource', async (uri) => {
      const data = await fetchSomeData();
      return {
        contents: [{ uri: uri.href, text: data }],
      };
    });

    Configuring with AI Assistants

    To use your MCP server with AI assistants, you need to bundle it first:

    Terminal window
    pnpm nx run your-mcp-server:bundle

    This creates a bundled version in dist/packages/your-mcp-server/bundle/index.js (path may vary based on your directory settings).

    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:

    {
      "mcpServers": {
        "your-mcp-server": {
          "command": "node",
          "args": [
            "/path/to/workspace/dist/packages/your-mcp-server/bundle/index.js"
          ],
          "transportType": "stdio"
        }
      }
    }

    Replace /path/to/workspace/dist/packages/your-mcp-server/bundle/index.js with the actual path to your bundled MCP server.

    Assistant-Specific Configuration

    Please refer to the following documentation for configuring MCP with specific AI Assistants:

    Development Workflow

    Build Targets

    The generator is built on top of the TypeScript project generator and as such inherits its targets, as well as adding the following additional targets:

    Bundle

    The bundle task uses esbuild to create a single bundled JavaScript file that can be used with AI assistants:

    Terminal window
    pnpm nx run your-mcp-server:bundle

    This creates a bundled version in dist/packages/your-mcp-server/bundle/index.js (path may vary based on your directory settings).

    Dev

    The dev task watches for changes in your project and automatically rebuilds the bundle:

    Terminal window
    pnpm nx run your-mcp-server:dev

    This is particularly useful during development as it ensures your AI Assistant utilises the latest version of your MCP server.