> ## Documentation Index > Fetch the complete documentation index at: https://docs.tiro.ooo/llms.txt > Use this file to discover all available pages before exploring further. # フォルダ検索 > 個人フォルダとチームフォルダを名前で検索（ページネーション対応） ## 概要 フォルダ検索ツール（`search_private_folders` と `search_team_folders`）は、個人またはチームのフォルダ階層内でフォルダを名前から見つけるための統一された方法を提供します。どちらのツールも NFC 正規化を伴う**大文字小文字を区別しない部分一致**を使用しており、韓国語やその他の CJK テキストでも確実に一致します。 * **`search_private_folders`** — 個人の（共有されていない）フォルダを検索します。 * **`search_team_folders`** — チーム（ワークスペースで共有された）フォルダを検索します。 どちらのツールもシグネチャと動作は同一で、唯一の違いは個人フォルダとチーム共有フォルダのどちらを検索するかです。どちらも `mcp:folders:read` スコープを必要とし、デフォルトでは API key のワークスペースを対象とします。別のワークスペースを対象にする場合は、明示的な `workspaceGuid`（`list_workspaces` から取得）を渡してください。 **主なユースケース:** * 名前の一部しか覚えていないときに特定のフォルダを名前で見つける（例: "general" は "0.General"、"General"、"general-things" に一致）。 * ワークスペース内のすべてのフォルダを列挙する（空のキーワードですべてをページネーション付きで返します）。 * 韓国語文字の検索: `keyword="네이버"` は `"네이버 모니터링"`、`"0.네이버"` などに一致します。 **主な特長:** * 大文字小文字を区別しない部分一致（CJK の信頼性のため NFC 正規化済み）。 * フォルダは一致位置（名前の先頭に近いほど上位）で並べ替えられ、その次に名前の長さ（短いほど上位）で並べ替えられます。 * 各結果にはフォルダのパンくずパスが含まれます（例: `"Engineering > Q1 Planning > Sprint 1"`）。 * 空のキーワードはすべてのフォルダをページネーション付きで返します。 * 後方互換性のための 2 つのレスポンスフィールド: `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 | 1 ページあたりの結果数（デフォルト `30`、最大 `100`）。 | | `workspaceGuid` | string | Optional | ワークスペース GUID（`list_workspaces` から取得）。省略すると API key のワークスペースを使用します。指定すると別のワークスペースを対象にします。 | ### keyword (optional) 大文字小文字を区別しない部分一致です。検索は NFC（正規分解の後に正規合成）で正規化され、韓国語・日本語・中国語などの CJK テキストを確実に処理します。 キーワードが空または省略された場合は、すべてのフォルダをページネーション付きで返します。 **例:** * `"general"` は `"0.General"`、`"General"`、`"general-things"` に一致します（一致位置、次に名前の長さで並べ替え）。 * `"네이버"` は `"네이버 모니터링"`、`"0.네이버"`、`"팀별 > 네이버"` に一致します。 ### cursor (optional) 前回のレスポンスの `nextCursor` を渡すと次のページを取得します。最初のページでは省略します。 ### size (optional) 1 ページあたりの結果数です。デフォルト `30`、最大 `100`。ページが小さいほど高速に返り、大きいほど往復回数を減らせます。 ## レスポンス形式 ### 成功レスポンス (search\_private\_folders) ```json theme={"system"} { "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 | `>` で結合されたパンくずパス（例: `"Engineering > Q1 Planning > Sprint 1"`）。トップレベルのフォルダは `path` が `name` と同じになります。 | | `folders[]` | array | `content` のレガシーエイリアス。両方の配列は同一のデータを含みます。クライアントが好む方を選んでください。 | | `total` | number | キーワードに一致するフォルダの総数（全ページにわたる結果セット全体）。 | | `totalSize` | number | このページの結果数。 | | `nextCursor` | string \| null | 次のページ用の cursor。これ以上結果がない場合は `null`。 | レスポンスには後方互換性のため `content`（推奨、新しい命名）と `folders`（レガシーエイリアス）の両方が含まれます。これらは同じ配列オブジェクトを参照しています。コードが好む方を選び、もう一方は無視してください。 ## 使用例 ### 例 1: search\_private\_folders — シンプルなキーワード **リクエスト:** ```json theme={"system"} { "keyword": "general" } ``` "general" に一致するすべての個人フォルダ（大文字小文字を区別しない）をページネーション付きで返します。 **レスポンス:** ```json theme={"system"} { "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 — 韓国語のキーワード **リクエスト:** ```json theme={"system"} { "keyword": "네이버" } ``` 名前に "네이버" を含むすべてのチームフォルダを返します（CJK 一致のため NFC 正規化済み）。 **レスポンス:** ```json theme={"system"} { "content": [ { "folderId": 200, "name": "네이버", "path": "파트너십 > 네이버" }, { "folderId": 201, "name": "네이버 API 모니터링", "path": "기술 > 파트너 > 네이버 API 모니터링" } ], "total": 2, "totalSize": 2, "nextCursor": null } ``` ### 例 3: すべてのフォルダを列挙（空のキーワード） **リクエスト:** ```json theme={"system"} { "keyword": "", "size": 50 } ``` 最初の 50 件のフォルダ（トップレベルとネストされたものすべて）を、特定の順序なしで返します。 **レスポンス:** ```json theme={"system"} { "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 を省略）:** ```json theme={"system"} { "keyword": "sprint", "size": 20 } ``` **2 ページ目（最初のレスポンスの nextCursor を使用）:** ```json theme={"system"} { "keyword": "sprint", "size": 20, "cursor": "eyJvZmZzZXQ6MjB9" } ``` ## 並び順 結果は一致位置で並べ替えられ、次にフォルダ名の長さで並べ替えられます（同じ一致位置では短い名前が上位）。 1. **一致位置の昇順** — `name` がキーワードで**始まる**フォルダは、名前の**後方**にキーワードを含むフォルダより上位になります。 * `keyword="general"` → `"General"`（位置 0）は `"0.General"`（位置 2）より上位。 2. **名前の長さの昇順** — 一致位置が同じ場合は、短い名前が上位になります。 * どちらも位置 0 で始まり "gen" に一致する場合: `"General"`（7 文字）は `"General Announcements"`（21 文字）より上位。 これにより、最も具体的に一致するものが先頭に表示されます。 ## ベストプラクティス `search_private_folders` は個人の（共有されていない）フォルダを検索し、`search_team_folders` はチーム（ワークスペースで共有された）フォルダを検索します。どちらも `mcp:folders:read` スコープを持つ任意の API key を受け付けます。ツールはフォルダの種類で選んでください。一致するフォルダがない場合、結果は空のリストになります（エラーではありません）。 どちらのツールもデフォルトでは API key のワークスペースを対象とします。アクセスできる別のワークスペースのフォルダを検索するには、`list_workspaces` から取得した `workspaceGuid` を渡してください。 韓国語・日本語・中国語のテキストはサーバー側で自動的に NFC 正規化されます。キーワードを前処理する必要はありません。生のテキストをそのまま渡せば、一致エンジンが処理します。 例: `keyword="네이버"` は、同じテキストの合成形・分解形いずれのフォルダにも一致します。 必ず前回のレスポンスで返された `nextCursor` を使用してください。オフセットを自分で計算しないでください。ページネーションの動作は将来のリリースで変更される可能性があります。 フィルタリングせずにフォルダの完全なリストを取得するには、`keyword` を省略するか空文字列を渡してください。`size` と `nextCursor` を使って結果セット全体をページネーションします。 ## よくあるエラー ### スコープが不足 ```json theme={"system"} { "error": "FORBIDDEN", "message": "Insufficient scope: mcp:folders:read required", "statusCode": 403 } ``` **解決方法:** お使いの API key に `mcp:folders:read` スコープがありません。正しいスコープで新しいキーを生成するか、ワークスペース管理者にアクセス権の付与を依頼してください。 ## トークン使用量 | Operation | Tokens | | -------------------- | --------- | | 空のキーワード（すべてのフォルダを列挙） | \~200–500 | | キーワード検索 | \~200–500 | フォルダ検索は軽量です。結果には名前とパスのみが含まれ、コンテンツは含まれません。 ## スコープ要件 `search_private_folders` と `search_team_folders` はどちらも `mcp:folders:read` スコープを必要とします。API key は [Tiro Platform API Keys](https://platform.tiro.ooo/dashboard/api-keys) で構成してください。 **注記:** `mcp:folders:write` スコープは（2026-05-06 時点で）もう存在しません。すべてのフォルダ書き込み操作は削除されました。`mcp:folders:write` を持つ古い API key をお持ちの場合、そのスコープは無視され、使用されません。 ## 関連ツール * **[`list_notes`](./list-notes)** — `filter.folderId` を使って特定のフォルダ内のノートを見つけます（別途「フォルダ一覧」ツールは不要です）。 * **[`search_notes`](./search-notes)** — `filter.folderId` を使ってフォルダ内のノートを検索します（キーワード必須の深い検索）。