TypeScript MCP Server

生成一个 TypeScript Model Context Protocol (MCP) 服务器，为大型语言模型（LLMs）提供上下文，并可选择将其部署到 Amazon Bedrock AgentCore。

什么是 MCP？

Model Context Protocol (MCP) 是一个开放标准，允许 AI 助手与外部工具和资源进行交互。它为 LLMs 提供了一种一致的方式来：

• 执行工具（函数）以执行操作或检索信息
• 访问提供上下文或数据的资源

使用方法

生成 MCP Server

您可以通过两种方式生成 TypeScript MCP 服务器：

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#mcp-server

yarn

yarn nx g @aws/nx-plugin:ts#mcp-server

npm

npx nx g @aws/nx-plugin:ts#mcp-server

bun

bunx nx g @aws/nx-plugin:ts#mcp-server

您还可以执行试运行以查看哪些文件会被更改

pnpm

pnpm nx g @aws/nx-plugin:ts#mcp-server --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#mcp-server --dry-run

npm

npx nx g @aws/nx-plugin:ts#mcp-server --dry-run

bun

bunx nx g @aws/nx-plugin:ts#mcp-server --dry-run

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - ts#mcp-server
5. 填写必需参数
6. 点击 Generate

项目前提条件

首先使用 ts#project 生成器创建一个项目，以便将您的 MCP 服务器添加到其中。

选项

参数	类型	默认值	描述
project 必需	string	-	要添加 MCP 服务器的项目
name	string	-	MCP 服务器的名称（默认：mcp-server）
auth	iam | cognito	iam	用于对 MCP 服务器进行身份验证的方法。仅在设置了 infra 时适用（当 infra 为 none 时忽略）。
iac	inherit | cdk | terraform	inherit	首选的 IaC 提供商。默认情况下，这继承自您的初始选择。
infra	agentcore | none	agentcore	托管 MCP 服务器的基础设施类型。选择 none 表示不托管。
preferInstallDependencies	boolean	true	是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

生成器将向您现有的 TypeScript 项目添加以下文件：

• 文件夹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 infra is set to None)
  • project.json Updated with MCP server serve target

基础设施

infra = agentcore

由于此生成器根据您选择的 iac 提供基础设施即代码，它将在 packages/common 中创建一个项目，其中包含相关的 CDK 构造或 Terraform 模块。

通用基础设施即代码项目的结构如下：

CDK

• 文件夹packages/common/constructs

  • 文件夹src

    • 文件夹app/ Constructs for infrastructure specific to a project/generator

      • …
    • 文件夹core/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Generated Project

此项目使用 ts#project 生成器生成，因此配置了相同的构建目标。

Terraform

• 文件夹packages/common/terraform

  • 文件夹src

    • 文件夹app/ Terraform modules for infrastructure specific to a project/generator

      • …
    • 文件夹core/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Generated Project

此项目使用 terraform#project 生成器生成，因此配置了相同的构建目标。

为了部署您的 MCP Server，会生成以下文件：

CDK

• 文件夹packages/common/constructs/src

  • 文件夹app

    • 文件夹mcp-servers

      • 文件夹<mcp-server-name>

        • <mcp-server-name>.ts CDK construct for deploying your MCP Server

Terraform

• 文件夹packages/common/terraform/src

  • 文件夹app

    • 文件夹mcp-servers

      • 文件夹<mcp-server-name>

        • <mcp-server-name>.tf Module for deploying your MCP Server
  • 文件夹core

    • 文件夹agent-core

      • runtime.tf Generic module for deploying to Bedrock AgentCore Runtime

infra = none

如果您为 infra 选择了 none，则不会生成 CDK 构造或 Terraform 模块 — MCP 服务器仅配置为本地 STDIO / HTTP 使用。在此模式下，auth 选项将被忽略，因为没有需要进行身份验证的托管端点。

架构

Bedrock AgentCore Runtime

