폴더 검색 - Tiro Docs

개요

폴더 검색 도구(search_private_folders와 search_team_folders)는 개인 또는 팀 폴더 계층 안에서 이름으로 폴더를 찾는 일관된 방법을 제공해요. 두 도구 모두 NFC 정규화와 함께 대소문자를 구분하지 않는 부분 문자열 매칭을 사용하므로 한국어를 비롯한 CJK 텍스트도 안정적으로 매칭돼요.

search_private_folders — 개인(공유되지 않은) 폴더를 검색해요.
search_team_folders — 팀(워크스페이스 공유) 폴더를 검색해요.

두 도구는 시그니처와 동작이 동일하고, 유일한 차이는 개인 폴더를 검색하느냐 팀 공유 폴더를 검색하느냐예요. 둘 다 mcp:folders:read scope가 필요하고 기본적으로 API key의 워크스페이스에서 동작해요 — 다른 워크스페이스를 대상으로 하려면 명시적인 workspaceGuid(list_workspaces에서 확인)를 전달하세요. 주요 사용 사례:

이름의 일부만 기억날 때 특정 폴더 찾기(예: “general”은 “0.General”, “General”, “general-things”에 매칭).
워크스페이스의 모든 폴더 열거하기(빈 keyword는 전체를 페이지네이션과 함께 반환).
한국어 검색: keyword="네이버"는 "네이버 모니터링", "0.네이버" 등에 매칭.

핵심 기능:

대소문자를 구분하지 않는 부분 문자열 매칭(CJK 안정성을 위해 NFC 정규화).
폴더는 매칭 위치(이름 시작 부분일수록 상위) 기준으로, 그다음 이름 길이(짧을수록 상위) 기준으로 정렬돼요.
각 결과에는 폴더의 breadcrumb 경로가 포함돼요(예: "Engineering > Q1 Planning > Sprint 1").
빈 keyword는 모든 폴더를 페이지네이션과 함께 반환해요.
하위 호환을 위한 이중 응답 필드: content(권장)와 folders(레거시 별칭).

v1 구현 참고: 이 도구들은 호출할 때마다 상위 폴더 트리를 한 번 가져와 서버 측에서 필터링해요. 네이티브 백엔드 폴더 검색 endpoint는 v2 로드맵에 있어요. 추가되더라도 MCP 시그니처는 동일하게 유지돼요. 이는 구현 세부 사항이에요.

파라미터

search_private_folders와 search_team_folders는 동일한 파라미터를 받아요:

Parameter	Type	Required	Description
`keyword`	string	Optional	검색할 폴더 이름 부분 문자열(대소문자 구분 안 함, NFC 정규화). 생략하면 모든 폴더를 열거해요.
`cursor`	string	Optional	이전 `nextCursor`에서 받은 페이지네이션 cursor. 다음 페이지를 가져오려면 이걸 전달하세요.
`size`	number	Optional	페이지당 결과 수(기본값 `30`, 최대 `100`).
`workspaceGuid`	string	Optional	워크스페이스 GUID(`list_workspaces`에서 확인). 생략하면 API key의 워크스페이스를 사용하고, 하나를 전달하면 다른 워크스페이스를 대상으로 해요.

keyword (선택)

대소문자를 구분하지 않는 부분 문자열 매칭이에요. 검색은 한국어, 일본어, 중국어를 비롯한 CJK 텍스트를 안정적으로 처리하기 위해 NFC(Canonical Decomposition 후 Canonical Composition)로 정규화돼요. 빈 keyword이거나 생략하면 모든 폴더를 페이지네이션과 함께 반환해요. 예시:

"general"은 "0.General", "General", "general-things"에 매칭돼요(매칭 위치, 그다음 이름 길이 순으로 정렬).
"네이버"는 "네이버 모니터링", "0.네이버", "팀별 > 네이버"에 매칭돼요.

cursor (선택)

다음 페이지를 가져오려면 이전 응답의 nextCursor를 전달하세요. 첫 페이지에서는 생략하세요.

size (선택)

페이지당 결과 수예요. 기본값 30, 최대 100이에요. 페이지가 작을수록 응답이 빠르고, 클수록 왕복 횟수가 줄어요.

응답 형식

