Bỏ qua để đến nội dung

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.

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

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

Chạy generator này@aws/nx-plugin:ts#mcp-server

pnpm nx g @aws/nx-plugin:ts#mcp-server
Xây dựng lệnh của bạn6

Bắt buộc

infra = agentcore | agentcore-ecr

Tùy chọn của generator6 tùy chọn
projectBắt buộcstring

Dự án để thêm MCP server vào

authenuminfra = agentcore | agentcore-ecrMặc định: 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).

iamcognito
iacenumMặc định: 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.

inheritcdkterraform
infraenumMặc định: agentcore

Loại hạ tầng để lưu trữ MCP server của bạn. agentcore triển khai mã của bạn dưới dạng zip đến runtime được quản lý bởi AgentCore để có chu kỳ build và deploy nhanh nhất. agentcore-ecr build và lưu trữ container image thay vào đó, để kiểm soát ở cấp độ hệ điều hành hoặc pipeline container đã thiết lập. Chọn none để không có hosting.

agentcoreagentcore-ecrnone
namestring

Tên của MCP server của bạn (mặc định: mcp-server)

preferInstallDependenciesbooleanMặc định: 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.

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 Container image definition (only when infra is agentcore-ecr)
    • project.json Updated with MCP server serve target

Tùy chọn infra chọn cách mã của bạn được đóng gói và lưu trữ trên Amazon Bedrock AgentCore Runtime:

  • agentcore (mặc định) sử dụng triển khai mã trực tiếp: mã đã build của bạn được đóng gói dưới dạng .zip, tải lên S3 và chạy trên runtime ngôn ngữ được quản lý bởi AgentCore. Không có container image để build, không có ECR repository để quản lý và không có image để push, điều này giúp chu kỳ build và deploy nhanh hơn đáng kể.
  • agentcore-ecr build một container image arm64 từ Dockerfile được cung cấp và lưu trữ nó từ registry core/asset-ecr được chia sẻ, cùng với mọi container khác trong workspace. Chọn tùy chọn này khi bạn cần kiểm soát image hệ điều hành — ví dụ để cài đặt các thư viện hệ thống gốc — hoặc khi bạn có một pipeline container đã thiết lập. Tùy chọn này cũng cung cấp thêm mục tiêu quét image Trivy (xem Image Scanning bên dưới).
  • none không tạo cơ sở hạ tầng nào cả, vì vậy dự án chỉ có thể chạy cục bộ.
infra = agentcore | agentcore-ecr

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:

  • 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

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

  • 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
infra = none

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, mã nguồn của server được đóng gói dưới dạng zip và chạy trong AgentCore managed 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/*resources/* đến server của bạn qua streamable HTTP transport.

Loading the diagram…

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:

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',
// Input schema using Zod
inputSchema: { param1: z.string(), param2: z.number() },
},
async ({ param1, param2 }) => {
// Tool implementation
const result = `${param1} ${param2}`;
return {
content: [{ type: 'text' as const, text: result }],
};
},
);
};

Sau đó đăng ký nó bên trong createServer trong server.ts:

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

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:

resources/my-resource.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
const fetchSomeData = async (): Promise<string> => 'some dynamic context';
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 }],
};
},
);
};

Đăng ký nó bên trong createServer trong server.ts giống như cách đăng ký một công cụ:

server.ts
import { registerMyResource } from './resources/my-resource.js';
export const createServer = async () => {
const server = new McpServer({ name: 'my-server', version: '1.0.0' });
registerMyResource(server);
return server;
};

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

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

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

Terminal window
pnpm 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ó:

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

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.

Terminal window
pnpm 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”.

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.

Terminal window
pnpm 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.

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.

Terminal window
pnpm 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.

infra = agentcore | agentcore-ecr

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

Phần tiêu đề “Triển khai MCP Server của bạn lên Bedrock AgentCore Runtime”

Nếu bạn chọn agentcore hoặc agentcore-ecr 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.

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

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.

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:

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

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.

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 UserPoolUserPoolClient CDK của riêng mình.

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

Terminal window
pnpm 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.

infra = agentcore

Generator cấu hình một target <your-server-name>-package để lắp ráp gói mã có thể triển khai: index.js được đóng gói cùng với bản cài đặt vendored của AWS Distro for OpenTelemetry, mà AgentCore yêu cầu phải có trong gói. Cơ sở hạ tầng được tạo ra sẽ tải thư mục này lên dưới dạng .zip — thông qua AgentRuntimeArtifact.fromCodeAsset trong CDK, hoặc được lưu trữ vào shared asset bucket trong Terraform.

infra = agentcore-ecr

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.

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. Quá trình quét không được cache, vì image mà nó đọc tồn tại trong container engine thay vì trên đĩa — do đó nó luôn quét image thực tế, và thất bại rõ ràng thay vì báo cáo kết quả pass đã được cache cho một image không còn tồn tại. Do đó, mỗi lần chạy mất hàng chục giây cho mỗi image và làm mới cơ sở dữ liệu lỗ hổng bảo mật của Trivy, vì vậy nó cần truy cập mạng. Script root trivy được cung cấp sẽ quét mọi image trong workspace:

Terminal window
pnpm 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):

.trivyignore
# 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.

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.

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:

Strands AgentsTypeScriptModel Context Protocol
TypeScript Agent to MCPConnect a TypeScript Agent to an MCP server
Strands AgentsPythonModel Context Protocol
Python Agent to MCPConnect a Python Agent to an MCP server
Model Context ProtocolAmazon Aurora
MCP Server to Relational DatabaseConnect a TypeScript MCP Server to an Aurora relational database
Model Context ProtocolAmazon DynamoDB
MCP Server to TypeScript DynamoDBConnect a TypeScript MCP Server to a DynamoDB table
Amazon Bedrock AgentCore GatewayModel Context Protocol
AgentCore Gateway to MCP ServerAggregate an MCP server behind an AgentCore Gateway