CPN 한국어 자습서 · 외부 문서 한국어 미러
MCP 문서 · Specification
Resources · 원문: modelcontextprotocol.io/specification/2025-11-25/server/resources
아래는 원문을 한국어로 옮긴 미러입니다. 코드·명령은 원문 그대로이며, 가장 최신 정보는 하단 원문 링크에서 확인하세요.
MCP(Model Context Protocol)는 서버가 클라이언트에 리소스(resource)를 노출하기 위한 표준화된 방법을 제공합니다. 리소스를 통해 서버는 파일, 데이터베이스 스키마, 애플리케이션별 정보 등 언어 모델에 컨텍스트를 제공하는 데이터를 공유할 수 있습니다. 각 리소스는 URI로 고유하게 식별됩니다.
MCP의 리소스는 애플리케이션 주도(application-driven) 방식으로 설계되어 있습니다. 호스트 애플리케이션이 필요에 따라 컨텍스트를 통합하는 방법을 결정합니다.
예를 들어, 애플리케이션은 다음을 수행할 수 있습니다.
단, 구현체는 필요에 맞는 어떤 인터페이스 패턴으로든 리소스를 노출할 수 있습니다. 프로토콜 자체는 특정 사용자 상호작용 모델을 강제하지 않습니다.
리소스를 지원하는 서버는 resources 기능을 반드시 선언해야 합니다(MUST).
{
"capabilities": {
"resources": {
"subscribe": true,
"listChanged": true
}
}
}
이 기능은 두 가지 선택적 특성을 지원합니다.
subscribe: 클라이언트가 개별 리소스 변경 알림을 구독할 수 있는지 여부listChanged: 사용 가능한 리소스 목록이 변경될 때 서버가 알림을 보낼지 여부subscribe와 listChanged 모두 선택 사항입니다. 서버는 둘 다 지원하지 않거나, 하나만 지원하거나, 둘 다 지원할 수 있습니다.
{
"capabilities": {
"resources": {} // 두 기능 모두 미지원
}
}
{
"capabilities": {
"resources": {
"subscribe": true // 구독만 지원
}
}
}
{
"capabilities": {
"resources": {
"listChanged": true // 목록 변경 알림만 지원
}
}
}
사용 가능한 리소스를 발견하기 위해 클라이언트는 resources/list 요청을 보냅니다. 이 작업은 페이지네이션을 지원합니다.
요청:
{
"jsonrpc": "2.0",
"id": 1,
"method": "resources/list",
"params": {
"cursor": "optional-cursor-value"
}
}
응답:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"resources": [
{
"uri": "file:///project/src/main.rs",
"name": "main.rs",
"title": "Rust Software Application Main File",
"description": "Primary application entry point",
"mimeType": "text/x-rust",
"icons": [
{
"src": "https://example.com/rust-file-icon.png",
"mimeType": "image/png",
"sizes": ["48x48"]
}
]
}
],
"nextCursor": "next-page-cursor"
}
}
리소스 콘텐츠를 가져오기 위해 클라이언트는 resources/read 요청을 보냅니다.
요청:
{
"jsonrpc": "2.0",
"id": 2,
"method": "resources/read",
"params": {
"uri": "file:///project/src/main.rs"
}
}
응답:
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"contents": [
{
"uri": "file:///project/src/main.rs",
"mimeType": "text/x-rust",
"text": "fn main() {\n println!(\"Hello world!\");\n}"
}
]
}
}
리소스 템플릿을 통해 서버는 URI 템플릿을 사용하여 파라미터화된 리소스를 노출할 수 있습니다. 인수는 완성 API를 통해 자동 완성될 수 있습니다.
요청:
{
"jsonrpc": "2.0",
"id": 3,
"method": "resources/templates/list"
}
응답:
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"resourceTemplates": [
{
"uriTemplate": "file:///{path}",
"name": "Project Files",
"title": "📁 Project Files",
"description": "Access files in the project directory",
"mimeType": "application/octet-stream",
"icons": [
{
"src": "https://example.com/folder-icon.png",
"mimeType": "image/png",
"sizes": ["48x48"]
}
]
}
]
}
}
사용 가능한 리소스 목록이 변경되면, listChanged 기능을 선언한 서버는 다음 알림을 보내야 합니다(SHOULD).
{
"jsonrpc": "2.0",
"method": "notifications/resources/list_changed"
}
프로토콜은 리소스 변경에 대한 선택적 구독을 지원합니다. 클라이언트는 특정 리소스를 구독하고 변경 시 알림을 받을 수 있습니다.
구독 요청:
{
"jsonrpc": "2.0",
"id": 4,
"method": "resources/subscribe",
"params": {
"uri": "file:///project/src/main.rs"
}
}
업데이트 알림:
{
"jsonrpc": "2.0",
"method": "notifications/resources/updated",
"params": {
"uri": "file:///project/src/main.rs"
}
}
sequenceDiagram
participant Client
participant Server
Note over Client,Server: Resource Discovery
Client->>Server: resources/list
Server-->>Client: List of resources
Note over Client,Server: Resource Template Discovery
Client->>Server: resources/templates/list
Server-->>Client: List of resource templates
Note over Client,Server: Resource Access
Client->>Server: resources/read
Server-->>Client: Resource contents
Note over Client,Server: Subscriptions
Client->>Server: resources/subscribe
Server-->>Client: Subscription confirmed
Note over Client,Server: Updates
Server--)Client: notifications/resources/updated
Client->>Server: resources/read
Server-->>Client: Updated contents
리소스 정의에는 다음 항목이 포함됩니다.
uri: 리소스의 고유 식별자name: 리소스 이름title: 표시용 사람이 읽을 수 있는 이름(선택 사항)description: 선택적 설명icons: 사용자 인터페이스 표시용 아이콘 배열(선택 사항)mimeType: 선택적 MIME 타입size: 선택적 크기(바이트)리소스에는 텍스트 또는 바이너리 데이터가 포함될 수 있습니다.
{
"uri": "file:///example.txt",
"mimeType": "text/plain",
"text": "Resource content"
}
{
"uri": "file:///example.png",
"mimeType": "image/png",
"blob": "base64-encoded-data"
}
리소스, 리소스 템플릿, 콘텐츠 블록은 클라이언트에게 리소스 사용 또는 표시 방법에 대한 힌트를 제공하는 선택적 어노테이션을 지원합니다.
audience: 이 리소스의 의도된 대상을 나타내는 배열. 유효한 값은 "user"와 "assistant"입니다. 예를 들어, ["user", "assistant"]는 양쪽 모두에 유용한 콘텐츠를 나타냅니다.priority: 이 리소스의 중요도를 나타내는 0.0~1.0 사이의 숫자. 1은 "가장 중요"(사실상 필수), 0은 "가장 덜 중요"(완전히 선택 사항)를 의미합니다.lastModified: 리소스가 마지막으로 수정된 시점을 나타내는 ISO 8601 형식 타임스탬프(예: "2025-01-12T15:00:58Z").어노테이션이 있는 리소스 예시:
{
"uri": "file:///project/README.md",
"name": "README.md",
"title": "Project Documentation",
"mimeType": "text/markdown",
"annotations": {
"audience": ["user"],
"priority": 0.8,
"lastModified": "2025-01-12T15:00:58Z"
}
}
클라이언트는 이 어노테이션을 다음 용도로 활용할 수 있습니다.
프로토콜은 여러 표준 URI 스킴을 정의합니다. 이 목록은 완전하지 않으며, 구현체는 추가적인 커스텀 URI 스킴을 자유롭게 사용할 수 있습니다.
웹에서 사용 가능한 리소스를 나타내는 데 사용합니다.
서버는 클라이언트가 MCP 서버를 통하지 않고도 웹에서 직접 리소스를 가져와 로드할 수 있는 경우에만 이 스킴을 사용해야 합니다(SHOULD).
다른 사용 사례에서는 서버가 인터넷을 통해 리소스 콘텐츠를 다운로드하더라도 다른 URI 스킴을 사용하거나 커스텀 스킴을 정의하는 것을 권장합니다(SHOULD).
파일 시스템처럼 동작하는 리소스를 식별하는 데 사용합니다. 단, 리소스가 반드시 실제 물리적 파일 시스템에 매핑될 필요는 없습니다.
MCP 서버는 표준 MIME 타입이 없는 비정규 파일(예: 디렉터리)을 나타내기 위해 inode/directory와 같은 XDG MIME 타입으로 file:// 리소스를 식별할 수 있습니다(MAY).
Git 버전 관리 통합.
커스텀 URI 스킴은 위의 지침을 고려하여 RFC3986에 따라야 합니다(MUST).
서버는 일반적인 실패 사례에 대해 표준 JSON-RPC 오류를 반환해야 합니다(SHOULD).
-32002-32603오류 예시:
{
"jsonrpc": "2.0",
"id": 5,
"error": {
"code": -32002,
"message": "Resource not found",
"data": {
"uri": "file:///nonexistent.txt"
}
}
}
원문(영어): https://modelcontextprotocol.io/specification/2025-11-25/server/resources · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Model Context Protocol)에게 있습니다.
원문(영어): https://modelcontextprotocol.io/specification/2025-11-25/server/resources