跳转到内容
@aws/nx-plugin
Blog

TypeScript MCP 服务器

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

什么是MCP？

Section titled “什么是MCP？”

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

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

使用方式

Section titled “使用方式”

生成MCP服务端

Section titled “生成MCP服务端”

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

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

    选项参数

    Section titled “选项参数”
    参数 类型 默认值 描述
    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 CDK The preferred IaC provider

    生成器输出

    Section titled “生成器输出”

    生成器将在现有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服务端运行目标

    基础设施

    Section titled “基础设施”

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

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

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

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

    • 文件夹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服务端

    Section titled “使用MCP服务端”

    添加工具

    Section titled “添加工具”

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

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

    添加资源

    Section titled “添加资源”

    资源为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助手

    Section titled “配置AI助手”

    配置文件

    Section titled “配置文件”

    大多数支持 MCP 的 AI 助手都采用相似的配置方式。您需要创建或更新包含 MCP 服务器详细信息的配置文件：

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

    热重载

    Section titled “热重载”

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

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

    特定助手配置

    Section titled “特定助手配置”

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

    运行MCP服务端

    Section titled “运行MCP服务端”

    检查器

    Section titled “检查器”

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

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

    检查器将运行在http://localhost:6274，点击”Connect”按钮即可开始使用。

    STDIO模式

    Section titled “STDIO模式”

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

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

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

    该命令使用tsx --watch实现文件变更时自动重启服务端。

    可流式HTTP模式

    Section titled “可流式HTTP模式”

    如需本地运行可流式HTTP传输的MCP服务端，可使用<your-server-name>-serve-http目标：

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

    该命令同样使用tsx --watch实现自动重启。

    部署至Bedrock AgentCore运行时

    Section titled “部署至Bedrock AgentCore运行时”

    基础设施即代码

    Section titled “基础设施即代码”

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

    系统会基于生成器运行时指定的name自动生成CDK构造（默认使用<ProjectName>McpServer命名）。

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

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

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

    认证机制

    Section titled “认证机制”

    IAM认证

    Section titled “IAM认证”

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

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

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

    您可以通过grantInvoke方法授予调用权限。例如，允许使用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);
      }
    }

    Cognito JWT认证

    Section titled “Cognito JWT认证”

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

    配置JWT认证时，可通过authorizerConfiguration属性传递参数。以下示例展示了如何配置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],
            },
          },
        });
      }
    }

    打包目标

    Section titled “打包目标”

    为构建适用于Bedrock AgentCore运行时的MCP服务端，项目中添加了<your-mcp-server>-bundle目标，该目标：

    • 使用esbuild将MCP服务端打包为单个JavaScript文件，以http.ts作为可流式HTTP MCP服务端的入口
    • 根据Dockerfile构建docker镜像，在端口8000运行打包后的服务端，符合MCP协议约定

    可观测性

    Section titled “可观测性”

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

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

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