TypeScript MCP 服务器

生成一个 TypeScript 模型上下文协议（MCP）服务器，用于为大型语言模型（LLM）提供上下文，并可选择部署到 Amazon Bedrock AgentCore。

什么是 MCP？

模型上下文协议（MCP）是一个开放标准，允许 AI 助手与外部工具和资源交互。它为 LLM 提供了一致的方式来：

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

使用方式

生成 MCP 服务器

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

VSCode
CLI

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

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

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

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

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

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

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

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

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

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

选项

参数	类型	默认值	描述
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/ (或自定义名称)
    index.ts 导出服务器
    server.ts 主服务器定义
    stdio.ts STDIO 传输入口，适用于本地简单 MCP 服务器
    http.ts 流式 HTTP 传输入口，适用于托管 MCP 服务器
    文件夹tools/
    divide.ts 示例工具
    文件夹resources/
    sample-guidance.ts 示例资源
    Dockerfile MCP 服务器托管入口（当 infra 设为 None 时排除）
- project.json 更新 MCP 服务器服务目标

基础设施

由于该生成器会根据您选择的 iacProvider 以基础设施即代码的形式输出，它将在 packages/common 目录下创建一个包含相关 CDK 构造体或 Terraform 模块的项目。

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

CDK
Terraform

文件夹packages/common/constructs
- 文件夹src
  - 文件夹app/ 针对特定项目/生成器的基础设施构造体
    …
  - 文件夹core/ 被 app 目录构造体重用的通用构造体
    …
  - index.ts 导出 app 目录构造体的入口文件
- project.json 项目构建目标与配置

文件夹packages/common/terraform
- 文件夹src
  - 文件夹app/ 针对特定项目/生成器的 Terraform 模块
    …
  - 文件夹core/ 被 app 目录模块重用的通用模块
    …
- project.json 项目构建目标与配置

部署 MCP 服务器时将会生成以下文件：

CDK
Terraform

文件夹packages/common/constructs/src
- 文件夹app
  - 文件夹mcp-servers
    文件夹<project-name>
    <project-name>.ts 用于部署 MCP 服务器的 CDK 构造
    Dockerfile CDK 构造使用的直通式 docker 文件

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

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

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

使用 MCP 服务器

添加工具

工具是 AI 助手可以调用的函数。您可以在 server.ts 文件中添加新工具：

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

添加资源

资源为 AI 助手提供上下文。您可以从文件添加静态资源或动态资源：

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

热重载

在开发 MCP 服务器时，建议配置 --watch 参数以确保 AI 助手始终获取工具/资源的最新版本：

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

特定助手配置

请参考以下文档配置不同 AI 助手的 MCP 设置：

运行 MCP 服务器

本地开发

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

pnpm nx dev your-project

yarn nx dev your-project

npx nx dev your-project

bunx nx dev your-project

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

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

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

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

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

检查器

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

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

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

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

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

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

STDIO 传输

测试和使用 MCP 服务器最简单的方式是使用检查器或按上述方式配置 AI 助手。

您也可以直接通过 <your-server-name>-serve-stdio 目标使用 STDIO 传输运行服务器：

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

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

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

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

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

流式 HTTP 传输

若需通过流式 HTTP 传输在本地运行 MCP 服务器，可使用 <your-server-name>-serve 目标：

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

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

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

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

此命令同样使用 tsx --watch 自动重启服务器。

部署到 Bedrock AgentCore 运行时

基础设施即代码

如果您为 infra 选择了 agentcore，系统会生成相应的 CDK 或 Terraform 基础设施代码，您可以用其将 MCP 服务器部署到 Amazon Bedrock AgentCore Runtime。

CDK
Terraform

系统会为您的 MCP 服务器生成一个 CDK 构造，其名称基于生成器运行时指定的 name（默认为 <ProjectName>McpServer）。

您可以在 CDK 应用中使用该 CDK 构造：

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // 将 MCP 服务器添加到您的堆栈
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

系统会基于生成器运行时指定的 name（默认为 <ProjectName>-mcp-server）生成一个 Terraform 模块。

将共享的 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
}

认证

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

IAM 认证

默认情况下，您的 MCP 服务器将使用 IAM 认证进行保护，直接部署时无需额外参数：

CDK
Terraform

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

# MCP 服务器
module "my_project_mcp_server" {
  # 指向 common/terraform 项目中生成模块的相对路径
  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
Terraform

生成的构造接受一个 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。

生成的模块接受 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]
}

打包目标

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

pnpm nx bundle <project-name>

yarn nx bundle <project-name>

npx nx bundle <project-name>

bunx nx bundle <project-name>

Rolldown 配置位于 rolldown.config.ts 文件中，每个要生成的包都有对应的入口配置。如果定义了多个包，Rolldown 会并行管理这些包的创建过程。

打包目标使用 http.ts 作为入口点，用于在 Bedrock AgentCore 运行时托管流式 HTTP MCP 服务器。

Docker 目标

生成器配置了 <your-server-name>-docker 目标，该目标将 Dockerfile 从 MCP 服务器源目录复制到打包输出目录中。这样可以将 Dockerfile 与打包后的构件共存，允许 CDK 直接使用 AgentRuntimeArtifact.fromAsset 构建 Docker 镜像。

若定义了多个 MCP 服务器，还会生成 docker 目标来为所有 MCP 服务器准备 Docker 上下文。

镜像扫描

为此项目构建的 Docker 镜像会在构建过程中使用 Trivy 进行漏洞扫描，运行来自 ECR 托管的 Trivy 镜像。

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

扫描使用与镜像构建相同的容器引擎（docker 或 finch），因此不需要额外的工具。由于扫描仅在镜像更改时重新运行，未更改的镜像不会被重新扫描。

抑制 Trivy 发现

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

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

# 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 MCP将 TypeScript Agent 连接到 MCP 服务器

Python Agent to MCP将 Python Agent 连接到 MCP 服务器

MCP Server to Relational Database将 TypeScript MCP Server 连接到 Aurora 关系数据库

MCP Server to TypeScript DynamoDB将 TypeScript MCP Server 连接到 DynamoDB 表

AgentCore Gateway to MCP Server在 AgentCore Gateway 后聚合 MCP 服务器