TypeScript MCP Server

Tạo một TypeScript Model Context Protocol (MCP) server để 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 để các LLM 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 MCP Server

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

CLI
VSCode

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

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

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

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
name	string	-	Tên của MCP server của bạn (mặc định: mcp-server)
auth	iam \| cognito	iam	Phương thức được sử dụng để xác thực với MCP server của bạn. Chỉ áp dụng khi infra được thiết lập (bị bỏ qua khi infra là none).
iac	inherit \| cdk \| terraform	inherit	Nhà cung cấp IaC ưu tiên. Mặc định giá trị này được kế thừa từ lựa chọn ban đầu của bạn.
infra	agentcore \| none	agentcore	Loại hạ tầng để lưu trữ MCP server của bạn. Chọn none để không có lưu trữ.
preferInstallDependencies	boolean	true	Có nên cài đặt dependencies sau khi generator chạy hay không. Đặt thành false để hoãn việc cài đặt khi chạy nhiều generator liên tiếp (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

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/ (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
    Thư mụctools/
    divide.ts Sample tool
    Thư mụcresources/
    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

Cơ sở hạ tầng

Vì generator này cung cấp infrastructure as code dựa trên iac 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
Terraform

Thư mụcpackages/common/constructs
- Thư mụcsrc
  - Thư mụcapp/ Constructs for infrastructure specific to a project/generator
    …
  - Thư mụccore/ Generic constructs which are reused by constructs in app
    …
  - index.ts Entry point exporting constructs from app
- project.json Project build targets and configuration

Thư mụcpackages/common/terraform
- Thư mụcsrc
  - Thư mụcapp/ Terraform modules for infrastructure specific to a project/generator
    …
  - Thư mụccore/ Generic modules which are reused by modules in app
    …
- project.json Project build targets and configuration

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

CDK
Terraform

Thư mụcpackages/common/constructs/src
- Thư mụcapp
  - Thư mụcmcp-servers
    Thư mục<mcp-server-name>
    <mcp-server-name>.ts CDK construct for deploying your MCP Server

Nếu bạn chọn none cho infra, không có CDK constructs hoặc Terraform modules nào được tạo — MCP server được cấu hình chỉ để sử dụng STDIO / HTTP cục bộ. Tùy chọn auth bị bỏ qua trong chế độ này vì không có endpoint được lưu trữ để xác thực.

Khi triển khai lên Bedrock AgentCore Runtime, MCP server được xây dựng thành container image, đẩy lên Amazon ECR, và chạy trong AgentCore Runtime. Các trợ lý AI gọi đến data plane endpoint của AgentCore Runtime, endpoint này chuyển tiếp các lời gọi tools/* và resources/* đến server của bạn qua streamable HTTP transport.

Với infra: none, không có cơ sở hạ tầng AWS nào được tạo ra. MCP server được cấu hình chỉ cho STDIO và HTTP transports cục bộ, và được sử dụng bởi các trợ lý AI chạy trên cùng một máy.

Làm việc với MCP Server của bạn

Thêm Công cụ

Cá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. Mỗi công cụ nằm trong tệp riêng của nó trong thư mục tools/ và xuất một hàm register<Name>Tool, sau đó bạn gọi từ server.ts. Ví dụ, thêm 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" }]
      };
    }
  );
};

Sau đó đăng ký nó bên trong createServer trong 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;
};

Thêm Tài nguyên

Các tài nguyên cung cấp ngữ cảnh cho trợ lý AI. Giống như các công cụ, mỗi tài nguyên nằm trong tệp riêng của nó trong thư mục resources/ và xuất một hàm register<Name>Resource được gọi từ server.ts. Bạn có thể thêm các tài nguyên tĩnh từ tệp hoặc các tài nguyên động:

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

Cấu hình với các 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 cách tiếp cận 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 mình:

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

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

Cấu hình Dành riêng cho Trợ lý

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ể:

Chạy MCP Server của bạn

Phát triển Cục bộ

Để chạy MCP server của bạn (và mọi thứ kết nối với nó, chẳng hạn như cơ sở dữ liệu cục bộ) ở cục bộ, hãy sử dụng target dev của dự án:

pnpm nx dev your-project

yarn nx dev your-project

npx nx dev your-project

bunx nx dev your-project

Nếu bạn đã thêm nhiều thành phần vào dự án của mình (MCP servers, agents, v.v.), lệnh này sẽ khởi động tất cả chúng. Để chỉ chạy MCP server này, hãy nhắm đến target <your-server-name>-dev của nó:

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

Inspector

Generator cấu hình một target có tên <your-server-name>-inspect, khởi động MCP server của bạn ở cục bộ (thông qua target <your-server-name>-dev, bao gồm bất kỳ phụ thuộc được kết nối nào như cơ sở dữ liệu cục bộ) và khởi chạy MCP Inspector được cấu hình sẵn để kết nối với nó qua Streamable HTTP transport.

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

Đ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ột MCP server 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 server 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 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

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

Streamable HTTP

Nếu bạn muốn chạy MCP server 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 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

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

Triển khai MCP Server của bạn lên Bedrock AgentCore Runtime

Infrastructure as Code

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

CDK
Terraform

Một CDK construct được tạo ra cho MCP Server của bạn, được đặt tên dựa trên name bạn đã chọn khi chạy generator, 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) {
    // Add the MCP server to your stack
    new MyProjectMcpServer(this, 'MyProjectMcpServer');
  }
}

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

Truyền các outputs của module runtime_config_appconfig được chia sẻ vào module MCP server:

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 là bắt buộc để build và triển khai MCP server của bạn. Đả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

Generator 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 bất kỳ đối số nào:

CDK
Terraform

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 generator py#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);
  }
}

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

Để 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, generator sẽ cấu hình MCP server để sử dụng Cognito cho xác thực.

CDK
Terraform

Construct được tạo ra chấp nhận một 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 generator ts#website#auth, hoặc bạn có thể tạo UserPool và UserPoolClient CDK của riêng mình.

Module được tạo ra 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"

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

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 nx bundle <project-name>

yarn nx bundle <project-name>

npx nx bundle <project-name>

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.

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

Docker Target

Generator cấu hình một target <your-server-name>-docker sao chép Dockerfile từ thư mục nguồn MCP server của bạn vào thư mục đầu ra bundle. Điều này đặt Dockerfile cùng vị trí với các artifact được đóng gói, cho phép CDK xây dựng Docker image trực tiếp bằng cách sử dụng AgentRuntimeArtifact.fromAsset.

Một target docker cũng được tạo để chuẩn bị ngữ cảnh docker cho tất cả các MCP servers nếu bạn có nhiều server được định nghĩa.

Quét Image

Docker image được xây dựng cho dự án này có thể được quét để tìm các lỗ hổng bảo mật bằng cách sử dụng Trivy, chạy từ ECR-hosted Trivy image.

Một target trivy được thêm vào dự án của bạn để quét image đã xây dựng và thoát với mã khác không nếu phát hiện bất kỳ lỗ hổng bảo mật mức độ nghiêm trọng HIGH hoặc CRITICAL nào. Dockerfile được tạo ra sử dụng một base image không có lỗ hổng bảo mật có thể sửa chữa nào ở các mức độ nghiêm trọng này tại thời điểm tạo, và nâng cấp các công cụ đi kèm (chẳng hạn như npm) để duy trì trạng thái đó.

Quá trình quét sử dụng cùng container engine với quá trình xây dựng image của bạn (docker hoặc finch), do đó không cần công cụ bổ sung nào. Vì quá trình quét chỉ được chạy lại khi image thay đổi, một image không thay đổi sẽ không được quét lại. Script root trivy được cung cấp sẽ quét mọi image trong workspace:

pnpm trivy

yarn trivy

npm run trivy

bun trivy

Quá trình quét chạy với --ignore-unfixed, do đó các lỗ hổng bảo mật không có bản sửa lỗi khả dụng sẽ không làm thất bại quá trình build, vì chúng không thể được xử lý bằng cách nâng cấp công cụ trong Dockerfile của bạn — chúng không được báo cáo trong kết quả quét của build. Khi các lỗ hổng bảo mật mới được công bố, kết quả quét có thể thay đổi theo thời gian, vì vậy hãy xem xét image định kỳ bằng cách chạy trivy image <your-image> mà không có flag này, và xây dựng lại với base image mới hơn (hoặc thêm các bước container để áp dụng các bản vá khả dụng) khi một bản sửa lỗi được phát hành.

Loại Bỏ Các Phát Hiện Của Trivy

Có thể có những trường hợp bạn muốn loại bỏ một lỗ hổng bảo mật cụ thể, ví dụ như khi chưa có bản sửa lỗi và bạn đã đánh giá rủi ro là có thể chấp nhận được.

Thêm ID lỗ hổng bảo mật (mỗi dòng một ID) vào file .trivyignore trong thư mục gốc của dự án (tức là bên cạnh project.json của bạn):

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

Để biết thêm chi tiết về việc lọc các phát hiện, hãy tham khảo tài liệu lọc của Trivy.

Khả năng quan sát

Máy chủ MCP 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 tự động ghi nhật ký trong Dockerfile của bạn.

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

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

Kết nối

Sử dụng generator connection để tích hợp dự án này với các dự án khác trong workspace của bạn. Các kết nối sau liên quan đến dự án này:

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