Máy chủ MCP TypeScript

Tạo một máy chủ Model Context Protocol (MCP) TypeScript để cung cấp ngữ cảnh cho các Mô hình Ngôn ngữ Lớn (LLMs), và tùy chọn triển khai nó lên Amazon Bedrock AgentCore.

MCP là gì?

Model Context Protocol (MCP) là một tiêu chuẩn mở cho phép các trợ lý AI tương tác với các công cụ và tài nguyên bên ngoài. Nó cung cấp một cách nhất quán để LLMs có thể:

• Thực thi các công cụ (hàm) để thực hiện các hành động hoặc truy xuất thông tin
• Truy cập các tài nguyên cung cấp ngữ cảnh hoặc dữ liệu

Cách sử dụng

Tạo một Máy chủ MCP

Bạn có thể tạo một máy chủ MCP TypeScript theo hai cách:

VSCode

1. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - ts#mcp-server
5. Điền các tham số bắt buộc
6. Nhấp Generate

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

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

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

Điều kiện tiên quyết dự án

Đầu tiên hãy sử dụng generator ts#project để tạo một dự án để thêm máy chủ MCP của bạn vào.

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
project Bắt buộc	string	-	Dự án để thêm MCP server vào
computeType	string	BedrockAgentCoreRuntime	Loại compute để host MCP server của bạn. Chọn None nếu không cần hosting.
name	string	-	Tên của MCP server của bạn (mặc định: mcp-server)
auth	string	IAM	Phương thức được sử dụng để xác thực với MCP server của bạn. Chọn giữa IAM (mặc định) hoặc Cognito.
iacProvider	string	Inherit	Nhà cung cấp IaC ưa thích. Mặc định được kế thừa từ lựa chọn ban đầu của bạn.

Kết quả của Generator

Generator sẽ thêm các tệp sau vào dự án TypeScript hiện có của bạn:

• Thư mụcyour-project/

  • Thư mụcsrc/

    • Thư mụcmcp-server/ (hoặc tên tùy chỉnh nếu được chỉ định)

      • index.ts Xuất máy chủ của bạn
      • server.ts Định nghĩa máy chủ chính
      • stdio.ts Điểm vào cho STDIO transport, hữu ích cho các máy chủ MCP cục bộ đơn giản
      • http.ts Điểm vào cho Streamable HTTP transport, hữu ích cho việc lưu trữ máy chủ MCP của bạn
      • Thư mụctools/

        • divide.ts Công cụ mẫu
      • Thư mụcresources/

        • sample-guidance.ts Tài nguyên mẫu
      • Dockerfile Điểm vào cho việc lưu trữ máy chủ MCP của bạn (loại trừ khi computeType được đặt thành None)
  • package.json Được cập nhật với mục bin và các phụ thuộc MCP
  • project.json Được cập nhật với target serve của máy chủ MCP

Cơ sở hạ tầng

Triển khai serverless

Nếu bạn chọn None cho computeType, generator sẽ không tạo bất kỳ infrastructure as code nào.

Vì generator này cung cấp infrastructure as code dựa trên iacProvider bạn đã chọn, nó sẽ tạo một dự án trong packages/common bao gồm các CDK constructs hoặc Terraform modules liên quan.

Dự án infrastructure as code chung được cấu trúc như sau:

CDK

• Thư mụcpackages/common/constructs

  • Thư mụcsrc

    • Thư mụcapp/ Constructs cho infrastructure cụ thể của một dự án/generator

      • …
    • Thư mụccore/ Constructs chung được tái sử dụng bởi các constructs trong app

      • …
    • index.ts Entry point xuất các constructs từ app
  • project.json Các build targets và cấu hình của dự án

Dự án được tạo

Dự án này được tạo bằng generator ts#project và do đó cấu hình các build targets giống nhau.

Terraform

• Thư mụcpackages/common/terraform

  • Thư mụcsrc

    • Thư mụcapp/ Terraform modules cho infrastructure cụ thể của một dự án/generator

      • …
    • Thư mụccore/ Modules chung được tái sử dụng bởi các modules trong app

      • …
  • project.json Các build targets và cấu hình của dự án

Dự án được tạo

Dự án này được tạo bằng generator terraform#project và do đó cấu hình các build targets giống nhau.

Để triển khai MCP Server của bạn, các tệp sau được tạo ra:

CDK

• Thư mụcpackages/common/constructs/src

  • Thư mụcapp

    • Thư mụcmcp-servers

      • Thư mục<project-name>

        • <project-name>.ts CDK construct để triển khai MCP Server của bạn
        • Dockerfile Tệp docker passthrough được sử dụng bởi CDK construct

Terraform

