메인 콘텐츠로 건너뛰기

​
개요

폴더 검색 도구(search_user_folders와 search_team_folders)는 개인 또는 팀 폴더 계층 안에서 이름으로 폴더를 찾는 일관된 방법을 제공해요. 두 도구 모두 NFC 정규화와 함께 대소문자를 구분하지 않는 부분 문자열 매칭을 사용하므로 한국어를 비롯한 CJK 텍스트도 안정적으로 매칭돼요.
  • search_user_folders — 개인 폴더 구조를 검색해요(사용자 기반 API key 필요).
  • search_team_folders — 호출자가 접근할 수 있는 팀 폴더를 검색해요. 개인 API key로는 팀 멤버십을 통해 접근 가능한 폴더를 반환하고, 팀 API key로는 전체 팀 폴더를 반환해요. 호출자에게 팀 멤버십이 없으면 빈 목록을 반환해요.
두 도구는 시그니처와 동작이 동일하고, 유일한 차이는 어떤 폴더 범위를 검색하느냐예요. 주요 사용 사례:
  • 이름의 일부만 기억날 때 특정 폴더 찾기(예: “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_user_folders와 search_team_folders는 동일한 파라미터를 받아요:
ParameterTypeRequiredDescription
keywordstringOptional검색할 폴더 이름 부분 문자열(대소문자 구분 안 함, NFC 정규화). 생략하면 모든 폴더를 열거해요.
cursorstringOptional이전 nextCursor에서 받은 페이지네이션 cursor. 다음 페이지를 가져오려면 이걸 전달하세요.
sizenumberOptional페이지당 결과 수(기본값 30, 최대 100).

​
keyword (선택)

대소문자를 구분하지 않는 부분 문자열 매칭이에요. 검색은 한국어, 일본어, 중국어를 비롯한 CJK 텍스트를 안정적으로 처리하기 위해 NFC(Canonical Decomposition 후 Canonical Composition)로 정규화돼요. 빈 keyword이거나 생략하면 모든 폴더를 페이지네이션과 함께 반환해요. 예시:
  • "general"은 "0.General", "General", "general-things"에 매칭돼요(매칭 위치, 그다음 이름 길이 순으로 정렬).
  • "네이버"는 "네이버 모니터링", "0.네이버", "팀별 > 네이버"에 매칭돼요.

​
cursor (선택)

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

​
size (선택)

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

​
응답 형식

​
성공 응답 (search_user_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=="
}
필드 설명:
FieldTypeDescription
content[]array검색 결과(권장 필드).
content[].folderIdnumber안정적인 폴더 식별자.
content[].namestring폴더 이름(예: "General", "Q1 Planning").
content[].pathstringbreadcrumb 경로(예: "Engineering > Q1 Planning > Sprint 1"), >로 연결돼요. 최상위 폴더는 path가 name과 같아요.
folders[]arraycontent의 레거시 별칭. 두 배열은 동일한 데이터를 담아요. 클라이언트가 선호하는 쪽을 고르세요.
totalnumberkeyword에 매칭되는 폴더의 총 개수(모든 페이지에 걸친 전체 결과 집합).
totalSizenumber이 페이지의 결과 수.
nextCursorstring | null다음 페이지를 위한 cursor. 더 이상 결과가 없으면 null.
응답에는 하위 호환을 위해 content(권장, 최신 명명)와 folders(레거시 별칭)가 모두 포함돼요. 둘은 같은 배열 객체를 참조하므로 코드에서 선호하는 쪽을 고르고 다른 쪽은 무시하세요.

​
사용 예시

​
예시 1: search_user_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"
}

​
정렬 순서

결과는 매칭 위치 기준으로, 그다음 폴더 이름 길이 기준(매칭 위치가 같으면 짧은 이름이 상위)으로 정렬돼요:
  1. 매칭 위치 오름차순 — name이 keyword로 시작하는 폴더가 이름 뒷부분에서 keyword를 포함하는 폴더보다 상위에 와요.
    • keyword="general" → "General"(위치 0)이 "0.General"(위치 2)보다 상위.
  2. 이름 길이 오름차순 — 매칭 위치가 같으면 짧은 이름이 상위에 와요.
    • 둘 다 위치 0에서 “gen”에 매칭: "General"(7자)이 "General Announcements"(21자)보다 상위.
이렇게 해서 가장 구체적인 매칭이 먼저 나타나요.

​
권장 사례

search_user_folders는 사용자 기반 API key가 필요해요. 팀 전용 API key는 403 TEAM_REQUIRED 오류를 반환해요. 사용자 API key는 Tiro Platform API Keys에서 만드세요.
search_team_folders는 사용자 기반 API key와 팀 기반 API key를 모두 받아요. 개인 API key로는 팀 멤버십을 통해 접근 가능한 팀 폴더로 응답이 필터링되고, 팀 API key로는 전체 팀 폴더 트리가 포함돼요. 호출자에게 팀 멤버십이 없으면 응답은 빈 목록이에요(오류가 아님).
한국어, 일본어, 중국어 텍스트는 서버 측에서 자동으로 NFC 정규화돼요. keyword를 미리 전처리할 필요 없이 원본 텍스트를 그대로 전달하면 매칭 엔진이 알아서 처리해요.예시: keyword="네이버"는 같은 텍스트의 결합형 또는 분해형 폴더에 모두 매칭돼요.
항상 이전 응답에서 반환된 nextCursor를 사용하세요. offset을 직접 계산하려고 하지 마세요. 페이지네이션 동작은 향후 릴리스에서 바뀔 수 있어요.
필터 없이 폴더의 전체 목록을 가져오려면 keyword를 생략하거나 빈 문자열을 전달하세요. size와 nextCursor로 전체 결과 집합을 페이지네이션하세요.

​
자주 발생하는 오류

​
사용자 API key 필요

해결 방법: 팀 API key로 search_user_folders를 호출했어요. 사용자 기반 API key로 전환하거나, 팀 폴더가 필요하면 search_team_folders를 사용하세요.

​
권한 scope 부족

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

​
토큰 사용량

OperationTokens
빈 keyword (모든 폴더 열거)~200–500
keyword 검색~200–500
폴더 검색은 가벼워요. 결과에는 콘텐츠가 아니라 이름과 경로만 포함돼요.

​
scope 요구 사항

search_user_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는 사용되지 않아요.

​
관련 도구

  • list_notes — filter.folderId를 사용해 특정 폴더 안의 노트를 찾아요(별도의 “폴더 목록” 도구가 필요 없어요).
  • search_notes — filter.folderId로 폴더 안의 노트를 검색해요(keyword가 필수인 심층 검색).