当部署到 Bedrock AgentCore Runtime 时，MCP server 会被构建为容器镜像，推送到 Amazon ECR，并在 AgentCore Runtime 中运行。AI 助手调用 AgentCore Runtime 数据平面端点，该端点通过 streamable HTTP transport 将 tools/* 和 resources/* 调用转发到您的服务器。

None (local only)

使用 infra: none 时，不会生成 AWS 基础设施。MCP server 仅配置为本地 STDIO 和 HTTP 传输，并由运行在同一台机器上的 AI 助手使用。

使用您的 MCP Server

添加工具

工具是 AI 助手可以调用以执行操作的函数。每个工具都位于 tools/ 下的独立文件中，该文件导出一个 register<Name>Tool 函数，然后您从 server.ts 中调用它。例如，添加 tools/my-tool.ts：

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" }]
      };
    }
  );
};

然后在 server.ts 的 createServer 中注册它：

server.ts

import { registerMyTool } from './tools/my-tool.js';

export const createServer = async () => {
  const server = new McpServer({ name: 'my-server', version: '1.0.0' });

  registerMyTool(server);

  return server;
};

添加资源

资源为 AI 助手提供上下文。与工具类似，每个资源都位于 resources/ 下的独立文件中，该文件导出一个从 server.ts 调用的 register<Name>Resource 函数。您可以从文件添加静态资源或动态资源：

resources/my-resource.ts

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

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 }],
  }));

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

配置 AI 助手

配置文件

大多数支持 MCP 的 AI 助手使用类似的配置方法。您需要创建或更新配置文件，其中包含您的 MCP 服务器详细信息：

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "npx",
      "args": ["tsx", "/path/to/your-mcp-server/stdio.ts"]
    }
  }
}

路径解析

如果您在连接到服务器时收到诸如 ENOENT npx 之类的错误，您可能需要指定 npx 的完整路径，可以通过在终端中运行 which npx 来获取。

热重载

在开发 MCP 服务器时，您可能希望配置 --watch 标志，以便 AI 助手始终看到工具/资源的最新版本：

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "npx",
      "args": ["tsx", "--watch", "/path/to/your-mcp-server/stdio.ts"]
    }
  }
}

刷新工具

如果您添加了新的工具或资源，您可能需要在 AI 助手中刷新您的 MCP 服务器。

特定助手配置

请参阅以下文档以了解如何为特定 AI 助手配置 MCP：

• Kiro
• Kiro CLI
• Claude Code
• Cursor
• Codex
• Cline
• Roo Code

工作区配置

某些 AI 助手（例如 Kiro）允许您指定工作区级别的 MCP 服务器配置，这对于为特定项目定义相关的 MCP 服务器特别有用。

运行您的 MCP Server

本地开发

要在本地运行您的 MCP 服务器（以及与其连接的所有内容，例如本地数据库），请使用项目的 dev 目标：

pnpm

pnpm nx dev your-project

yarn

yarn nx dev your-project

npm

npx nx dev your-project

bun

bunx nx dev your-project

如果您已向项目添加了多个组件（MCP 服务器、代理等），这将启动所有组件。要仅运行此 MCP 服务器，请以其 <your-server-name>-dev 目标为目标：

pnpm

pnpm nx your-server-name-dev your-project

yarn

yarn nx your-server-name-dev your-project

npm

npx nx your-server-name-dev your-project

bun

bunx nx your-server-name-dev your-project

Inspector

生成器配置了一个名为 <your-server-name>-inspect 的目标，它会在本地启动您的 MCP 服务器（通过 <your-server-name>-dev 目标，包括任何连接的依赖项，例如本地数据库），并启动预配置为通过 Streamable HTTP 传输连接到它的 MCP Inspector。

pnpm

pnpm nx your-server-name-inspect your-project

yarn

yarn nx your-server-name-inspect your-project

npm

npx nx your-server-name-inspect your-project

bun

bunx nx your-server-name-inspect your-project

这将在 http://localhost:6274 启动检查器。点击”Connect”按钮开始使用。

提示

要使用 STDIO 传输检查服务器，请使用 <your-server-name>-inspect-stdio 目标，它会针对服务器的 STDIO 实例启动检查器。

STDIO

测试和使用 MCP 服务器的最简单方法是使用检查器或将其配置为 AI 助手（如上所述）。

但是，您可以使用 <your-server-name>-serve-stdio 目标直接使用 STDIO transport 运行服务器。

pnpm

pnpm nx your-server-name-serve-stdio your-project

yarn

yarn nx your-server-name-serve-stdio your-project

npm

npx nx your-server-name-serve-stdio your-project

bun

bunx nx your-server-name-serve-stdio your-project

此命令使用 tsx --watch 在文件更改时自动重启服务器。

Streamable HTTP

如果您想使用 Streamable HTTP transport 在本地运行 MCP 服务器，可以使用 <your-server-name>-serve 目标。

pnpm

pnpm nx your-server-name-serve your-project

yarn

yarn nx your-server-name-serve your-project

npm

npx nx your-server-name-serve your-project

bun

bunx nx your-server-name-serve your-project

此命令使用 tsx --watch 在文件更改时自动重启服务器。

infra = agentcore

将您的 MCP Server 部署到 Bedrock AgentCore Runtime

基础设施即代码

如果您为 infra 选择了 agentcore，将生成相关的 CDK 或 Terraform 基础设施，您可以使用它将 MCP 服务器部署到 Amazon Bedrock AgentCore Runtime。

CDK

将为您的 MCP Server 生成一个 CDK 构造，根据您运行生成器时选择的 name 命名，或默认为 <ProjectName>McpServer。

您可以在 CDK 应用程序中使用此 CDK 构造：

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');
  }
}

CDK 构造

此构造使用 aws-cdk-lib/aws-bedrockagentcore 模块。

Terraform

将为您生成一个 Terraform 模块，根据您运行生成器时选择的 name 命名，或默认为 <ProjectName>-mcp-server。

将共享的 runtime_config_appconfig 模块的输出传递到 MCP 服务器模块：

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
}

需要 Docker

构建和部署 MCP 服务器需要 Docker。请确保您已安装并启动 Docker 以避免以下错误：

ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.

身份验证

生成器提供了一个 auth 选项来配置 MCP 服务器的身份验证。在生成 MCP 服务器时，您可以在 IAM（默认）或 Cognito 身份验证之间进行选择。

IAM

默认情况下，您的 MCP 服务器将使用 IAM 身份验证进行保护，只需在不带任何参数的情况下部署它：

CDK

import { MyProjectMcpServer } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

您可以使用 grantInvokeAccess 方法授予在 Bedrock AgentCore Runtime 上调用 MCP 服务器的访问权限。例如，您可能希望使用 py#agent 生成器生成的代理来调用您的 MCP 服务器：

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);
  }
}

Terraform

# 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
}

要授予调用 MCP 服务器的访问权限，您需要添加如下策略，引用 module.my_project_mcp_server.agent_core_runtime_arn 输出：

{
  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}/*"
  ]
}

Cognito 身份验证

当您选择 Cognito 身份验证时，生成器会将 MCP 服务器配置为使用 Cognito 进行身份验证。

CDK

生成的构造接受一个 identity 属性，用于配置 Cognito 身份验证：

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,
    });
  }
}

UserIdentity 构造可以使用 ts#website#auth 生成器生成，或者您可以创建自己的 CDK UserPool 和 UserPoolClient。

Terraform

生成的模块接受 user_pool_id 和 user_pool_client_ids 变量用于 Cognito 身份验证：

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]
}

自定义 OIDC 提供商

如果您需要使用非 Cognito OIDC 提供商的自定义 JWT 身份验证，您可以直接修改为 MCP 服务器生成的 CDK 构造或 Terraform 模块。请注意，连接生成器仅支持 IAM 或 Cognito 身份验证。

安全最佳实践

在实现 MCP 服务器的业务逻辑时，请查看 Bedrock AgentCore Runtime 安全最佳实践。

Bundle 目标

生成器会自动配置一个 bundle 目标，它使用 Rolldown 来创建部署包：

pnpm

pnpm nx bundle <project-name>

yarn

yarn nx bundle <project-name>

npm

npx nx bundle <project-name>

bun

bunx nx bundle <project-name>

Rolldown 配置可以在 rolldown.config.ts 中找到，每个要生成的包都有一个入口。Rolldown 会管理并行创建多个包（如果已定义）。

自定义配置

您可以在 rolldown.config.ts 中调整 Rolldown 的配置，例如，如果您有依赖于文件路径且无法打包的依赖项，可以将它们添加到 external 模块列表中。

bundle 目标使用 http.ts 作为 Streamable HTTP MCP 服务器的入口点，以便在 Bedrock AgentCore Runtime 上托管。

Docker 目标

生成器配置了一个 <your-server-name>-docker 目标，它将 Dockerfile 从您的 MCP 服务器源目录复制到 bundle 输出目录。这将 Dockerfile 与打包的工件放在一起，允许 CDK 使用 AgentRuntimeArtifact.fromAsset 直接构建 Docker 镜像。

如果您定义了多个 MCP 服务器，还会生成一个 docker 目标，为所有 MCP 服务器准备 docker 上下文。

镜像扫描

为此项目构建的 Docker 镜像可以使用 Trivy 进行漏洞扫描，该工具从 ECR 托管的 Trivy 镜像运行。

项目中会添加一个 trivy 目标，用于扫描构建的镜像，如果发现任何 HIGH 或 CRITICAL 严重级别的漏洞，将以非零状态退出。生成的 Dockerfile 使用的基础镜像在生成时没有已知的可修复漏洞（这些严重级别），并升级捆绑的工具（如 npm）以保持这种状态。

扫描使用与镜像构建相同的容器引擎（docker 或 finch），因此不需要额外的工具。由于扫描仅在镜像更改时重新运行，未更改的镜像不会被重新扫描。提供的 trivy 根脚本会扫描工作区中的每个镜像：

pnpm

pnpm trivy

yarn

yarn trivy

npm

npm run trivy

bun

bun trivy

在 CI 中运行 Trivy

扫描故意不连接到 build，因为这可能会在开发过程中迭代时引入不必要的摩擦，因为 Trivy 的漏洞数据库会不断更新新的 CVE。

相反，我们建议在部署到生产阶段之前，在 CI 流水线中将上述命令作为专门的步骤运行。

忽略无法修复的漏洞

扫描使用 --ignore-unfixed 运行，因此没有可用修复的漏洞不会导致构建失败，因为它们无法通过升级 Dockerfile 中的工具来解决——它们不会在构建的扫描输出中报告。随着新漏洞的披露，扫描结果可能会随时间而变化，因此请通过运行 trivy image <your-image>（不带该标志）定期检查镜像，并在发布修复后针对更新的基础镜像重新构建（或添加容器步骤以应用可用的补丁）。

抑制 Trivy 发现

在某些情况下，您可能希望抑制特定的漏洞，例如当尚无可用修复且您已评估风险为可接受时。

将漏洞 ID（每行一个）添加到项目根目录中的 .trivyignore 文件（即 project.json 旁边）：

.trivyignore

# node-tar arbitrary file write - not exploitable in our usage
CVE-2024-XXXXX

有关过滤发现的更多详细信息，请参阅 Trivy 过滤文档。

可观测性

您的 MCP 服务器通过在 Dockerfile 中配置自动检测，使用 AWS Distro for Open Telemetry (ADOT) 自动配置了可观测性。

您可以在 CloudWatch AWS 控制台中找到跟踪信息，方法是在菜单中选择”GenAI Observability”。请注意，要填充跟踪信息，您需要启用 Transaction Search。

有关更多详细信息，请参阅 AgentCore 可观测性文档。

连接

使用 connection 生成器将此项目与工作区中的其他项目集成。以下连接涉及此项目：

TypeScript Agent to MCPConnect a TypeScript Agent to an MCP server

Python Agent to MCPConnect a Python Agent to an MCP server

MCP Server to Relational DatabaseConnect a TypeScript MCP Server to an Aurora relational database

MCP Server to TypeScript DynamoDBConnect a TypeScript MCP Server to a DynamoDB table

AgentCore Gateway to MCP ServerAggregate an MCP server behind an AgentCore Gateway