メインコンテンツへスキップ

​
概要

フォルダ検索ツール（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="네이버" は "네이버 모니터링"、"0.네이버" などに一致します。
主な特長:
  • 大文字小文字を区別しない部分一致（CJK の信頼性のため NFC 正規化済み）。
  • フォルダは一致位置（名前の先頭に近いほど上位）で並べ替えられ、その次に名前の長さ（短いほど上位）で並べ替えられます。
  • 各結果にはフォルダのパンくずパスが含まれます（例: "Engineering > Q1 Planning > Sprint 1"）。
  • 空のキーワードはすべてのフォルダをページネーション付きで返します。
  • 後方互換性のための 2 つのレスポンスフィールド: content（推奨）と folders（レガシーエイリアス）。
v1 の実装に関する注記: これらのツールは呼び出しごとにアップストリームのフォルダツリーを一度取得し、サーバー側でフィルタリングします。ネイティブなバックエンドのフォルダ検索 endpoint は v2 ロードマップに含まれています。追加されても MCP のシグネチャは変わりません。これは実装上の詳細です。

​
パラメータ

search_user_folders と search_team_folders は同一のパラメータを受け取ります。
ParameterTypeRequiredDescription
keywordstringOptional検索するフォルダ名の部分文字列（大文字小文字を区別せず、NFC 正規化されます）。すべてのフォルダを列挙する場合は省略します。
cursorstringOptional前回の nextCursor から得たページネーション用 cursor。次のページを取得するために渡します。
sizenumberOptional1 ページあたりの結果数（デフォルト 30、最大 100）。

​
keyword (optional)

大文字小文字を区別しない部分一致です。検索は NFC（正規分解の後に正規合成）で正規化され、韓国語・日本語・中国語などの CJK テキストを確実に処理します。 キーワードが空または省略された場合は、すべてのフォルダをページネーション付きで返します。 例:
  • "general" は "0.General"、"General"、"general-things" に一致します（一致位置、次に名前の長さで並べ替え）。
  • "네이버" は "네이버 모니터링"、"0.네이버"、"팀별 > 네이버" に一致します。

​
cursor (optional)

前回のレスポンスの nextCursor を渡すと次のページを取得します。最初のページでは省略します。

​
size (optional)

1 ページあたりの結果数です。デフォルト 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[].pathstring> で結合されたパンくずパス（例: "Engineering > Q1 Planning > Sprint 1"）。トップレベルのフォルダは path が name と同じになります。
folders[]arraycontent のレガシーエイリアス。両方の配列は同一のデータを含みます。クライアントが好む方を選んでください。
totalnumberキーワードに一致するフォルダの総数（全ページにわたる結果セット全体）。
totalSizenumberこのページの結果数。
nextCursorstring | null次のページ用の cursor。これ以上結果がない場合は null。
レスポンスには後方互換性のため content（推奨、新しい命名）と folders（レガシーエイリアス）の両方が含まれます。これらは同じ配列オブジェクトを参照しています。コードが好む方を選び、もう一方は無視してください。

​
使用例

​
例 1: search_user_folders — シンプルなキーワード

リクエスト: 
{
  "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": "네이버"
}
名前に “네이버” を含むすべてのチームフォルダを返します（CJK 一致のため NFC 正規化済み）。 レスポンス: 
{
  "content": [
    {
      "folderId": 200,
      "name": "네이버",
      "path": "파트너십 > 네이버"
    },
    {
      "folderId": 201,
      "name": "네이버 API 모니터링",
      "path": "기술 > 파트너 > 네이버 API 모니터링"
    }
  ],
  "total": 2,
  "totalSize": 2,
  "nextCursor": null
}

​
例 3: すべてのフォルダを列挙（空のキーワード）

リクエスト: 
{
  "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
}
2 ページ目（最初のレスポンスの nextCursor を使用）: 
{
  "keyword": "sprint",
  "size": 20,
  "cursor": "eyJvZmZzZXQ6MjB9"
}

​
並び順

結果は一致位置で並べ替えられ、次にフォルダ名の長さで並べ替えられます（同じ一致位置では短い名前が上位）。
  1. 一致位置の昇順 — name がキーワードで始まるフォルダは、名前の後方にキーワードを含むフォルダより上位になります。
    • 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 の場合、レスポンスにはチームフォルダツリー全体が含まれます。呼び出し元がどのチームにも所属していない場合、レスポンスは空のリストになります（エラーではありません）。
韓国語・日本語・中国語のテキストはサーバー側で自動的に NFC 正規化されます。キーワードを前処理する必要はありません。生のテキストをそのまま渡せば、一致エンジンが処理します。例: keyword="네이버" は、同じテキストの合成形・分解形いずれのフォルダにも一致します。
必ず前回のレスポンスで返された nextCursor を使用してください。オフセットを自分で計算しないでください。ページネーションの動作は将来のリリースで変更される可能性があります。
フィルタリングせずにフォルダの完全なリストを取得するには、keyword を省略するか空文字列を渡してください。size と nextCursor を使って結果セット全体をページネーションします。

​
よくあるエラー

​
ユーザー API key が必要

解決方法: search_user_folders をチーム API key で呼び出しました。ユーザーベースの API key に切り替えるか、チームフォルダが必要な場合は search_team_folders を使用してください。

​
スコープが不足

解決方法: お使いの API key に mcp:folders:read スコープがありません。正しいスコープで新しいキーを生成するか、ワークスペース管理者にアクセス権の付与を依頼してください。

​
トークン使用量

OperationTokens
空のキーワード（すべてのフォルダを列挙）~200–500
キーワード検索~200–500
フォルダ検索は軽量です。結果には名前とパスのみが含まれ、コンテンツは含まれません。

​
スコープ要件

search_user_folders と search_team_folders はどちらも mcp:folders:read スコープを必要とします。API key は Tiro Platform API Keys で構成してください。
注記: mcp:folders:write スコープは（2026-05-06 時点で）もう存在しません。すべてのフォルダ書き込み操作は削除されました。mcp:folders:write を持つ古い API key をお持ちの場合、そのスコープは無視され、使用されません。

​
関連ツール

  • list_notes — filter.folderId を使って特定のフォルダ内のノートを見つけます（別途「フォルダ一覧」ツールは不要です）。
  • search_notes — filter.folderId を使ってフォルダ内のノートを検索します（キーワード必須の深い検索）。