.gif&blockId=11b00c82-b138-8050-a58b-dcbceda2ef8f)
리소스(Resources)
: 클라이언트가 읽을 수 있는 파일과 같은 데이터(API 응답이나 파일 내용 등)
•
LLM 애플리케이션이 외부 데이터와 컨텍스트에 안전하게 접근할 수 있게 해주는 메커니즘
•
리소스는 서버가 클라이언트가 읽고 LLM 상호 작용에 대한 컨텍스트로 사용할 수 있는 데이터와 콘텐츠를 노출할 수 있도록 하는 요소이다.
리소스는 애플리케이션 제어 되도록 설계되어 클라이언트 애플리케이션이 리소스를 어떻게, 언제 사용할지 결정할 수 있다. 다른 MCP 클라이언트는 리소스를 다르게 처리할 수 있다.
예:
•
Claude Desktop은 현재 사용자가 리소스를 사용하기 전에 명시적으로 선택하도록 요구한다.
•
다른 클라이언트는 휴리스틱을 기반으로 자동으로 리소스를 선택할 수 있다.
•
일부 구현에서는 AI 모델 자체가 사용할 리소스를 결정하도록 허용할 수도 있다.
서버 작성자는 리소스 지원을 구현할 때 이러한 상호 작용 패턴을 처리할 준비가 되어 있어야 한다. 모델에 데이터를 자동으로 노출하기 위해 서버 작성자는 Tools와 같은 모델 제어 기본 요소를 사용해야 한다 .
•
기본 리소스 정의
interface Resource {
// 리소스의 고유 식별자 (URI 형식)
uri: string;
// 사용자에게 표시될 이름
name: string;
// 리소스에 대한 설명
description?: string;
// 리소스의 MIME 타입
mimeType?: string;
}
TypeScript
복사
개요
•
리소스는 MCP 서버가 클라이언트에 제공하고자 하는 모든 종류의 데이터를 나타낸다.
•
다음을 포함:
◦
파일 내용
◦
데이터베이스 기록
◦
API 응답
◦
라이브 시스템 데이터
◦
스크린샷 및 이미지
◦
로그 파일
◦
그리고 더 많은 것
•
각 리소스는 고유한 URI로 식별되며 텍스트 또는 이진 데이터를 포함할 수 있다.
리소스 식별 방법(URI)
각 리소스는 고유한 URI(Uniform Resource Identifier)로 식별 ≒ 웹 주소(URL)
•
프로토콜과 경로 구조는 MCP 서버 구현에 의해 정의됩니다. 서버는 자체 사용자 정의 URI 체계를 정의할 수 있다.
•
URI 구조
[프로토콜]://[호스트]/[경로]
TypeScript
복사
◦
스키마(프로토콜): 리소스 유형 식별 (예: file://, db://, note://)
◦
경로(호스트): 리소스의 실제 위치
◦
쿼리: 선택적 매개변수
•
URI 템플릿
interface ResourceTemplate {
// URI 템플릿 (RFC 6570 기준)
uriTemplate: string;
// 템플릿 이름
name: string;
// 설명
description?: string;
// MIME 타입
mimeType?: string;
}
TypeScript
복사
리소스 내용 형식
interface ResourceContents {
// 리소스의 URI
uri: string;
// MIME 타입
mimeType?: string;
}
interface TextResourceContents extends ResourceContents {
// 텍스트 리소스: UTF-8 인코딩된 텍스트 데이터
// 소스 코드, 설정 파일, 로그, JSON/XML 데이터, 일반 텍스트 등
text: string;
}
interface BlobResourceContents extends ResourceContents {
// 바이너리 리소스: base64로 인코딩된 바이너리 데이터
// 이미지, PDF, 오디오/비디오 파일, 기타 비텍스트 형식 등
blob: string;
}
TypeScript
복사
리소스 작업
리소스 발견 방법
클라이언트가 사용 가능한 리소스를 찾는 방법은 총 두 가지
1.
직접 리소스 목록: 서버가 resources/list 엔드포인트를 통해 구체적인 리소스 목록을 제공
•
구조
{
uri: string; // Unique identifier for the resource
name: string; // Human-readable name
description?: string; // Optional description
mimeType?: string; // Optional MIME type
}
TypeScript
복사
•
예시
{
"uri": "file:///honeylogs/honeycomb.log",
"name": "honeycomb 로그",
"description": "honeycomb 로그 파일",
"mimeType": "text/plain"
}
TypeScript
복사
2.
리소스 템플릿: 동적 리소스를 위한 URI 템플릿 제공
•
구조
{
uriTemplate: string; // URI template following RFC 6570
name: string; // Human-readable name for this type
description?: string; // Optional description
mimeType?: string; // Optional MIME type for all matching resources
}
TypeScript
복사
•
예시
{
"uriTemplate": "file:///honeylogs/{date}.log",
"name": "날짜별 honeycomb 로그 파일",
"description": "특정일의 honeycomb 로그 접근"
}
TypeScript
복사
리소스 읽기
•
리소스를 읽으려면 클라이언트가 resources/read리소스 URI로 요청해야 함.
서버는 한 resources/read요청에 대한 응답으로 여러 리소스를 반환할 수 있다 .
예를 들어, 디렉토리를 읽을 때 디렉토리 내부의 파일 목록을 반환하는 데 사용할 수 있다.
•
구조
{
contents: [
{
uri: string; // The URI of the resource
mimeType?: string; // Optional MIME type
// One of:
text?: string; // For text resources
blob?: string; // For binary resources (base64 encoded)
}
]
}
TypeScript
복사
•
클라이언트가 리소스를 읽는 방법:
1.
resources/read 요청을 리소스 URI와 함께 보낸다.
2.
서버는 리소스 내용을 응답한다.
{
"contents": [
{
"uri": "file:///logs/app.log",
"mimeType": "text/plain",
"text": "로그 내용이 여기에..."
}
]
}
Python
복사
interface ReadResourceRequest {
method: "resources/read";
params: {
uri: string; // 읽을 리소스의 URI
};
}
interface ReadResourceResult {
contents: (TextResourceContents | BlobResourceContents)[];
}
TypeScript
복사
리소스 구독/업데이트
MCP는 두 가지 메커니즘을 통해 리소스에 대한 실시간 업데이트를 지원한다.
1.
목록 변경 알림: 서버가 사용 가능한 리소스 목록이 변경되면 클라이언트에 알림
2.
내용 변경 구독:
•
클라이언트가 특정 리소스를 구독 (resources/subscribe)
•
리소스가 변경되면 서버가 알림 (notifications/resources/updated)
•
클라이언트가 최신 내용을 가져옴 (resources/read)
•
필요 없으면 구독 해제 (resources/unsubscribe)
interface SubscribeRequest {
method: "resources/subscribe";
params: {
uri: string; // 구독할 리소스의 URI
};
}
interface ResourceUpdatedNotification {
method: "notifications/resources/updated";
params: {
uri: string; // 업데이트된 리소스의 URI
};
}
TypeScript
복사
모범 사례
리소스 설계
•
명확한 URI 구조: 이해하기 쉽고 예측 가능한 URI 사용
•
적절한 MIME 타입: 리소스 형식을 정확히 명시
•
유용한 메타데이터: 의미 있는 이름과 설명 제공
구현 권장사항
•
비동기 처리: 대용량 리소스 처리 시 비동기 방식 사용
•
적절한 에러 처리: 명확한 오류 메시지와 처리
•
효율적인 리소스 관리: 메모리 및 연결 관리
확장성 고려
•
버전 관리: 리소스 형식 변경 대비
•
유연한 구조: 새로운 리소스 타입 추가 용이
•
모듈화: 재사용 가능한 컴포넌트 설계
