루트 제공하기

루트 제공하기 (Provide roots)

::: warning Deprecated — SEP-2577 대신 경로를 도구 인자, 리소스 URI, 또는 호스트 설정으로 넘기세요. 루트(roots) 는 프로토콜 버전 2026-07-28 (SEP-2577) 부터 deprecated 이고, 2025 시대 연결에서는 최소 12개월 동안 동작을 유지해요 — deprecated 기능 레지스트리 를 보세요. :::

먼저 옮겨 가세요

루트 는 클라이언트가 파일 작업의 경계로 서버에 건네주는 file:// URI예요. 2026-07-28 리비전은 그것을 싣는 요청을 deprecated 하고, 그 자리를 대체하는 것은 없어요 — 서버에 경로를 직접 주면 됩니다.

호출이 동작해야 할 경로를 도구 인자로 보내거나(도구), 서버가 소유한 위치를 리소스로 노출하거나(리소스), 고정 디렉터리를 서버의 설정에 넣으면 돼요. 이 페이지의 나머지는 아직 2025 시대 서버에 응답하는 클라이언트가 deprecation 창 동안 쓸 루트 API를 다룹니다.

루트 기능 선언하기

Client 생성자의 capabilities 에 있는 roots 는 서버에게 목록을 요청해도 된다고 알려 줘요. listChanged: true 는 목록이 바뀌었을 때 알려 줄 수 있는 권한도 줍니다.

import { Client } from '@modelcontextprotocol/client';

const client = new Client({ name: 'workspace-client', version: '1.0.0' }, { capabilities: { roots: { listChanged: true } } });

핸들러를 등록하기 전에 기능을 선언하세요. 선언이 없으면 setRequestHandler('roots/list', …) 가 throw 됩니다.

roots/list 에 답하기

setRequestHandler('roots/list', …) 는 { roots } 를 반환해요. 모든 uri 는 file:// 로 시작해야 하고, name 은 선택입니다.

const roots = [
    { uri: 'file:///home/user/projects/my-app', name: 'My App' },
    { uri: 'file:///home/user/data', name: 'Data' }
];

client.setRequestHandler('roots/list', async () => {
    return { roots };
});

roots/list 를 요청한 연결된 서버는 핸들러가 돌려준 값을 정확히 받아요.

[
  { uri: 'file:///home/user/projects/my-app', name: 'My App' },
  { uri: 'file:///home/user/data', name: 'Data' }
]

루트는 자문(advisory) 경계이지 접근 허가가 아니에요. 서버는 여전히 자기 권한으로 파일시스템에 닿고, SDK는 어느 쪽에도 이 목록을 강제하지 않습니다.

::: info 2026-07-28 연결에는 서버에서 클라이언트로 가는 요청 채널이 없어요. 같은 핸들러가 input_required 결과에 내장된 roots/list 요청을 처리합니다 — 프로토콜 버전 을 보세요. :::

루트가 바뀌었을 때 서버에 알리기

sendRootsListChanged() 는 notifications/roots/list_changed 를 보냅니다. 위에서 선언한 listChanged: true 가 필요해요.

roots.push({ uri: 'file:///home/user/projects/another-app', name: 'Another app' });
await client.sendRootsListChanged();

이 알림은 payload를 갖고 있지 않아요. 그것을 지켜보는 서버는 roots/list 를 다시 요청해 갱신된 목록을 받습니다.

[
  { uri: 'file:///home/user/projects/my-app', name: 'My App' },
  { uri: 'file:///home/user/data', name: 'Data' },
  {
    uri: 'file:///home/user/projects/another-app',
    name: 'Another app'
  }
]

요약

루트는 deprecated (SEP-2577) 예요. 경로는 도구 인자, 리소스 URI, 또는 설정으로 넘기세요.
Client 생성자의 capabilities: { roots: { listChanged: true } } 가 기능을 선언하고, roots/list 핸들러는 선언한 뒤에만 등록해야 합니다.
핸들러는 { roots } 를 돌려주고, 모든 루트 uri 는 file:// 로 시작해요.
루트는 자문 경계이지 접근 허가가 아닙니다.
sendRootsListChanged() 가 목록이 바뀌었음을 서버에 알리고, 서버 스스로 roots/list 를 다시 요청해요.