• Thư mụcpackages/common/terraform/src

  • Thư mụcapp

    • Thư mụcmcp-servers

      • Thư mục<project-name>

        • <project-name>.tf Module để triển khai MCP Server của bạn
  • Thư mụccore

    • Thư mụcagent-core

      • runtime.tf Module chung để triển khai lên Bedrock AgentCore Runtime

Làm việc với Máy chủ MCP của bạn

Thêm Công cụ

Công cụ là các hàm mà trợ lý AI có thể gọi để thực hiện các hành động. Bạn có thể thêm các công cụ mới trong tệp server.ts:

server.registerTool("toolName", {
  description: "tool description",
  inputSchema: { param1: z.string(), param2: z.number() } // Input schema sử dụng Zod
},
  async ({ param1, param2 }) => {
    // Triển khai công cụ
    return {
      content: [{ type: "text", text: "Result" }]
    };
  }
);

Thêm Tài nguyên

Tài nguyên cung cấp ngữ cảnh cho trợ lý AI. Bạn có thể thêm các tài nguyên tĩnh từ tệp hoặc tài nguyên động:

const exampleContext = 'some context to return';

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

// Tài nguyên động
server.registerResource('dynamic-resource', 'dynamic://resource', {}, async (uri) => {
  const data = await fetchSomeData();
  return {
    contents: [{ uri: uri.href, text: data }],
  };
});

Cấu hình với Trợ lý AI

Tệp Cấu Hình

Hầu hết các trợ lý AI hỗ trợ MCP đều sử dụng phương pháp cấu hình tương tự. Bạn sẽ cần tạo hoặc cập nhật tệp cấu hình với thông tin chi tiết về MCP server của bạn:

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

Giải quyết đường dẫn

Nếu bạn nhận được lỗi như ENOENT npx khi kết nối với server của bạn, bạn có thể cần chỉ định đường dẫn đầy đủ đến npx, bạn có thể lấy đường dẫn này bằng cách chạy lệnh which npx trong terminal của bạn.

Hot Reload

Trong khi phát triển MCP server của bạn, bạn có thể muốn cấu hình cờ --watch để trợ lý AI luôn thấy các phiên bản mới nhất của tools/resources:

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

Làm mới công cụ

Nếu bạn thêm tools hoặc resources mới, bạn có thể cần làm mới MCP server của bạn trong trợ lý AI.

Cấu Hình Theo Trợ Lý Cụ Thể

Vui lòng tham khảo tài liệu sau để cấu hình MCP với các Trợ Lý AI cụ thể:

• Amazon Q Developer
• Cline
• Cursor
• Claude Code
• Roo Code

Cấu hình workspace

Một số Trợ Lý AI, chẳng hạn như Amazon Q Developer, cho phép bạn chỉ định cấu hình MCP server ở cấp độ workspace, điều này đặc biệt hữu ích để xác định các MCP server liên quan cho một dự án cụ thể.

Chạy Máy chủ MCP của bạn

Inspector

Generator cấu hình một target có tên <your-server-name>-inspect, khởi động MCP Inspector với cấu hình để kết nối với máy chủ MCP của bạn bằng STDIO transport.

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

Điều này sẽ khởi động inspector tại http://localhost:6274. Bắt đầu bằng cách nhấp vào nút “Connect”.

STDIO

Cách dễ nhất để kiểm tra và sử dụng máy chủ MCP là bằng cách sử dụng inspector hoặc cấu hình nó với một trợ lý AI (như trên).

Tuy nhiên, bạn có thể chạy máy chủ của mình với STDIO transport trực tiếp bằng cách sử dụng target <your-server-name>-serve-stdio.

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

Lệnh này sử dụng tsx --watch để tự động khởi động lại máy chủ khi các tệp thay đổi.

Streamable HTTP

Nếu bạn muốn chạy máy chủ MCP của mình cục bộ bằng Streamable HTTP transport, bạn có thể sử dụng target <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

Lệnh này sử dụng tsx --watch để tự động khởi động lại máy chủ khi các tệp thay đổi.

Triển khai Máy chủ MCP của bạn lên Bedrock AgentCore Runtime

Cơ sở hạ tầng dưới dạng mã (Infrastructure as Code)

Nếu bạn đã chọn BedrockAgentCoreRuntime cho computeType, cơ sở hạ tầng CDK hoặc Terraform tương ứng sẽ được tạo ra, bạn có thể sử dụng để triển khai MCP server của mình lên Amazon Bedrock AgentCore Runtime.

CDK

Một CDK construct được tạo cho MCP Server của bạn, được đặt tên dựa trên name bạn đã chọn khi chạy trình tạo, hoặc <ProjectName>McpServer theo mặc định.

Bạn có thể sử dụng CDK construct này trong một ứng dụng CDK:

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Thêm MCP server vào stack của bạn
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

CDK Construct Alpha

Construct này sử dụng module @aws-cdk/aws-bedrock-agentcore-alpha.

Terraform

