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	-	The project to add an MCP server to
computeType	string	BedrockAgentCoreRuntime	The type of compute to host your MCP server. Select None for no hosting.
name	string	-	The name of your MCP server (default: mcp-server)
iacProvider	string	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

生成器输出

生成器将在现有 TypeScript 项目中添加以下文件：

文件夹your-project/
- 文件夹src/
  - 文件夹mcp-server/ (或自定义名称)
    index.ts 导出服务器
    server.ts 主服务器定义
    stdio.ts STDIO 传输入口，适用于本地简单 MCP 服务器
    http.ts 流式 HTTP 传输入口，适用于托管 MCP 服务器
    文件夹tools/
    add.ts 示例工具
    文件夹resources/
    sample-guidance.ts 示例资源
    Dockerfile MCP 服务器托管入口（当 computeType 设为 None 时排除）
- package.json 更新 bin 条目和 MCP 依赖
- 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 文件
- 文件夹core
  - 文件夹agent-core
    runtime.ts 用于部署到 Bedrock AgentCore Runtime 的通用 CDK 构造

使用 MCP 服务器

添加工具

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

server.tool("工具名称", "工具描述",
  { 参数1: z.string(), 参数2: z.number() }, // 使用 Zod 的输入模式
  async ({ 参数1, 参数2 }) => {
    // 工具实现
    return {
      content: [{ type: "text", text: "结果" }]
    };
  }
);

当前 MCP SDK 仅支持 Zod v3。为了允许其他生成器使用 Zod v4，Zod v3 依赖以 zod-v3 名称安装。对于 MCP 工具模式，需按以下方式导入 Zod：

import { z } from 'zod-v3';

待 MCP SDK 此问题解决后，可移除 zod-v3 依赖并直接导入 zod。

添加资源

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

const 示例上下文 = '要返回的上下文内容';

server.resource('资源名称', 'example://resource', async (uri) => ({
  contents: [{ uri: uri.href, text: 示例上下文 }],
}));

// 动态资源
server.resource('动态资源', 'dynamic://resource', async (uri) => {
  const 数据 = await 获取数据();
  return {
    contents: [{ uri: uri.href, text: 数据 }],
  };
});

配置 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 服务器

检查器

生成器配置了名为 <your-server-name>-inspect 的目标，用于启动 MCP 检查器并通过 STDIO 传输连接到您的 MCP 服务器。

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

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

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

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

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

STDIO 传输

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

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

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

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

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

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

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

流式 HTTP 传输

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

pnpm nx run your-project:your-server-name-serve-http

yarn nx run your-project:your-server-name-serve-http

npx nx run your-project:your-server-name-serve-http

bunx nx run your-project:your-server-name-serve-http

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

部署到 Bedrock AgentCore 运行时

基础设施即代码

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

CDK
Terraform

系统会基于生成器运行时指定的 name（默认为 <ProjectName>McpServer）生成一个 CDK 构造。

您可以在 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 模块。

您可以在 Terraform 项目中使用该模块：

# MCP 服务器
module "my_project_mcp_server" {
  # 指向 common/terraform 项目中生成模块的相对路径
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

认证

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

您可以使用 grantInvoke 方法授予调用 Bedrock AgentCore Runtime 上 MCP 的权限。例如，您可能希望允许通过 py#strands-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.agentCoreRuntime.grantInvoke(agent.agentCoreRuntime);
  }
}

# MCP 服务器
module "my_project_mcp_server" {
  # 指向 common/terraform 项目中生成模块的相对路径
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

要授予调用权限，您需要添加如下策略，并引用 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 JWT 认证

以下演示如何为代理配置 Cognito 认证。

CDK
Terraform

要配置 JWT 认证，您可以通过 authorizerConfiguration 属性传递给 MCP 服务器构造。以下示例配置了 Cognito 用户池和客户端来保护 MCP 服务器：

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const userPool = new UserPool(this, 'UserPool');
    const client = userPool.addClient('Client', {
      authFlows: {
        userPassword: true,
      },
    });

    new MyProjectMcpServer(this, 'MyProjectMcpServer', {
      authorizerConfiguration: {
        customJwtAuthorizer: {
          discoveryUrl: `https://cognito-idp.${Stack.of(userPool).region}.amazonaws.com/${userPool.userPoolId}/.well-known/openid-configuration`,
          allowedClients: [client.userPoolClientId],
        },
      },
    });
  }
}

要配置 JWT 认证，您可以编辑 MCP 服务器模块来配置 customJWTAuthorizer 变量：

data "aws_region" "current" {}

locals {
  aws_region = data.aws_region.current.name

  # 替换为您的用户池和客户端 ID，或通过变量暴露
  user_pool_id = "xxx"
  user_pool_client_ids = ["yyy"]
}

module "agent_core_runtime" {
  source = "../../../core/agent-core"
  agent_runtime_name = "MyProjectMcpServer"
  docker_image_tag = "my-scope-my-project-agent:latest"
  server_protocol = "MCP"
  customJWTAuthorizer = {
    discoveryUrl = "https://cognito-idp.${local.aws_region}.amazonaws.com/${local.user_pool_id}/.well-known/openid-configuration",
    allowedClients = local.user_pool_client_ids
  }
  env = var.env
  additional_iam_policy_statements = var.additional_iam_policy_statements
  tags = var.tags
}

打包目标

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

pnpm nx run <project-name>:bundle

yarn nx run <project-name>:bundle

npx nx run <project-name>:bundle

bunx nx run <project-name>:bundle

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

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

Docker 目标

生成器配置了 <your-server-name>-docker 目标，该目标根据 MCP 协议约定在端口 8000 上运行打包后的流式 HTTP MCP 服务器。

若定义了多个 MCP 服务器，还会生成 docker 目标来执行所有 MCP 服务器的 Docker 构建。

可观测性

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

您可以在CloudWatch AWS控制台的菜单中选择”GenAI Observability”查看追踪数据。注意：要使追踪数据正常显示，需先启用Transaction Search功能。

更多详细信息，请参考AgentCore可观测性配置文档。