MCP TypeScript SDK 종합 분석
개요
Model Context Protocol(MCP) TypeScript SDK는 대규모 언어 모델(LLM) 애플리케이션과 외부 데이터 소스, 도구, 서비스 간의 표준화된 통신 방법을 제공하는 라이브러리입니다. 이 SDK는 LLM이 다양한 컨텍스트에 접근하고 외부 기능을 활용할 수 있게 하는 인프라를 제공하며, 클라이언트와 서버 측 구현을 모두 포함합니다.
MCP는 "컨텍스트 제공"의 관심사를 LLM 상호작용과 분리함으로써, 보다 모듈화된 접근 방식을 가능하게 합니다. 이는 웹 API와 유사하지만 특별히 LLM 상호작용을 위해 설계되었습니다.
아키텍처
MCP TypeScript SDK는 다음과 같은 주요 컴포넌트로 구성된 모듈식 아키텍처를 채택하고 있습니다:
graph TD
%% 메인 컴포넌트
SDK[MCP TypeScript SDK]
SDK --> Client[Client Module]
SDK --> Server[Server Module]
SDK --> Shared[Shared Module]
SDK --> Types[Types Module]
%% 클라이언트 모듈
Client --> ClientMain[Client Class]
Client --> ClientAuth[Auth Module]
Client --> ClientSSE[SSE Transport]
Client --> ClientStdio[Stdio Transport]
Client --> ClientWebSocket[WebSocket Transport]
Client --> ClientHTTP[HTTP Transport]
%% 서버 모듈
Server --> McpServer[McpServer Class]
Server --> ServerBase[Server Base Class]
Server --> ServerAuth[Auth Module]
Server --> ServerTransports[Transports]
Server --> Completable[Completable Utility]
ServerAuth --> AuthProviders[Auth Providers]
AuthProviders --> ProxyProvider[Proxy Provider]
ServerAuth --> AuthMiddleware[Auth Middleware]
AuthMiddleware --> BearerAuth[Bearer Auth]
AuthMiddleware --> ClientAuth[Client Auth]
AuthMiddleware --> AllowedMethods[Allowed Methods]
ServerAuth --> AuthHandlers[Auth Handlers]
AuthHandlers --> Authorize[Authorize Handler]
AuthHandlers --> Register[Register Handler]
AuthHandlers --> Token[Token Handler]
AuthHandlers --> Revoke[Revoke Handler]
AuthHandlers --> Metadata[Metadata Handler]
ServerTransports --> ServerSSE[SSE Transport]
ServerTransports --> ServerStdio[Stdio Transport]
ServerTransports --> ServerHTTP[HTTP Transport]
%% 공유 모듈
Shared --> Protocol[Protocol Class]
Shared --> Transport[Transport Interface]
Shared --> UriTemplate[URI Template]
Shared --> SharedAuth[Auth Utilities]
Shared --> SharedStdio[Stdio Utilities]
%% 타입 모듈
Types --> SchemaTypes[Schema Types]
Types --> RequestTypes[Request Types]
Types --> ResponseTypes[Response Types]
Types --> NotificationTypes[Notification Types]
%% McpServer 기능
McpServer --> Resources[Resources API]
McpServer --> Tools[Tools API]
McpServer --> Prompts[Prompts API]
McpServer --> Capabilities[Capabilities API]
Resources --> ResourceHandler[Resource Handlers]
Resources --> ResourceTemplate[Resource Templates]
Tools --> ToolHandler[Tool Handlers]
Tools --> ToolParams[Tool Parameters]
Prompts --> PromptHandler[Prompt Handlers]
Prompts --> PromptParams[Prompt Parameters]
%% 주요 연결 관계
ClientMain --> Protocol
McpServer --> ServerBase
ServerBase --> Protocol
style SDK fill:#f9f9f9,stroke:#333,stroke-width:4px
style Client fill:#e1f5fe,stroke:#333,stroke-width:2px
style Server fill:#e8f5e9,stroke:#333,stroke-width:2px
style Shared fill:#fff3e0,stroke:#333,stroke-width:2px
style Types fill:#f3e5f5,stroke:#333,stroke-width:2px
style McpServer fill:#81c784,stroke:#333,stroke-width:2px
style ClientMain fill:#4fc3f7,stroke:#333,stroke-width:2px
style Protocol fill:#ffb74d,stroke:#333,stroke-width:2px
style ServerAuth fill:#aed581,stroke:#333,stroke-width:2px이 아키텍처는 모듈성, 확장성, 유연성을 우선시하며, 다양한 전송 방식과 인증 메커니즘을 지원합니다.
핵심 구성 요소
모듈 구조
MCP TypeScript SDK는 다음과 같은 주요 모듈로 구성되어 있습니다:
Client 모듈: MCP 서버에 연결하고 리소스를 요청하며 도구를 호출하는 클라이언트 구현. 다양한 전송 메커니즘을 지원합니다.
Server 모듈: 리소스, 도구, 프롬프트를 노출하는 서버 구현. McpServer 클래스는 높은 수준의 API를 제공하여 개발자가 쉽게 서버를 구성할 수 있도록 합니다.
Shared 모듈: 클라이언트와 서버 간에 공유되는 공통 유틸리티 및 인터페이스를 포함합니다. Protocol 클래스, Transport 인터페이스, URI 템플릿 처리 등이 이에 해당합니다.
Types 모듈: 프로토콜에서 사용되는 모든 데이터 타입과 스키마 정의를 포함합니다. Zod 라이브러리를 활용한 강력한 타입 검증을 제공합니다.
주요 클래스
SDK의 핵심 기능은 다음과 같은 주요 클래스들을 통해 구현됩니다:
classDiagram
%% 기본 클래스
class Protocol {
#id: number
#pendingRequests: Map
#requestHandlers: Map
#transport: Transport
+connect(transport: Transport)
+close()
+request(req, schema, options)
+notification(notif)
+setRequestHandler(schema, handler)
+registerCapabilities(capabilities)
}
class Transport {
<<interface>>
+connect(): Promise
+close(): Promise
+sendMessage(message: string): Promise
+onMessage(callback): void
+onClose(callback): void
}
class Server {
-serverInfo: Implementation
-capabilities: ServerCapabilities
+connect(transport: Transport)
+close()
+setRequestHandler(schema, handler)
+sendResourceListChanged()
+sendToolListChanged()
+sendPromptListChanged()
+sendResourceContentsChanged()
}
class McpServer {
-server: Server
-registeredResources: Map
-registeredResourceTemplates: Map
-registeredTools: Map
-registeredPrompts: Map
+connect(transport: Transport)
+close()
+resource(name, uri, callback)
+tool(name, [description], [paramsSchema], callback)
+prompt(name, [description], [argsSchema], callback)
+isConnected()
+sendResourceListChanged()
+sendToolListChanged()
+sendPromptListChanged()
}
class Client {
-clientInfo: Implementation
-serverCapabilities: ServerCapabilities
-serverVersion: Implementation
-capabilities: ClientCapabilities
-instructions: string
+connect(transport: Transport)
+getServerCapabilities()
+getServerVersion()
+getInstructions()
+ping()
+complete(params)
+setLoggingLevel(level)
+getPrompt(params)
+listPrompts(params)
+listResources(params)
+listResourceTemplates(params)
+readResource(params)
+subscribeResource(params)
+unsubscribeResource(params)
+callTool(params)
+listTools(params)
+sendRootsListChanged()
}
class ResourceTemplate {
-uriTemplate: UriTemplate
-callbacks: object
+get uriTemplate()
+get listCallback()
+completeCallback(variable)
}
class UriTemplate {
-template: string
-segments: array
+match(uri): Variables
+toString(): string
}
%% 관계 정의
Protocol <|-- Server
Protocol <|-- Client
Server <-- McpServer
McpServer --> ResourceTemplate
ResourceTemplate --> UriTemplateProtocol: 클라이언트와 서버 모두의 기본이 되는 클래스로, 요청-응답 처리, 알림 처리, 메시지 포맷팅 등의 핵심 기능을 제공합니다.
Server: 기본 서버 구현 클래스로, 요청 처리 및 알림 전송을 담당합니다.
McpServer: Server 클래스를 감싸는 고수준 래퍼로, 리소스, 도구, 프롬프트를 쉽게 등록하고 관리할 수 있는 API를 제공합니다.
Client: MCP 서버와 통신하기 위한 클라이언트 구현으로, 각종 요청 메서드와 응답 처리 기능을 제공합니다.
ResourceTemplate: URI 템플릿과 변수 매칭을 처리하여 동적 리소스 접근을 가능하게 합니다.
UriTemplate: URI 패턴 매칭 및 파싱을 담당하는 유틸리티 클래스입니다.
전송 계층
SDK는 다양한 환경에서 작동할 수 있도록 여러 전송 메커니즘을 지원합니다:
StdioTransport: 표준 입출력을 통한 통신으로, 명령줄 도구 및 프로세스 간 통신에 적합합니다.
SSETransport: Server-Sent Events(SSE)를 통한 HTTP 기반 통신으로, 웹 기반 애플리케이션에 적합합니다.
WebSocketTransport: WebSocket을 통한 양방향 통신을 지원합니다.
StreamableHttpTransport: HTTP 기반의 스트리밍 통신을 지원합니다.
이러한 다양한 전송 옵션은 SDK가 CLI 환경부터 웹 서버, 브라우저 애플리케이션에 이르기까지 다양한 컨텍스트에서 사용될 수 있게 합니다.
요청 처리 흐름
서버 초기화 과정
MCP 서버의 초기화 과정은 다음과 같습니다:
- McpServer 인스턴스 생성: 서버 이름, 버전 등의 기본 정보 설정
- 리소스, 도구, 프롬프트 등록:
resource(),tool(),prompt()메서드를 통한 기능 등록 - 전송 계층 설정: 사용할 통신 방식(stdio, SSE 등)에 맞는 Transport 객체 생성
- 서버 연결:
connect()메서드를 통해 전송 계층과 연결하고 메시지 수신 대기
요청 처리 상세 플로우
MCP 서버에서의 요청 처리 흐름은 다음과 같은 상세한 단계를 거칩니다:
sequenceDiagram
participant Client
participant Transport
participant Protocol as Protocol (Server)
participant ServerClass as Server Class
participant McpServer
participant Handler as Request Handler
participant Resource as Resource/Tool/Prompt
participant External as External System
Client->>Transport: 요청 메시지 전송
Transport->>Protocol: 메시지 수신 및 파싱
Protocol->>Protocol: 메시지 ID 및 타입 확인
Protocol->>ServerClass: 요청 유형에 맞는 핸들러 조회
alt 일반 Server 핸들러
ServerClass->>Handler: 등록된 핸들러로 요청 전달
else McpServer 핸들러
ServerClass->>McpServer: 고수준 API 핸들러로 요청 전달
alt 리소스 요청
McpServer->>McpServer: 요청 URI 매칭
McpServer->>Resource: 리소스 핸들러 호출
Resource->>External: 필요시 외부 시스템 접근
External->>Resource: 데이터 반환
Resource->>McpServer: 리소스 컨텐츠 반환
else 도구 호출
McpServer->>McpServer: 도구 이름 매칭
McpServer->>McpServer: 파라미터 검증 (Zod)
McpServer->>Resource: 도구 콜백 함수 호출
Resource->>External: 필요시 외부 시스템과 통신
External->>Resource: 처리 결과 반환
Resource->>McpServer: 도구 실행 결과 반환
else 프롬프트 요청
McpServer->>McpServer: 프롬프트 이름 매칭
McpServer->>McpServer: 인자 검증 (Zod)
McpServer->>Resource: 프롬프트 콜백 함수 호출
Resource->>McpServer: 프롬프트 메시지 반환
end
McpServer->>ServerClass: 처리 결과 반환
end
ServerClass->>Protocol: 결과 포맷팅
Protocol->>Transport: 응답 메시지 전송
Transport->>Client: 클라이언트에 응답 전달이 흐름도는 MCP 서버 내에서 요청이 어떻게 처리되는지 자세히 보여줍니다. Protocol 레이어에서 메시지를 수신하고 파싱한 후, 적절한 핸들러로 라우팅하여 처리하고, 결과를 다시 클라이언트에게 반환하는 과정이 포함됩니다.
리소스 처리 메커니즘
리소스 처리는 다음과 같은 단계로 이루어집니다:
- URI 매칭: 요청된 URI가 정적 리소스 또는 리소스 템플릿과 매칭되는지 확인
- 변수 추출: URI 템플릿의 경우, URI에서 변수 값을 추출
- 리소스 콜백 호출: 매칭된 리소스의 콜백 함수 호출
- 결과 반환: 리소스 콘텐츠를 클라이언트에 반환
다음은 리소스 요청 처리의 자세한 플로우입니다:
sequenceDiagram
participant Client
participant Server as MCP Server
participant RouterHandler as Resources Router Handler
participant StaticResource as Static Resource
participant TemplateResource as Template Resource
participant ExternalSystem as External System
Client->>Server: resources/read 요청
Server->>RouterHandler: URI와 요청 전달
RouterHandler->>RouterHandler: URI 검사
alt 정적 리소스 매칭
RouterHandler->>StaticResource: 정확한 URI 매칭
StaticResource->>ExternalSystem: 필요시 외부 데이터 조회
ExternalSystem->>StaticResource: 데이터 반환
StaticResource->>RouterHandler: 리소스 콘텐츠 반환
else 리소스 템플릿 매칭
RouterHandler->>TemplateResource: URI 패턴 매칭 시도
TemplateResource->>TemplateResource: URI 변수 추출
TemplateResource->>ExternalSystem: 변수를 이용한 동적 데이터 조회
ExternalSystem->>TemplateResource: 데이터 반환
TemplateResource->>RouterHandler: 리소스 콘텐츠 반환
else 매칭 실패
RouterHandler->>RouterHandler: 404 에러 생성
end
RouterHandler->>Server: 처리 결과 반환
Server->>Client: 응답 전송도구 호출 메커니즘
도구 호출은 다음과 같은 단계로 이루어집니다:
- 도구 조회: 요청된 도구 이름으로 등록된 도구 찾기
- 파라미터 검증: Zod 스키마를 사용하여 입력 파라미터 검증
- 콜백 실행: 도구의 콜백 함수 실행
- 결과 반환: 도구 실행 결과를 클라이언트에 반환
다음은 도구 호출 처리의 자세한 플로우입니다:
sequenceDiagram
participant Client
participant Server as MCP Server
participant ToolsHandler as Tools Handler
participant ToolImpl as Tool Implementation
participant ValidationEngine as Zod Validation Engine
participant ExternalAPI as External API/Service
Client->>Server: tools/call 요청 (name, arguments)
Server->>ToolsHandler: 요청 전달
ToolsHandler->>ToolsHandler: 도구 이름으로 등록된 도구 조회
alt 도구 찾음
ToolsHandler->>ValidationEngine: 입력 인자 검증 (Zod)
alt 검증 성공
ValidationEngine->>ToolsHandler: 검증된 파라미터 반환
ToolsHandler->>ToolImpl: 콜백 함수 호출
opt 외부 API 호출
ToolImpl->>ExternalAPI: 외부 서비스 호출
ExternalAPI->>ToolImpl: 결과 반환
end
ToolImpl->>ToolsHandler: 실행 결과 반환
else 검증 실패
ValidationEngine->>ToolsHandler: 검증 오류 반환
ToolsHandler->>ToolsHandler: 파라미터 오류 응답 생성
end
else 도구 없음
ToolsHandler->>ToolsHandler: 도구 없음 오류 응답 생성
end
ToolsHandler->>Server: 처리 결과 반환
Server->>Client: 응답 전송프롬프트 처리 메커니즘
프롬프트 처리는 다음과 같은 단계로 이루어집니다:
- 프롬프트 조회: 요청된 프롬프트 이름으로 등록된 프롬프트 찾기
- 인자 검증: Zod 스키마를 사용하여 입력 인자 검증
- 콜백 실행: 프롬프트의 콜백 함수 실행하여 메시지 생성
- 결과 반환: 생성된 프롬프트 메시지를 클라이언트에 반환
다음은 프롬프트 요청 처리의 자세한 플로우입니다:
sequenceDiagram
participant Client
participant Server as MCP Server
participant PromptHandler as Prompts Handler
participant PromptImpl as Prompt Implementation
participant ValidationEngine as Zod Validation Engine
Client->>Server: prompts/get 요청 (name, arguments)
Server->>PromptHandler: 요청 전달
PromptHandler->>PromptHandler: 프롬프트 이름으로 등록된 프롬프트 조회
alt 프롬프트 찾음
PromptHandler->>ValidationEngine: 입력 인자 검증 (Zod)
alt 검증 성공
ValidationEngine->>PromptHandler: 검증된 인자 반환
PromptHandler->>PromptImpl: 콜백 함수 호출
PromptImpl->>PromptHandler: 프롬프트 메시지 생성 및 반환
else 검증 실패
ValidationEngine->>PromptHandler: 검증 오류 반환
PromptHandler->>PromptHandler: 인자 오류 응답 생성
end
else 프롬프트 없음
PromptHandler->>PromptHandler: 프롬프트 없음 오류 응답 생성
end
PromptHandler->>Server: 처리 결과 반환
Server->>Client: 응답 전송MCP 서버 내부 요청 처리 상세 흐름도
다음은 MCP 서버 내부에서 요청이 처리되는 전체 과정을 더욱 상세하게 보여주는 흐름도입니다:
sequenceDiagram
participant Client
participant Transport
participant Protocol as Protocol Layer
participant ServerImpl as Server Implementation
participant McpServer
participant Resolvers as Request Resolvers
participant Validation as Zod Validation
participant Handlers as Resource/Tool/Prompt Handlers
participant External as External Systems
Client->>Transport: HTTP/WS/Stdio 요청
Transport->>Protocol: JSON 메시지 수신
%% 메시지 파싱 및 라우팅
Protocol->>Protocol: 메시지 형식 검증
Protocol->>Protocol: 메시지 ID 및 타입 분석
Protocol->>Protocol: 요청/알림 구분
alt 알림(Notification)
Protocol->>ServerImpl: 알림 메시지 전달
ServerImpl->>ServerImpl: 알림 처리
else 요청(Request)
Protocol->>ServerImpl: 요청 메시지 전달
%% 요청 유형에 따른 분기
alt initialize 요청
ServerImpl->>ServerImpl: 초기화 처리
ServerImpl->>Protocol: 서버 정보 및 기능 응답
else ping 요청
ServerImpl->>Protocol: 즉시 응답
else 리소스/도구/프롬프트 요청
ServerImpl->>McpServer: 요청 위임
%% MCP 서버 내부 처리
alt resources/list 요청
McpServer->>Resolvers: 리소스 목록 요청 처리
Resolvers->>Resolvers: 등록된 리소스 수집
Resolvers->>McpServer: 리소스 목록 반환
else resources/read 요청
McpServer->>Resolvers: URI 기반 리소스 요청 처리
Resolvers->>Resolvers: URI 매칭 (정적/템플릿)
alt 정적 리소스 매칭
Resolvers->>Handlers: 정적 리소스 핸들러 호출
else 리소스 템플릿 매칭
Resolvers->>Resolvers: URI 변수 추출
Resolvers->>Handlers: 템플릿 리소스 핸들러 호출 (변수 전달)
end
Handlers->>External: 필요시 외부 시스템 호출
External->>Handlers: 데이터 반환
Handlers->>Resolvers: 리소스 콘텐츠 반환
Resolvers->>McpServer: 읽기 결과 반환
else tools/list 요청
McpServer->>Resolvers: 도구 목록 요청 처리
Resolvers->>Resolvers: 등록된 도구 수집
Resolvers->>McpServer: 도구 목록 반환
else tools/call 요청
McpServer->>Resolvers: 도구 호출 요청 처리
Resolvers->>Resolvers: 도구 이름으로 조회
alt 도구 찾음
Resolvers->>Validation: 입력 파라미터 검증
alt 검증 성공
Validation->>Resolvers: 검증된 파라미터 반환
Resolvers->>Handlers: 도구 콜백 함수 호출
Handlers->>External: 필요시 외부 시스템 호출
External->>Handlers: 결과 반환
Handlers->>Resolvers: 도구 실행 결과 반환
else 검증 실패
Validation->>Resolvers: 검증 오류 반환
Resolvers->>McpServer: 파라미터 오류 응답 생성
end
else 도구 없음
Resolvers->>McpServer: 도구 없음 오류 응답 생성
end
Resolvers->>McpServer: 도구 호출 결과 반환
else prompts/list 요청
McpServer->>Resolvers: 프롬프트 목록 요청 처리
Resolvers->>Resolvers: 등록된 프롬프트 수집
Resolvers->>McpServer: 프롬프트 목록 반환
else prompts/get 요청
McpServer->>Resolvers: 프롬프트 요청 처리
Resolvers->>Resolvers: 프롬프트 이름으로 조회
alt 프롬프트 찾음
Resolvers->>Validation: 입력 인자 검증
alt 검증 성공
Validation->>Resolvers: 검증된 인자 반환
Resolvers->>Handlers: 프롬프트 콜백 함수 호출
Handlers->>Resolvers: 프롬프트 메시지 반환
else 검증 실패
Validation->>Resolvers: 검증 오류 반환
Resolvers->>McpServer: 인자 오류 응답 생성
end
else 프롬프트 없음
Resolvers->>McpServer: 프롬프트 없음 오류 응답 생성
end
Resolvers->>McpServer: 프롬프트 반환 결과
else completion/complete 요청
McpServer->>Resolvers: 자동완성 요청 처리
Resolvers->>Resolvers: 참조 유형 확인 (프롬프트/리소스)
alt 프롬프트 자동완성
Resolvers->>Handlers: 프롬프트 자동완성 처리
else 리소스 자동완성
Resolvers->>Handlers: 리소스 템플릿 자동완성 처리
end
Handlers->>Resolvers: 자동완성 결과 반환
Resolvers->>McpServer: 자동완성 결과 반환
end
McpServer->>ServerImpl: 처리 결과 반환
end
ServerImpl->>Protocol: 응답 생성
end
Protocol->>Transport: JSON 응답 전송
Transport->>Client: HTTP/WS/Stdio 응답이 흐름도는 클라이언트 요청이 전송 계층을 통해 서버에 도달한 후 Protocol 레이어, Server 구현, McpServer, 요청 해석기, 검증 엔진, 핸들러를 거쳐 최종적으로 외부 시스템과 통합되는 전체 과정을 보여줍니다. 각 요청 유형에 따른 처리 경로와 검증 단계, 그리고 에러 처리 흐름까지 상세하게 시각화되어 있습니다.
기능 및 Capabilities
MCP TypeScript SDK는 서버와 클라이언트 간에 지원하는 기능을 명확하게 정의하고 협상하기 위한 Capabilities 시스템을 제공합니다. 이 시스템은 프로토콜의 유연성과 확장성을 보장하는 핵심 메커니즘입니다.
Capabilities 시스템
Capabilities 시스템은 다음과 같은 주요 목적을 가집니다:
- 기능 협상: 클라이언트와 서버가 지원하는 기능을 초기화 과정에서 교환하여 호환성 확인
- 기능 구성: 특정 기능의 세부 옵션 및 제한 설정
- 점진적 확장: 프로토콜 버전을 변경하지 않고도 새로운 기능 추가 가능
- 런타임 검증: 요청 전에 특정 기능의 지원 여부 확인
Capabilities 시스템의 작동 방식:
초기화 단계:
- 클라이언트는 자신이 지원하는 기능을
initialize요청에 포함 - 서버는 자신이 지원하는 기능을 응답에 포함
- 양측은 상대방의 기능을 저장하고 이후 요청에서 참조
- 클라이언트는 자신이 지원하는 기능을
요청 전 검증:
- 클라이언트는 요청 전에 서버가 필요한 기능을 지원하는지 확인
- 서버는 요청 처리 전에 해당 요청에 필요한 기능이 있는지 확인
기능 알림:
- 특정 기능이 변경되면 관련 알림 메시지 전송 (예: 리소스 목록 변경)
클라이언트 Capabilities
클라이언트 Capabilities는 초기화 과정에서 서버에 전달되며, 다음과 같은 주요 항목을 포함합니다:
interface ClientCapabilities {
// 로깅 기능 지원
logging?: {
// 로깅 수준 변경 지원
setLevel?: boolean;
};
// 샘플링 기능 지원
sampling?: {
// 메시지 생성 지원
createMessage?: boolean;
};
// 루트 리소스 지원
roots?: {
// 루트 리소스 목록 변경 알림 수신 지원
listChanged?: boolean;
};
}클라이언트 기능은 다음과 같이 등록됩니다:
const client = new Client(
{ name: "example-client", version: "1.0.0" },
{
capabilities: {
roots: { listChanged: true },
sampling: { createMessage: true }
}
}
);
// 또는 나중에 추가
client.registerCapabilities({
logging: { setLevel: true }
});서버 Capabilities
서버 Capabilities는 서버가 지원하는 기능을 정의하며, 초기화 응답에 포함됩니다:
interface ServerCapabilities {
// 리소스 관련 기능
resources?: {
// 리소스 구독 지원
subscribe?: boolean;
// 리소스 목록 변경 알림 지원
listChanged?: boolean;
// 리소스 내용 변경 알림 지원
contentsChanged?: boolean;
};
// 도구 관련 기능
tools?: {
// 도구 목록 변경 알림 지원
listChanged?: boolean;
};
// 프롬프트 관련 기능
prompts?: {
// 프롬프트 목록 변경 알림 지원
listChanged?: boolean;
};
// 완성 기능 지원
completions?: boolean;
// 로깅 기능 지원
logging?: boolean;
}서버에서 기능을 등록하는 방법:
// McpServer를 통한 자동 등록
const server = new McpServer(
{ name: "example-server", version: "1.0.0" }
);
// resource(), tool(), prompt() 메서드를 호출하면 자동으로 관련 기능이 등록됨
// 또는 명시적 등록
server.server.registerCapabilities({
resources: {
subscribe: true,
listChanged: true,
contentsChanged: true
},
logging: true
});Capabilities 시스템은 McpServer가 제공하는 높은 수준의 API를 사용할 때 대부분 자동으로 처리됩니다. 예를 들어, 리소스를 등록하면 resources 기능이 자동으로 활성화되고, 도구를 등록하면 tools 기능이 활성화됩니다.
또한, 런타임에 특정 기능이 변경될 때(예: 새 리소스 추가) 관련 알림을 보내기 위한 메서드가 제공됩니다:
// 리소스 목록 변경 알림
server.sendResourceListChanged();
// 도구 목록 변경 알림
server.sendToolListChanged();
// 프롬프트 목록 변경 알림
server.sendPromptListChanged();이러한 Capabilities 시스템은 MCP 프로토콜의 핵심 요소로, 다양한 클라이언트와 서버가 서로의 기능을 명확하게 이해하고 호환성 있게 통신할 수 있도록 합니다.
데이터 모델
MCP TypeScript SDK는 Zod 라이브러리를 활용하여 강력한 타입 검증과 스키마 정의를 제공합니다. 주요 데이터 모델은 다음과 같습니다:
메시지 타입:
- Request: 클라이언트에서 서버로의 요청 메시지
interface Request { id: string; method: string; params?: unknown; } - Result: 서버에서 클라이언트로의 응답 메시지
interface Result { id: string; result?: unknown; error?: { code: ErrorCode; message: string; data?: unknown; }; } - Notification: 양방향 알림 메시지(ID 없음)
interface Notification { method: string; params?: unknown; }
- Request: 클라이언트에서 서버로의 요청 메시지
리소스 모델:
- URI 기반 식별 시스템
interface Resource { uri: string; name: string; description?: string; contentType?: string; tags?: string[]; } - 리소스 콘텐츠 구조
interface ResourceContent { uri: string; text: string; contentType?: string; title?: string; } - 리소스 템플릿(동적 리소스용)
interface ResourceTemplate { name: string; uriTemplate: string; description?: string; }
- URI 기반 식별 시스템
도구 모델:
- 도구 정의 구조
interface Tool { name: string; description?: string; inputSchema?: JSONSchema; } - 도구 호출 결과 구조
interface CallToolResult { content: { type: string; text: string; }[]; isError?: boolean; }
- 도구 정의 구조
프롬프트 모델:
- 프롬프트 정의 구조
interface Prompt { name: string; description?: string; arguments?: PromptArgument[]; } - 프롬프트 인자 구조
interface PromptArgument { name: string; description?: string; required: boolean; } - 프롬프트 메시지 구조
interface GetPromptResult { description?: string; messages: { role: string; content: { type: string; text: string; }; }[]; }
- 프롬프트 정의 구조
기타 중요 타입:
- Implementation: 클라이언트/서버 식별 정보
interface Implementation { name: string; version: string; } - UriTemplate: URI 패턴 및 변수 정의
- Completable: 자동완성을 위한 문자열 확장 타입
- Implementation: 클라이언트/서버 식별 정보
이러한 데이터 모델은 Types 모듈에서 정의되며, Zod 스키마를 통해 모든 요청과 응답이 엄격하게 검증됩니다. Zod는 TypeScript 타입 시스템과 통합되어 런타임 데이터 검증과 정적 타입 검사를 모두 제공합니다.
기능적 특징
MCP TypeScript SDK는 다양한 기능적 특징을 제공합니다. 이번 섹션에서는 각 핵심 구성 요소에 대해 초보자부터 AI 관련 종사자까지 모두가 이해할 수 있도록 상세히 설명하겠습니다.
1. 리소스(Resources)
리소스는 LLM에 제공할 데이터의 근원을 나타냅니다. 웹 개발의 RESTful API에서 GET 엔드포인트와 유사한 개념으로 생각할 수 있습니다.
리소스의 기본 개념
리소스란 무엇인가?
- 리소스는 LLM이 참조할 수 있는 데이터 소스입니다
- URI(Uniform Resource Identifier)로 식별됩니다
- 주로 텍스트 데이터를 제공하지만, 다양한 형식(JSON, 마크다운 등)을 지원할 수 있습니다
- 계산보다는 데이터 검색 목적으로 설계되었습니다
// 정적 리소스 예제
server.resource(
"config",
"config://app",
async (uri) => ({
contents: [{
uri: uri.href,
text: "기본 설정 데이터입니다."
}]
})
);리소스의 종류
정적 리소스: 고정된 URI를 가지며, 항상 동일한 데이터를 반환합니다
server.resource("readme", "docs://readme.md", async () => { ... });동적 리소스(템플릿): URI 템플릿을 통해 변수를 포함하는 패턴으로 정의됩니다
server.resource( "user-profile", new ResourceTemplate("users://{userId}/profile", { list: undefined }), async (uri, { userId }) => { ... } );리소스 목록: 특정 패턴에 맞는 여러 리소스를 목록으로 제공합니다
// 모든 사용자 목록을 반환하는 리소스 new ResourceTemplate("users://", { list: async () => ({ resources: [ { uri: "users://1", name: "사용자 1" }, { uri: "users://2", name: "사용자 2" } ] }) });
리소스의 활용 사례
- 문서 컨텍스트: 사용자 매뉴얼, API 문서, 정책 등의 텍스트 제공
- 데이터베이스 접근: 데이터베이스의 데이터를 URI 패턴을 통해 노출
- 파일 시스템 통합: 로컬 또는 원격 파일 시스템의 파일에 접근
- 메타데이터 제공: 시스템 상태, 설정, 환경 정보 등 제공
리소스 구현의 핵심 요소
- URI 기반 식별: 모든 리소스는 고유한 URI로 식별됩니다
- 템플릿 및 변수: 동적 콘텐츠를 위한 URI 패턴과 변수 지원
- 비동기 데이터 접근: Promise 기반의 비동기 데이터 검색
- 메타데이터: 리소스에 대한 추가 정보(설명, 태그, 콘텐츠 타입 등)
2. 도구(Tools)
도구는 LLM이 실행할 수 있는 기능을 제공합니다. 웹 개발의 POST 엔드포인트와 유사하게 생각할 수 있으며, 계산이나 외부 효과를 가질 수 있습니다.
도구의 기본 개념
도구란 무엇인가?
- 도구는 LLM이 호출할 수 있는 함수나 서비스입니다
- 입력 매개변수를 받고 결과를 반환합니다
- 계산, API 호출, 데이터 변환 등의 작업을 수행할 수 있습니다
- 부작용(side effects)을 가질 수 있습니다(예: 데이터베이스 업데이트, 파일 생성)
// 간단한 도구 예제
server.tool(
"calculate-bmi",
{
weightKg: z.number(),
heightM: z.number()
},
async ({ weightKg, heightM }) => ({
content: [{
type: "text",
text: String(weightKg / (heightM * heightM))
}]
})
);도구의 구성 요소
- 이름: 도구를 식별하는 고유한 이름
- 설명(선택사항): 도구의 기능에 대한 설명
- 입력 스키마: Zod를 사용한 입력 매개변수 정의
- 콜백 함수: 도구의 실제 기능을 구현하는 함수
도구 입력 검증
MCP TypeScript SDK는 Zod 라이브러리를 사용하여 도구 입력의 유효성을 검사합니다:
server.tool(
"send-email",
{
to: z.string().email(), // 이메일 형식 검증
subject: z.string().min(1), // 최소 1자 이상
body: z.string().optional() // 선택적 필드
},
async ({ to, subject, body = "" }) => { ... }
);도구의 활용 사례
- 계산 도구: 수학적 계산, 통계 분석, 데이터 처리
- API 통합: 외부 API 호출(날씨 정보, 주식 데이터, 번역 서비스 등)
- 데이터베이스 조작: 쿼리 실행, 데이터 삽입/업데이트
- 파일 작업: 파일 생성, 수정, 삭제
도구 구현의 핵심 요소
- 강력한 타입 안전성: Zod를 통한 입력 검증으로 타입 안전성 보장
- 비동기 실행: Promise 기반의 비동기 작업 지원
- 오류 처리: 명확한 오류 메시지와 오류 상태 반환
- 결과 형식: 텍스트 또는 구조화된 데이터 반환
3. 프롬프트(Prompts)
프롬프트는 LLM과의 상호작용을 위한 템플릿을 제공합니다. 미리 정의된 프롬프트 패턴을 통해 일관된 LLM 응답을 유도할 수 있습니다.
프롬프트의 기본 개념
프롬프트란 무엇인가?
- 프롬프트는 LLM에 전달될 메시지 템플릿입니다
- 동적 값을 삽입할 수 있는 매개변수화된 형식을 지원합니다
- 다중 메시지 구조를 가질 수 있습니다(사용자/시스템 메시지 등)
- 특정 작업이나 조직에 맞춘 표준화된 상호작용 패턴을 정의합니다
// 간단한 프롬프트 예제
server.prompt(
"code-review",
{
code: z.string(),
language: z.string().optional()
},
({ code, language = "unknown" }) => ({
messages: [
{
role: "user",
content: {
type: "text",
text: `다음 ${language} 코드를 리뷰해주세요:\n\n${code}`
}
}
]
})
);프롬프트의 구성 요소
- 이름: 프롬프트를 식별하는 고유한 이름
- 설명(선택사항): 프롬프트의 용도 설명
- 인자 스키마: Zod를 사용한 입력 매개변수 정의
- 메시지 생성기: 입력을 바탕으로 메시지 구조를 생성하는 함수
프롬프트의 활용 사례
- 표준화된 질의: 조직 내 일관된 LLM 사용 패턴 정의
- 맞춤형 지시사항: 특정 도메인에 맞춘 프롬프트 템플릿
- 복합 상호작용: 여러 메시지로 구성된 상호작용 패턴
- 스타일 가이드라인: 응답 형식, 톤, 스타일을 일관되게 유지
프롬프트 구현의 핵심 요소
- 매개변수화: 동적 값을 프롬프트에 삽입할 수 있는 기능
- 다중 메시지 구조: 다양한 역할(사용자, 시스템, 보조자)의 메시지 지원
- 유효성 검사: 인자의 유효성 검사를 통한 안정적인 프롬프트 생성
- 재사용성: 공통 패턴을 위한 표준화된 프롬프트 라이브러리
4. 전송 계층(Transport)
전송 계층은 클라이언트와 서버 간의 통신 방식을 정의합니다. MCP는 다양한 환경에서 작동할 수 있도록 여러 전송 방식을 지원합니다.
전송 계층의 기본 개념
전송 계층이란 무엇인가?
- 전송 계층은 MCP 메시지의 전달 방식을 정의하는 인터페이스입니다
- 다양한 통신 프로토콜과 환경을 추상화합니다
- 클라이언트와 서버 간의 메시지 교환을 담당합니다
- JSON-RPC 형식의 메시지를 기반으로 합니다
// Transport 인터페이스 정의
export interface Transport {
start(): Promise<void>;
send(message: JSONRPCMessage, options?: { relatedRequestId?: RequestId }): Promise<void>;
close(): Promise<void>;
onclose?: () => void;
onerror?: (error: Error) => void;
onmessage?: (message: JSONRPCMessage) => void;
sessionId?: string;
}지원하는 전송 방식
StdioTransport: 표준 입출력(stdin/stdout)을 통한 통신
// 서버 측 Stdio 전송 사용 예 const transport = new StdioServerTransport(); await server.connect(transport); // 클라이언트 측 Stdio 전송 사용 예 const transport = new StdioClientTransport({ command: "node", args: ["server.js"] }); await client.connect(transport);SSETransport: Server-Sent Events(SSE)를 통한 HTTP 기반 통신
// 서버 측 SSE 전송 설정 예 app.get("/sse", async (req, res) => { const transport = new SSEServerTransport('/messages', res); await server.connect(transport); }); // 클라이언트 측 SSE 전송 예 const transport = new SSEClientTransport({ eventSourceUrl: "http://localhost:3000/sse", postUrl: "http://localhost:3000/messages" }); await client.connect(transport);WebSocketTransport: WebSocket을 통한 양방향 통신
// WebSocket 전송 설정 예 const wss = new WebSocketServer({ port: 8080 }); wss.on('connection', async (ws) => { const transport = new WebSocketServerTransport(ws); await server.connect(transport); });
전송 계층의 활용 사례
- CLI 도구: Stdio 전송을 통한 명령줄 인터페이스 통합
- 웹 애플리케이션: SSE 또는 WebSocket을 통한 웹 기반 MCP 클라이언트
- 마이크로서비스: 서비스 간 통신을 위한 전송 계층
- 임베디드 환경: 다양한 환경에 맞춘 커스텀 전송 구현
전송 계층 구현의 핵심 요소
- 프로토콜 추상화: 다양한 통신 프로토콜을 일관된 인터페이스로 추상화
- 메시지 직렬화: JSON-RPC 형식의 메시지 인코딩 및 디코딩
- 비동기 통신: Promise 기반의 비동기 메시지 전송 및 수신
- 오류 처리: 연결 오류, 타임아웃 등의 상황 처리
5. LLM 상호작용 전략
MCP는 다양한 LLM 상호작용 전략을 지원하며, 이를 통해 보다 효과적인 AI 애플리케이션을 구현할 수 있습니다.
Zero-Shot Learning
Zero-Shot Learning이란?
- 예시 없이 직접 작업을 수행하도록 LLM에 지시하는 방식입니다
- 모델이 사전에 관련 지식을 가지고 있어야 효과적입니다
- 간단하고 명확한 작업에 적합합니다
MCP에서의 구현:
// Zero-Shot Learning을 위한 프롬프트 예제
server.prompt(
"zero-shot-classification",
{
text: z.string(),
categories: z.array(z.string())
},
({ text, categories }) => ({
messages: [{
role: "user",
content: {
type: "text",
text: `다음 텍스트를 [${categories.join(', ')}] 중 하나로 분류해주세요: "${text}"`
}
}]
})
);Few-Shot Learning
Few-Shot Learning이란?
- 몇 가지 예시를 제공하여 LLM이 패턴을 학습하도록 하는 방식입니다
- 예시와 정답 쌍을 통해 모델이 작업 패턴을 이해하도록 합니다
- 복잡하거나 특수한 형식의 작업에 유용합니다
MCP에서의 구현:
// Few-Shot Learning을 위한 프롬프트 예제
server.prompt(
"few-shot-sentiment",
{ text: z.string() },
({ text }) => ({
messages: [{
role: "user",
content: {
type: "text",
text: `
다음은 텍스트의 감정을 분석하는 예시입니다:
텍스트: "오늘 날씨가 너무 좋네요!"
감정: 긍정적
텍스트: "제품이 생각보다 별로네요."
감정: 부정적
텍스트: "영화는 보통이었어요."
감정: 중립적
이제 다음 텍스트의 감정을 분석해주세요:
텍스트: "${text}"
감정: `
}
}]
})
);작업 분해(Decomposition)
작업 분해란?
- 복잡한 문제를 작은 하위 작업으로 나누어 처리하는 전략입니다
- 각 하위 작업은 독립적으로 해결한 후 결과를 통합합니다
- 복잡한 추론이나 다단계 작업에 효과적입니다
MCP에서의 구현:
// 복잡한 작업을 분해하는 도구 예제
server.tool(
"analyze-document",
{ document: z.string() },
async ({ document }, extra) => {
// 1단계: 문서에서 주요 주제 추출
const topicsResult = await extra.protocol.callTool({
name: "extract-topics",
arguments: { text: document }
});
// 2단계: 주제별 감정 분석
const topicSentiments = [];
for (const topic of JSON.parse(topicsResult.content[0].text)) {
const sentimentResult = await extra.protocol.callTool({
name: "analyze-sentiment",
arguments: { topic, text: document }
});
topicSentiments.push({
topic,
sentiment: sentimentResult.content[0].text
});
}
// 3단계: 종합 분석 결과 생성
return {
content: [{
type: "text",
text: JSON.stringify(topicSentiments, null, 2)
}]
};
}
);앙상블 기법(Ensembling)
앙상블 기법이란?
- 여러 LLM 또는 프롬프트 변형을 통해 다양한 결과를 얻고 통합하는 전략입니다
- 다양한 관점을 종합하여 보다 정확하고 균형 잡힌 결과를 얻을 수 있습니다
- 중요한 결정이나 높은 정확도가 필요한 작업에 유용합니다
MCP에서의 구현:
// 여러 모델의 결과를 앙상블하는 도구 예제
server.tool(
"ensemble-summarize",
{ text: z.string() },
async ({ text }) => {
// 여러 프롬프트 변형으로 요약 생성
const summaries = await Promise.all([
generateSummary(text, "concise"), // 간결한 요약
generateSummary(text, "detailed"), // 상세한 요약
generateSummary(text, "bullet-points") // 요점 중심 요약
]);
// 생성된 요약들을 바탕으로 최종 요약 생성
const finalSummary = await mergeSummaries(summaries);
return {
content: [{
type: "text",
text: finalSummary
}]
};
}
);이러한 다양한 LLM 상호작용 전략은 MCP의 리소스, 도구, 프롬프트를 통해 효과적으로 구현될 수 있으며, 전송 계층을 통해 클라이언트와 서버 간에 원활하게 통신됩니다. 이를 통해 개발자는 복잡한 AI 애플리케이션을 더욱 구조화되고 모듈화된 방식으로 구축할 수 있습니다.# MCP TypeScript SDK 종합 분석 보고서
목차
개요
Model Context Protocol(MCP) TypeScript SDK는 대규모 언어 모델(LLM) 애플리케이션과 외부 데이터 소스, 도구, 서비스 간의 표준화된 통신 방법을 제공하는 라이브러리입니다. 이 SDK는 LLM이 다양한 컨텍스트에 접근하고 외부 기능을 활용할 수 있게 하는 인프라를 제공하며, 클라이언트와 서버 측 구현을 모두 포함합니다.
MCP는 "컨텍스트 제공"의 관심사를 LLM 상호작용과 분리함으로써, 보다 모듈화된 접근 방식을 가능하게 합니다. 이는 웹 API와 유사하지만 특별히 LLM 상호작용을 위해 설계되었습니다.
아키텍처
MCP TypeScript SDK는 다음과 같은 주요 컴포넌트로 구성된 모듈식 아키텍처를 채택하고 있습니다:
graph TD
%% 메인 컴포넌트
SDK[MCP TypeScript SDK]
SDK --> Client[Client Module]
SDK --> Server[Server Module]
SDK --> Shared[Shared Module]
SDK --> Types[Types Module]
%% 클라이언트 모듈
Client --> ClientMain[Client Class]
Client --> ClientAuth[Auth Module]
Client --> ClientSSE[SSE Transport]
Client --> ClientStdio[Stdio Transport]
Client --> ClientWebSocket[WebSocket Transport]
Client --> ClientHTTP[HTTP Transport]
%% 서버 모듈
Server --> McpServer[McpServer Class]
Server --> ServerBase[Server Base Class]
Server --> ServerAuth[Auth Module]
Server --> ServerTransports[Transports]
Server --> Completable[Completable Utility]
ServerAuth --> AuthProviders[Auth Providers]
AuthProviders --> ProxyProvider[Proxy Provider]
ServerAuth --> AuthMiddleware[Auth Middleware]
AuthMiddleware --> BearerAuth[Bearer Auth]
AuthMiddleware --> ClientAuth[Client Auth]
AuthMiddleware --> AllowedMethods[Allowed Methods]
ServerAuth --> AuthHandlers[Auth Handlers]
AuthHandlers --> Authorize[Authorize Handler]
AuthHandlers --> Register[Register Handler]
AuthHandlers --> Token[Token Handler]
AuthHandlers --> Revoke[Revoke Handler]
AuthHandlers --> Metadata[Metadata Handler]
ServerTransports --> ServerSSE[SSE Transport]
ServerTransports --> ServerStdio[Stdio Transport]
ServerTransports --> ServerHTTP[HTTP Transport]
%% 공유 모듈
Shared --> Protocol[Protocol Class]
Shared --> Transport[Transport Interface]
Shared --> UriTemplate[URI Template]
Shared --> SharedAuth[Auth Utilities]
Shared --> SharedStdio[Stdio Utilities]
%% 타입 모듈
Types --> SchemaTypes[Schema Types]
Types --> RequestTypes[Request Types]
Types --> ResponseTypes[Response Types]
Types --> NotificationTypes[Notification Types]
%% McpServer 기능
McpServer --> Resources[Resources API]
McpServer --> Tools[Tools API]
McpServer --> Prompts[Prompts API]
McpServer --> Capabilities[Capabilities API]
Resources --> ResourceHandler[Resource Handlers]
Resources --> ResourceTemplate[Resource Templates]
Tools --> ToolHandler[Tool Handlers]
Tools --> ToolParams[Tool Parameters]
Prompts --> PromptHandler[Prompt Handlers]
Prompts --> PromptParams[Prompt Parameters]
%% 주요 연결 관계
ClientMain --> Protocol
McpServer --> ServerBase
ServerBase --> Protocol
style SDK fill:#f9f9f9,stroke:#333,stroke-width:4px
style Client fill:#e1f5fe,stroke:#333,stroke-width:2px
style Server fill:#e8f5e9,stroke:#333,stroke-width:2px
style Shared fill:#fff3e0,stroke:#333,stroke-width:2px
style Types fill:#f3e5f5,stroke:#333,stroke-width:2px
style McpServer fill:#81c784,stroke:#333,stroke-width:2px
style ClientMain fill:#4fc3f7,stroke:#333,stroke-width:2px
style Protocol fill:#ffb74d,stroke:#333,stroke-width:2px
style ServerAuth fill:#aed581,stroke:#333,stroke-width:2px이 아키텍처는 모듈성, 확장성, 유연성을 우선시하며, 다양한 전송 방식과 인증 메커니즘을 지원합니다.
핵심 구성 요소
모듈 구조
MCP TypeScript SDK는 다음과 같은 주요 모듈로 구성되어 있습니다:
Client 모듈: MCP 서버에 연결하고 리소스를 요청하며 도구를 호출하는 클라이언트 구현. 다양한 전송 메커니즘을 지원합니다.
Server 모듈: 리소스, 도구, 프롬프트를 노출하는 서버 구현. McpServer 클래스는 높은 수준의 API를 제공하여 개발자가 쉽게 서버를 구성할 수 있도록 합니다.
Shared 모듈: 클라이언트와 서버 간에 공유되는 공통 유틸리티 및 인터페이스를 포함합니다. Protocol 클래스, Transport 인터페이스, URI 템플릿 처리 등이 이에 해당합니다.
Types 모듈: 프로토콜에서 사용되는 모든 데이터 타입과 스키마 정의를 포함합니다. Zod 라이브러리를 활용한 강력한 타입 검증을 제공합니다.
주요 클래스
SDK의 핵심 기능은 다음과 같은 주요 클래스들을 통해 구현됩니다:
classDiagram
%% 기본 클래스
class Protocol {
#id: number
#pendingRequests: Map
#requestHandlers: Map
#transport: Transport
+connect(transport: Transport)
+close()
+request(req, schema, options)
+notification(notif)
+setRequestHandler(schema, handler)
+registerCapabilities(capabilities)
}
class Transport {
<<interface>>
+connect(): Promise
+close(): Promise
+sendMessage(message: string): Promise
+onMessage(callback): void
+onClose(callback): void
}
class Server {
-serverInfo: Implementation
-capabilities: ServerCapabilities
+connect(transport: Transport)
+close()
+setRequestHandler(schema, handler)
+sendResourceListChanged()
+sendToolListChanged()
+sendPromptListChanged()
+sendResourceContentsChanged()
}
class McpServer {
-server: Server
-registeredResources: Map
-registeredResourceTemplates: Map
-registeredTools: Map
-registeredPrompts: Map
+connect(transport: Transport)
+close()
+resource(name, uri, callback)
+tool(name, [description], [paramsSchema], callback)
+prompt(name, [description], [argsSchema], callback)
+isConnected()
+sendResourceListChanged()
+sendToolListChanged()
+sendPromptListChanged()
}
class Client {
-clientInfo: Implementation
-serverCapabilities: ServerCapabilities
-serverVersion: Implementation
-capabilities: ClientCapabilities
-instructions: string
+connect(transport: Transport)
+getServerCapabilities()
+getServerVersion()
+getInstructions()
+ping()
+complete(params)
+setLoggingLevel(level)
+getPrompt(params)
+listPrompts(params)
+listResources(params)
+listResourceTemplates(params)
+readResource(params)
+subscribeResource(params)
+unsubscribeResource(params)
+callTool(params)
+listTools(params)
+sendRootsListChanged()
}
class ResourceTemplate {
-uriTemplate: UriTemplate
-callbacks: object
+get uriTemplate()
+get listCallback()
+completeCallback(variable)
}
class UriTemplate {
-template: string
-segments: array
+match(uri): Variables
+toString(): string
}
%% 관계 정의
Protocol <|-- Server
Protocol <|-- Client
Server <-- McpServer
McpServer --> ResourceTemplate
ResourceTemplate --> UriTemplateProtocol: 클라이언트와 서버 모두의 기본이 되는 클래스로, 요청-응답 처리, 알림 처리, 메시지 포맷팅 등의 핵심 기능을 제공합니다.
Server: 기본 서버 구현 클래스로, 요청 처리 및 알림 전송을 담당합니다.
McpServer: Server 클래스를 감싸는 고수준 래퍼로, 리소스, 도구, 프롬프트를 쉽게 등록하고 관리할 수 있는 API를 제공합니다.
Client: MCP 서버와 통신하기 위한 클라이언트 구현으로, 각종 요청 메서드와 응답 처리 기능을 제공합니다.
ResourceTemplate: URI 템플릿과 변수 매칭을 처리하여 동적 리소스 접근을 가능하게 합니다.
UriTemplate: URI 패턴 매칭 및 파싱을 담당하는 유틸리티 클래스입니다.
전송 계층
SDK는 다양한 환경에서 작동할 수 있도록 여러 전송 메커니즘을 지원합니다:
StdioTransport: 표준 입출력을 통한 통신으로, 명령줄 도구 및 프로세스 간 통신에 적합합니다.
SSETransport: Server-Sent Events(SSE)를 통한 HTTP 기반 통신으로, 웹 기반 애플리케이션에 적합합니다.
WebSocketTransport: WebSocket을 통한 양방향 통신을 지원합니다.
StreamableHttpTransport: HTTP 기반의 스트리밍 통신을 지원합니다.
이러한 다양한 전송 옵션은 SDK가 CLI 환경부터 웹 서버, 브라우저 애플리케이션에 이르기까지 다양한 컨텍스트에서 사용될 수 있게 합니다.
요청 처리 흐름
서버 초기화 과정
MCP 서버의 초기화 과정은 다음과 같습니다:
- McpServer 인스턴스 생성: 서버 이름, 버전 등의 기본 정보 설정
- 리소스, 도구, 프롬프트 등록:
resource(),tool(),prompt()메서드를 통한 기능 등록 - 전송 계층 설정: 사용할 통신 방식(stdio, SSE 등)에 맞는 Transport 객체 생성
- 서버 연결:
connect()메서드를 통해 전송 계층과 연결하고 메시지 수신 대기
요청 처리 상세 플로우
MCP 서버에서의 요청 처리 흐름은 다음과 같은 상세한 단계를 거칩니다:
sequenceDiagram
participant Client
participant Transport
participant Protocol as Protocol (Server)
participant ServerClass as Server Class
participant McpServer
participant Handler as Request Handler
participant Resource as Resource/Tool/Prompt
participant External as External System
Client->>Transport: 요청 메시지 전송
Transport->>Protocol: 메시지 수신 및 파싱
Protocol->>Protocol: 메시지 ID 및 타입 확인
Protocol->>ServerClass: 요청 유형에 맞는 핸들러 조회
alt 일반 Server 핸들러
ServerClass->>Handler: 등록된 핸들러로 요청 전달
else McpServer 핸들러
ServerClass->>McpServer: 고수준 API 핸들러로 요청 전달
alt 리소스 요청
McpServer->>McpServer: 요청 URI 매칭
McpServer->>Resource: 리소스 핸들러 호출
Resource->>External: 필요시 외부 시스템 접근
External->>Resource: 데이터 반환
Resource->>McpServer: 리소스 컨텐츠 반환
else 도구 호출
McpServer->>McpServer: 도구 이름 매칭
McpServer->>McpServer: 파라미터 검증 (Zod)
McpServer->>Resource: 도구 콜백 함수 호출
Resource->>External: 필요시 외부 시스템과 통신
External->>Resource: 처리 결과 반환
Resource->>McpServer: 도구 실행 결과 반환
else 프롬프트 요청
McpServer->>McpServer: 프롬프트 이름 매칭
McpServer->>McpServer: 인자 검증 (Zod)
McpServer->>Resource: 프롬프트 콜백 함수 호출
Resource->>McpServer: 프롬프트 메시지 반환
end
McpServer->>ServerClass: 처리 결과 반환
end
ServerClass->>Protocol: 결과 포맷팅
Protocol->>Transport: 응답 메시지 전송
Transport->>Client: 클라이언트에 응답 전달이 흐름도는 MCP 서버 내에서 요청이 어떻게 처리되는지 자세히 보여줍니다. Protocol 레이어에서 메시지를 수신하고 파싱한 후, 적절한 핸들러로 라우팅하여 처리하고, 결과를 다시 클라이언트에게 반환하는 과정이 포함됩니다.
리소스 처리 메커니즘
리소스 처리는 다음과 같은 단계로 이루어집니다:
- URI 매칭: 요청된 URI가 정적 리소스 또는 리소스 템플릿과 매칭되는지 확인
- 변수 추출: URI 템플릿의 경우, URI에서 변수 값을 추출
- 리소스 콜백 호출: 매칭된 리소스의 콜백 함수 호출
- 결과 반환: 리소스 콘텐츠를 클라이언트에 반환
다음은 리소스 요청 처리의 자세한 플로우입니다:
```mermaid
sequenceDiagram
participant Client
participant Server as MCP Server
participant RouterHandler as Resources Router Handler
participant Static
'AI' 카테고리의 다른 글
| Model Context Protocol (MCP): AI 애플리케이션을 위한 통합 프로토콜 (0) | 2025.04.13 |
|---|---|
| MCP(Model Context Protocol) 서버 개발 가이드: LLM과 외부 도구의 완벽한 통합 (0) | 2025.04.11 |
| MCP(Model Context Protocol) 클라이언트 개발 가이드: LLM과 외부 도구 통합하기 (0) | 2025.04.11 |
| MCP(Model Context Protocol)의 보안 위험과 방지책 (0) | 2025.04.09 |
| MCP란? (0) | 2025.04.09 |