Một Terraform module được tạo cho bạn, được đặt tên dựa trên name bạn đã chọn khi chạy trình tạo, hoặc <ProjectName>-mcp-server theo mặc định.

Bạn có thể sử dụng terraform module này trong một dự án Terraform:

# MCP Server
module "my_project_mcp_server" {
  # Đường dẫn tương đối đến module được tạo trong dự án common/terraform
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

Yêu cầu Docker

Docker là bắt buộc để xây dựng và triển khai MCP server của bạn. Hãy đảm bảo bạn đã cài đặt và khởi chạy Docker để tránh các lỗi như:

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

Xác thực

Trình tạo cung cấp tùy chọn auth để cấu hình xác thực cho MCP server của bạn. Bạn có thể chọn giữa xác thực IAM (mặc định) hoặc Cognito khi tạo MCP server của mình.

IAM

Theo mặc định, MCP server của bạn sẽ được bảo mật bằng xác thực IAM, chỉ cần triển khai nó mà không cần tham số nào:

CDK

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

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

Bạn có thể cấp quyền truy cập để gọi MCP server của mình trên Bedrock AgentCore Runtime bằng phương thức grantInvokeAccess. Ví dụ, bạn có thể muốn một agent được tạo bằng trình tạo py#strands-agent gọi MCP server của bạn:

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

Terraform

# MCP Server
module "my_project_mcp_server" {
  # Đường dẫn tương đối đến module được tạo trong dự án common/terraform
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

Để cấp quyền truy cập gọi MCP server của bạn, bạn sẽ cần thêm một policy như sau, tham chiếu đến output 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}/*"
  ]
}

Xác thực Cognito

Khi bạn chọn xác thực Cognito, trình tạo sẽ cấu hình MCP server để sử dụng Cognito cho xác thực.

CDK

Construct được tạo chấp nhận prop identity để cấu hình xác thực 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,
    });
  }
}

Construct UserIdentity có thể được tạo bằng trình tạo ts#react-website#auth, hoặc bạn có thể tự tạo CDK UserPool và UserPoolClient của riêng mình.

Terraform

Module được tạo chấp nhận các biến user_pool_id và user_pool_client_ids cho xác thực 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"

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

Nhà cung cấp OIDC tùy chỉnh

Nếu bạn cần xác thực JWT tùy chỉnh với OIDC provider không phải Cognito, bạn có thể chỉnh sửa trực tiếp CDK construct hoặc Terraform module được tạo cho MCP server của mình. Lưu ý rằng trình tạo kết nối sẽ chỉ hỗ trợ xác thực IAM hoặc Cognito.

Bundle Target

Generator tự động cấu hình một target bundle sử dụng Rolldown để tạo gói triển khai:

pnpm

pnpm nx bundle <project-name>

yarn

yarn nx bundle <project-name>

npm

npx nx bundle <project-name>

bun

bunx nx bundle <project-name>

Cấu hình Rolldown có thể được tìm thấy trong rolldown.config.ts, với một entry cho mỗi bundle cần tạo. Rolldown quản lý việc tạo nhiều bundle song song nếu được định nghĩa.

Cấu hình tùy chỉnh

Bạn có thể điều chỉnh cấu hình cho Rolldown trong rolldown.config.ts, ví dụ nếu bạn có các dependency phụ thuộc vào đường dẫn file và không thể được bundle, bạn có thể thêm chúng vào danh sách các module external.

Bundle target sử dụng http.ts làm điểm vào cho máy chủ MCP Streamable HTTP để lưu trữ trên Bedrock AgentCore Runtime.

Docker Target

Generator cấu hình một target <your-server-name>-docker chạy máy chủ MCP Streamable HTTP đã được đóng gói trên cổng 8000 theo MCP protocol contract.

Tag ảnh Docker

Docker image được xây dựng bằng cách sử dụng một tag (ví dụ my-scope-my-project-mcp-server:latest), mà Dockerfile của CDK construct kế thừa từ đó, cho phép Dockerfile của bạn được đặt cùng vị trí với dự án máy chủ MCP của bạn.

Một target docker cũng được tạo ra để chạy docker build cho tất cả các máy chủ MCP nếu bạn có nhiều máy chủ được định nghĩa.

Khả năng quan sát

MCP server của bạn được tự động cấu hình với khả năng quan sát bằng cách sử dụng AWS Distro for Open Telemetry (ADOT), thông qua việc cấu hình auto-instrumentation trong Dockerfile của bạn.

Bạn có thể tìm thấy các trace trong CloudWatch AWS Console, bằng cách chọn “GenAI Observability” trong menu. Lưu ý rằng để các trace được hiển thị, bạn sẽ cần bật Transaction Search.

Để biết thêm chi tiết, vui lòng tham khảo tài liệu AgentCore về khả năng quan sát.