성공 응답 (search_private_folders)

{
  "content": [
    {
      "folderId": 12345,
      "name": "General",
      "path": "General"
    },
    {
      "folderId": 12346,
      "name": "Q1 Planning",
      "path": "Engineering > Q1 Planning"
    }
  ],
  "folders": [
    {
      "folderId": 12345,
      "name": "General",
      "path": "General"
    },
    {
      "folderId": 12346,
      "name": "Q1 Planning",
      "path": "Engineering > Q1 Planning"
    }
  ],
  "total": 47,
  "totalSize": 2,
  "nextCursor": "eyJvZmZzZXQiOjMwfQ=="
}

필드 설명:

Field	Type	Description
`content[]`	array	검색 결과(권장 필드).
`content[].folderId`	number	안정적인 폴더 식별자.
`content[].name`	string	폴더 이름(예: `"General"`, `"Q1 Planning"`).
`content[].path`	string	breadcrumb 경로(예: `"Engineering > Q1 Planning > Sprint 1"`), `>`로 연결돼요. 최상위 폴더는 `path`가 `name`과 같아요.
`folders[]`	array	`content`의 레거시 별칭. 두 배열은 동일한 데이터를 담아요. 클라이언트가 선호하는 쪽을 고르세요.
`total`	number	keyword에 매칭되는 폴더의 총 개수(모든 페이지에 걸친 전체 결과 집합).
`totalSize`	number	이 페이지의 결과 수.
`nextCursor`	string \| null	다음 페이지를 위한 cursor. 더 이상 결과가 없으면 `null`.

응답에는 하위 호환을 위해 content(권장, 최신 명명)와 folders(레거시 별칭)가 모두 포함돼요. 둘은 같은 배열 객체를 참조하므로 코드에서 선호하는 쪽을 고르고 다른 쪽은 무시하세요.

사용 예시

예시 1: search_private_folders — 단순 keyword

요청:

{
  "keyword": "general"
}

“general”에 매칭되는(대소문자 구분 안 함) 모든 개인 폴더를 페이지네이션과 함께 반환해요. 응답:

{
  "content": [
    {
      "folderId": 100,
      "name": "General",
      "path": "General"
    },
    {
      "folderId": 101,
      "name": "0.General Announcements",
      "path": "General Folder > 0.General Announcements"
    }
  ],
  "total": 2,
  "totalSize": 2,
  "nextCursor": null
}

예시 2: search_team_folders — 한국어 keyword

요청:

{
  "keyword": "네이버"
}

이름에 “네이버”가 들어간 모든 팀 폴더를 반환해요(CJK 매칭을 위해 NFC 정규화). 응답:

{
  "content": [
    {
      "folderId": 200,
      "name": "네이버",
      "path": "파트너십 > 네이버"
    },
    {
      "folderId": 201,
      "name": "네이버 API 모니터링",
      "path": "기술 > 파트너 > 네이버 API 모니터링"
    }
  ],
  "total": 2,
  "totalSize": 2,
  "nextCursor": null
}

예시 3: 모든 폴더 열거 (빈 keyword)

요청:

{
  "keyword": "",
  "size": 50
}

처음 50개 폴더(모든 최상위 및 중첩 폴더)를 특정 순서 없이 반환해요. 응답:

{
  "content": [
    { "folderId": 1, "name": "Engineering", "path": "Engineering" },
    { "folderId": 2, "name": "Q1 Planning", "path": "Engineering > Q1 Planning" },
    { "folderId": 3, "name": "General", "path": "General" }
  ],
  "total": 137,
  "totalSize": 3,
  "nextCursor": "eyJvZmZzZXQ6NTB9"
}

예시 4: 페이지네이션

첫 페이지 (cursor 생략):

{
  "keyword": "sprint",
  "size": 20
}

두 번째 페이지 (첫 응답의 nextCursor 사용):

{
  "keyword": "sprint",
  "size": 20,
  "cursor": "eyJvZmZzZXQ6MjB9"
}

정렬 순서

결과는 매칭 위치 기준으로, 그다음 폴더 이름 길이 기준(매칭 위치가 같으면 짧은 이름이 상위)으로 정렬돼요:

