byteforce

CPN 한국어 자습서 · 외부 문서 한국어 미러

MCP 문서 · Specification

루트

Roots · 원문: modelcontextprotocol.io/specification/2025-11-25/client/roots

아래는 원문을 한국어로 옮긴 미러입니다. 코드·명령은 원문 그대로이며, 가장 최신 정보는 하단 원문 링크에서 확인하세요.

MCP(Model Context Protocol)는 클라이언트가 파일시스템 "루트(roots)"를 서버에 노출하는 표준화된 방법을 제공합니다. 루트(root)는 서버가 파일시스템 내에서 작업할 수 있는 범위를 정의하여, 어떤 디렉터리와 파일에 접근할 수 있는지 서버가 이해할 수 있도록 합니다. 서버는 지원하는 클라이언트에서 루트 목록을 요청하고, 해당 목록이 변경될 때 알림을 받을 수 있습니다.

사용자 상호작용 모델

MCP에서 루트는 일반적으로 워크스페이스(workspace) 또는 프로젝트 구성 인터페이스를 통해 노출됩니다.

예를 들어, 구현체는 사용자가 서버가 접근해야 하는 디렉터리와 파일을 선택할 수 있는 워크스페이스/프로젝트 선택기를 제공할 수 있습니다. 이는 버전 관리 시스템이나 프로젝트 파일로부터의 자동 워크스페이스 감지와 결합될 수 있습니다.

다만 구현체는 필요에 맞는 어떠한 인터페이스 패턴을 통해서도 루트를 자유롭게 노출할 수 있습니다. 프로토콜 자체는 특정 사용자 상호작용 모델을 강제하지 않습니다.

기능 선언

루트를 지원하는 클라이언트는 초기화 중에 roots 기능을 선언해야 합니다(MUST).

코드 · 명령
{
  "capabilities": {
    "roots": {
      "listChanged": true
    }
  }
}

listChanged는 루트 목록이 변경될 때 클라이언트가 알림을 발행할지 여부를 나타냅니다.

프로토콜 메시지

루트 목록 조회

루트를 조회하기 위해 서버는 roots/list 요청을 전송합니다.

요청:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "roots/list"
}

응답:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "roots": [
      {
        "uri": "file:///home/user/projects/myproject",
        "name": "My Project"
      }
    ]
  }
}

루트 목록 변경

루트가 변경되면, listChanged를 지원하는 클라이언트는 알림을 전송해야 합니다(MUST).

코드 · 명령
{
  "jsonrpc": "2.0",
  "method": "notifications/roots/list_changed"
}

메시지 흐름

코드 · 명령
sequenceDiagram
    participant Server
    participant Client

    Note over Server,Client: Discovery
    Server->>Client: roots/list
    Client-->>Server: Available roots

    Note over Server,Client: Changes
    Client--)Server: notifications/roots/list_changed
    Server->>Client: roots/list
    Client-->>Server: Updated roots

데이터 타입

Root

루트 정의에는 다음이 포함됩니다.

다양한 사용 사례에 대한 루트 예시:

프로젝트 디렉터리

코드 · 명령
{
  "uri": "file:///home/user/projects/myproject",
  "name": "My Project"
}

복수 저장소

코드 · 명령
[
  {
    "uri": "file:///home/user/repos/frontend",
    "name": "Frontend Repository"
  },
  {
    "uri": "file:///home/user/repos/backend",
    "name": "Backend Repository"
  }
]

오류 처리

클라이언트는 일반적인 실패 사례에 대해 표준 JSON-RPC 오류를 반환해야 합니다(SHOULD).

오류 예시:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Roots not supported",
    "data": {
      "reason": "Client does not have roots capability"
    }
  }
}

보안 고려사항

  1. 클라이언트는 다음을 수행해야 합니다(MUST). * 적절한 권한이 있는 루트만 노출 * 경로 탐색을 방지하기 위해 모든 루트 URI 검증 * 적절한 접근 제어 구현 * 루트 접근성 모니터링

  2. 서버는 다음을 수행해야 합니다(SHOULD). * 루트를 사용할 수 없게 되는 경우 처리 * 작업 중 루트 경계 준수 * 제공된 루트에 대한 모든 경로 검증

구현 가이드라인

  1. 클라이언트는 다음을 수행해야 합니다(SHOULD). * 서버에 루트를 노출하기 전에 사용자 동의 요청 * 루트 관리를 위한 명확한 사용자 인터페이스 제공 * 노출하기 전에 루트 접근성 검증 * 루트 변경 사항 모니터링

  2. 서버는 다음을 수행해야 합니다(SHOULD). * 사용 전에 루트 기능 확인 * 루트 목록 변경 사항을 정상적으로 처리 * 작업에서 루트 경계 준수 * 루트 정보를 적절히 캐시(cache)

원문(영어): https://modelcontextprotocol.io/specification/2025-11-25/client/roots · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Model Context Protocol)에게 있습니다.

원문(영어): https://modelcontextprotocol.io/specification/2025-11-25/client/roots