매칭 위치 오름차순 — name이 keyword로 시작하는 폴더가 이름 뒷부분에서 keyword를 포함하는 폴더보다 상위에 와요.
- keyword="general" → "General"(위치 0)이 "0.General"(위치 2)보다 상위.
이름 길이 오름차순 — 매칭 위치가 같으면 짧은 이름이 상위에 와요.
- 둘 다 위치 0에서 “gen”에 매칭: "General"(7자)이 "General Announcements"(21자)보다 상위.

이렇게 해서 가장 구체적인 매칭이 먼저 나타나요.

권장 사례

API key 타입이 아니라 폴더 타입으로 도구를 고르세요

search_private_folders는 개인(공유되지 않은) 폴더를 검색하고, search_team_folders는 팀(워크스페이스 공유) 폴더를 검색해요. 둘 다 mcp:folders:read scope가 있는 key면 받아요. 도구는 폴더 타입으로 고르세요. 매칭되는 폴더가 없으면 결과는 오류가 아니라 빈 목록이에요.

workspaceGuid로 특정 워크스페이스를 대상으로 하기

두 도구 모두 기본적으로 API key의 워크스페이스에서 동작해요. 접근 가능한 다른 워크스페이스의 폴더를 검색하려면 list_workspaces에서 얻은 명시적인 workspaceGuid를 전달하세요.

CJK 텍스트는 NFC 정규화에 맡기세요

한국어, 일본어, 중국어 텍스트는 서버 측에서 자동으로 NFC 정규화돼요. keyword를 미리 전처리할 필요 없이 원본 텍스트를 그대로 전달하면 매칭 엔진이 알아서 처리해요.예시: keyword="네이버"는 같은 텍스트의 결합형 또는 분해형 폴더에 모두 매칭돼요.

offset이 아니라 nextCursor로 페이지네이션하세요

항상 이전 응답에서 반환된 nextCursor를 사용하세요. offset을 직접 계산하려고 하지 마세요. 페이지네이션 동작은 향후 릴리스에서 바뀔 수 있어요.

모든 폴더를 열거하려면 빈 keyword를 사용하세요

필터 없이 폴더의 전체 목록을 가져오려면 keyword를 생략하거나 빈 문자열을 전달하세요. size와 nextCursor로 전체 결과 집합을 페이지네이션하세요.

자주 발생하는 오류

권한 scope 부족

해결 방법: API key에 mcp:folders:read scope가 없어요. 올바른 scope로 새 key를 발급하거나 워크스페이스 관리자에게 권한 부여를 요청하세요.

토큰 사용량

Operation	Tokens
빈 keyword (모든 폴더 열거)	~200–500
keyword 검색	~200–500

폴더 검색은 가벼워요. 결과에는 콘텐츠가 아니라 이름과 경로만 포함돼요.

scope 요구 사항

search_private_folders와 search_team_folders는 모두 mcp:folders:read scope가 필요해요. API key는 Tiro Platform API Keys에서 구성하세요.

참고: mcp:folders:write scope는 더 이상 존재하지 않아요(2026-05-06 기준). 모든 폴더 쓰기 작업이 제거됐어요. mcp:folders:write가 있는 오래된 API key가 있다면 무시돼요. 이 scope는 사용되지 않아요.

​개요

​파라미터

​keyword (선택)

​cursor (선택)

​size (선택)

​응답 형식

​성공 응답 (search_private_folders)

​사용 예시

​예시 1: search_private_folders — 단순 keyword

​예시 2: search_team_folders — 한국어 keyword

​예시 3: 모든 폴더 열거 (빈 keyword)

​예시 4: 페이지네이션

​정렬 순서

​권장 사례

​자주 발생하는 오류

​권한 scope 부족

​토큰 사용량

​scope 요구 사항

​관련 도구

개요

파라미터

keyword (선택)

cursor (선택)

size (선택)

응답 형식

성공 응답 (search_private_folders)

사용 예시

예시 1: search_private_folders — 단순 keyword

예시 2: search_team_folders — 한국어 keyword

예시 3: 모든 폴더 열거 (빈 keyword)

예시 4: 페이지네이션

정렬 순서

권장 사례

자주 발생하는 오류

권한 scope 부족

토큰 사용량

scope 요구 사항

관련 도구