> ## Documentation Index > Fetch the complete documentation index at: https://linkly.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Linkly AI MCP ツールの紹介 > Linkly AI が AI アシスタントに提供するツールの紹介 ## ツール概要 Linkly AI は MCP（Model Context Protocol）を通じて AI アシスタントに 7 つのツールを公開し、段階的なドキュメントアクセスワークフローを構成します： ``` search → grep or outline → read ``` さらに 3 つのユーティリティツールが利用可能です：`list_libraries`（ナレッジライブラリの一覧表示）、`explore`（ドキュメントコレクションの概要表示）、`find_paths`（キーワードでフォルダパスを特定し、`search` の `path_glob` に渡す）。 ドキュメントを検索し、関連する結果を取得 ドキュメントのアウトラインを表示し、構造を把握 正規表現で特定のテキストパターンを検索 ドキュメントの内容を読み取り、詳細情報を取得 ナレッジライブラリとそのドキュメント数を一覧表示 ドキュメントコレクションのテーマと構造の概要を表示 キーワードでフォルダパスを特定し、`search` の `path_glob` に渡す これら 7 つのツールを組み合わせることで、AI アシスタントがローカルドキュメントからコンテキスト情報を効率的に取得できます。 ## 検索（search） インデックス済みのローカルドキュメントを検索し、最も関連性の高い結果リストを返します。 ### パラメータ | パラメータ | 型 | 必須 | デフォルト値 | 説明 | | ----------------- | --------- | --- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `query` | string | はい | — | 検索キーワードまたはフレーズ | | `limit` | number | いいえ | 20 | 最大返却結果数（1-50） | | `doc_types` | string\[] | いいえ | 全部 | ドキュメントタイプでフィルター、例：`["pdf", "md", "docx", "pptx", "epub"]` | | `library` | string | いいえ | — | 特定のライブラリに限定します。ローカルは名前または `local://`、クラウドは `cloud:///`（`--remote` のみ）。`list_libraries` で利用可能なライブラリを確認できます | | `path_glob` | string | いいえ | — | ファイルパスでフィルターします。パターンはパスに対して**部分一致**します——任意の位置にマッチし、前後に `*` を付ける必要はありません。`*` は任意の文字列（`/` を含む）、`?` は単一文字にマッチ。常に大文字小文字を区別。完全なディレクトリパス（`/Users/me/notes/`）を渡すとそのディレクトリ内に限定できます。実際のパスが不明な場合は、先に `find_paths` を呼び出してください | | `modified_after` | string | いいえ | — | 更新日時の下限（含む）。ISO 8601 UTC 形式：日付のみ `2024-01-01`（`00:00:00Z` として扱われる）または完全な RFC 3339 `2024-01-01T00:00:00Z` | | `modified_before` | string | いいえ | — | 更新日時の上限（含む）。形式は `modified_after` と同じ | | `time_sort` | string | いいえ | `default` | 時間順での並べ替え：`default`（関連度順を保持）/ `newest`（新しい順）/ `oldest`（古い順）。候補集合が選定・重複排除された後にのみ並べ替えを適用 | | `output_format` | string | いいえ | `markdown` | `json` に設定すると構造化 JSON 出力を取得 | ベクトルモデルのダウンロード中でも、検索は自動的にキーワードのみモードにフォールバックし、利用に影響はありません。 **時間フィルターと並べ替えについて：** * ユーザーが明確な期間を指定する場合（「先月」「2024 年中」「直近 3 ヶ月」）は、`modified_after` / `modified_before` を使います。 * ユーザーが「最近」「最新」「最古」のように具体的な期間を指定しない場合は、`time_sort=newest` または `oldest` を使います。 * 両者は組み合わせ可能：「2024 年で最も古いもの」は `modified_after=2024-01-01` + `modified_before=2024-12-31` + `time_sort=oldest` です。 * 「先月」のような相対日付を計算するには、まず任意のツール応答末尾の `[meta] now=...` フィールドから現在の UTC 時刻を読み取り、そこから日付を算出してください。詳しくは下記の [レスポンスメタデータ](#レスポンスメタデータ) を参照。 ### 返却フィールド 各検索結果には以下の情報が含まれます： | フィールド | 説明 | | ------------- | ------------------------------------- | | `doc_id` | ドキュメントの一意識別子。後続の outline/read 呼び出しに使用 | | `title` | ドキュメントタイトル | | `path` | ファイルパス | | `relevance` | 関連度スコア（0-1） | | `word_count` | ドキュメントの語数 | | `total_lines` | ドキュメントの総行数 | | `has_outline` | 利用可能なアウトラインがあるか | | `modified_at` | 最終更新日時 | | `keywords` | 抽出されたキーワードリスト | | `snippet` | マッチした内容のスニペット | ### 使用例 ```bash theme={null} # CLI 方式 linkly search "project management best practices" --limit 10 # ドキュメントタイプでフィルター linkly search "quarterly report" --type pdf,docx --json # 特定のライブラリ内で検索 linkly search "deep learning" --library my-research --limit 10 # ファイルパスでフィルター linkly search "report" --path-glob "*2024*" # 期間でフィルター（2024 年 Q3 の四半期報告書） linkly search "quarterly report" --modified-after 2024-07-01 --modified-before 2024-09-30 # 時間順で並べ替え（「最新」「最古」など期間が定まらない場合） linkly search "weekly retro" --time-sort newest --limit 5 ``` ## アウトライン（outline） 1 つまたは複数のドキュメントの構造化されたアウトラインとメタデータを取得し、ドキュメント構造の迅速な把握と対象セクションの特定に役立ちます。 ### パラメータ | パラメータ | 型 | 必須 | デフォルト値 | 説明 | | --------------- | --------- | --- | ---------- | --------------------------------------------- | | `doc_ids` | string\[] | はい | — | ドキュメント ID リスト（検索結果から取得） | | `expand` | string\[] | いいえ | 自動 | 展開するノード ID（例：`["2", "3.1"]`）、省略するとすべての階層を自動表示 | | `output_format` | string | いいえ | `markdown` | `json` に設定すると構造化 JSON 出力を取得 | ### アウトラインを使うべきタイミング | シナリオ | 推奨 | | ---------------------------- | ----------------------------------- | | 50 行超のドキュメントでアウトラインあり | まずアウトラインを確認し、対象セクションを読み取る | | 短いドキュメント（50 行未満） | アウトラインをスキップし、`read` で全文を直接読む | | `has_outline: false` のドキュメント | `grep` でパターンを検索するか、`read` でページごとに閲覧 | アウトライン機能は**ブックマーク付きの PDF**、**Markdown**、**DOCX**、**PowerPoint (PPTX)**、**EPUB** のドキュメントで最も効果的です。長いドキュメントや書籍を読む際に特に有効です。 プレーンテキストやブックマークのない PDF へのアウトラインサポートは、今後のイテレーションで追加予定です。 ### 使用例 ```bash theme={null} # 単一のドキュメントのアウトラインを表示 linkly outline abc123 # 複数のドキュメントを一括表示 linkly outline id1 id2 id3 # JSON 形式で出力 linkly outline abc123 --json ``` ## Grep 単一のドキュメント内で正規表現パターンにより特定の行を検索します。アウトラインが利用できない `has_outline=false` のドキュメントに最適です。`search` の後に使用して、名前、日付、用語、識別子、その他のパターンの正確な位置を特定し、`read` で offset を指定して前後の文脈を確認します。すべてのドキュメントタイプ（PDF、Markdown、DOCX、PPTX、EPUB、TXT、HTML）で動作します。複数のドキュメントを検索する場合は、ドキュメントごとに grep を 1 回呼び出してください。 ### パラメータ | パラメータ | 型 | 必須 | デフォルト値 | 説明 | | ------------------ | ------- | --- | ---------- | ------------------------------------------------------ | | `pattern` | string | はい | — | 検索する正規表現パターン | | `doc_id` | string | はい | — | 検索対象のドキュメント ID（検索結果から取得） | | `context` | number | いいえ | 3 | 各マッチの前後に表示するコンテキスト行数 | | `before` | number | いいえ | — | 各マッチの前に表示するコンテキスト行数（`context` を上書き） | | `after` | number | いいえ | — | 各マッチの後に表示するコンテキスト行数（`context` を上書き） | | `case_insensitive` | boolean | いいえ | false | 大文字小文字を区別しないマッチング | | `output_mode` | string | いいえ | `content` | `content`（コンテキスト付きマッチ行）または `count`（マッチ数のみ、先に合計を確認する場合） | | `limit` | number | いいえ | 20 | 返却するマッチ行の最大数（最大 100） | | `offset` | number | いいえ | 0 | ページネーション用にスキップするマッチ数 | | `output_format` | string | いいえ | `markdown` | `json` に設定すると構造化 JSON 出力を取得 | ### Grep とアウトラインの使い分け | シナリオ | 推奨 | | ------------------------------------- | -------------------- | | 特定の用語、名前、日付を検索したい | パターンを指定して `grep` を使用 | | ドキュメント全体の構造を把握したい | `outline` を使用 | | アウトラインがないドキュメント（`has_outline: false`） | `grep` でコンテンツを検索 | | パターンの検索（メール、ID、数値など） | 正規表現で `grep` を使用 | ### 使用例 ```bash theme={null} # ドキュメント内で特定の用語を検索 linkly grep "quarterly revenue" 456 # 大文字小文字を区別しない検索（コンテキスト付き） linkly grep "error|warning" 1044 -C 3 -i # 読み取り前にマッチ数を確認 linkly grep "TODO" 591 --mode count ``` ## 読み取り（read） ドキュメントの内容を行番号での位置指定とページネーションで読み取ります。長いドキュメントの特定部分の読み取りに適しています。Read ツールは Claude AI SDK と一貫した動作をするため、各種 Agentic AI モデルで最適な結果が得られます。 ### パラメータ | パラメータ | 型 | 必須 | デフォルト値 | 説明 | | --------------- | ------ | --- | ---------- | --------------------------- | | `doc_id` | string | はい | — | ドキュメント ID（検索結果から取得） | | `offset` | number | いいえ | 1 | 開始行番号（1 から開始） | | `limit` | number | いいえ | 200 | 読み取り行数（最大 500） | | `output_format` | string | いいえ | `markdown` | `json` に設定すると構造化 JSON 出力を取得 | ### コンテンツ形式 `Read` ツールは行番号付きの内容を返し、参照と位置特定が容易です： ``` 1 # Project Requirements Document 2 3 ## 1. Project Background 4 5 This project aims to build an efficient knowledge management system... 6 Target users are enterprise R&D teams and individual knowledge workers. ``` ### ページネーション戦略 長いドキュメントの場合、分割して読み取ることをお勧めします： ```bash theme={null} # 第 1 ページ：第 1-200 行 linkly read --offset 1 --limit 200 # 第 2 ページ：第 201-400 行 linkly read --offset 201 --limit 200 # 第 3 ページ：第 401-600 行 linkly read --offset 401 --limit 200 ``` アウトラインとの併用がより効果的です。アウトラインで対象セクションの行範囲を特定し、`read` でその範囲の内容を正確に読み取れます。 ### 使用例 ```bash theme={null} # ドキュメントの冒頭を読み取り linkly read abc123 # 特定の範囲を読み取り linkly read abc123 --offset 120 --limit 80 # JSON 形式（プログラム処理に適しています） linkly read abc123 --json ``` ## ライブラリ一覧（list\_libraries） ユーザーが設定したすべてのナレッジライブラリを、説明とドキュメント数とともに一覧表示します。 ### パラメータ パラメータは不要です。 ### ユースケース * ユーザーが「どんなライブラリがありますか？」と質問した場合 * `search` の `library` パラメータを使用する前に、ライブラリ名を確認する場合 ```bash theme={null} linkly list-libraries ``` ## 探索（explore） インデックス済みの全ドキュメントまたは特定のライブラリの鳥瞰的な概要を取得します。ドキュメントタイプの分布、ディレクトリ構造（ファイル数と語数の中央値付き）、上位キーワード（出典の帰属付き）を返します。 ### パラメータ | パラメータ | 型 | 必須 | デフォルト値 | 説明 | | --------- | ------ | --- | ------ | ---------------------------------------------------------------------------------------------------------------- | | `library` | string | いいえ | — | 特定のライブラリに限定します。ローカルは名前または `local://`、クラウドは `cloud:///`（`--remote` のみ）。省略するとすべてのローカルドキュメントを探索します | ### ユースケース * ユーザーがナレッジベースやドキュメントコレクションの内容を知りたい場合 * ユーザーに特定の検索トピックがなく、利用可能なテーマや方向性を発見したい場合 * AI アシスタントが効果的な検索戦略を策定するために、規模とトピック分布を把握する必要がある場合 探索後は、出力のキーワードやディレクトリ名を手がかりとして、後続の `search` クエリに活用します。 ```bash theme={null} # すべてのドキュメントを探索 linkly explore # 特定のライブラリを探索 linkly explore --library my-research ``` ## パス特定（find\_paths） インデックス済みドキュメントの**ファイルパス**フィールドに対してキーワードで曖昧マッチングを行い、フォルダ単位で集約して上位の候補ディレクトリを返します。`search` の補助ツールとして位置づけられており、ユーザーがコンテナを名前で示しているのに（「Notion ノートの中で」「Dropbox の論文フォルダで」）その実際のディスク上のパスがわからないとき、まず `find_paths` で実際のパスを探し、それを `search` の `path_glob` パラメータに渡します。 ディスク上の実際のフォルダ名は、ユーザーの口語表現と一致しないことが多く（例：エクスポートが `Notion-Export-c58e430f...` のような名前で保存される）、`path_glob` を直接推測するのは脆弱です。 ### パラメータ | パラメータ | 型 | 必須 | デフォルト値 | 説明 | | --------------- | --------- | --- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `patterns` | string\[] | はい | — | キーワード配列。各要素は内部で SQL `LIKE %keyword%` としてパスに対してマッチング。複数のキーワードは OR 関係のため、**1 回の呼び出しで複数のバリエーションを渡す**ことを推奨（翻訳ペア、大文字小文字、既知のアプリ/SDK 識別子など）。例：`["Notion", "notion", "notion-export"]`。ASCII は大文字小文字を区別しない、CJK は字面一致 | | `library` | string | いいえ | — | 特定のライブラリに限定します。ローカルは名前または `local://`、クラウドは `cloud:///`（`--remote` のみ）。`list_libraries` で利用可能なライブラリを確認できます | | `limit` | number | いいえ | 10 | 候補ディレクトリの最大数（最大 50） | | `output_format` | string | いいえ | `markdown` | `json` に設定すると構造化 JSON 出力を取得 | ### 返却フィールド（JSON モード） | フィールド | 説明 | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `total_files` | 返却された候補に集約されたファイル総数（`limit` による切り捨て前） | | `truncated` | `limit` によりディレクトリリストが切り詰められたか（`true` の場合、まだ候補が存在） | | `directories` | 候補ディレクトリの配列。`file_count` の降順で並ぶ。各エントリは `path`（完全な絶対パス）、`path_glob`（`path` を `search` の `path_glob` にそのまま渡せるパターンへ変換したもの：ディレクトリ名に含まれる glob メタ文字 `* ? [` がエスケープされ、そのディレクトリに字面一致する——メタ文字がない場合は `path` と同じ。後続の `search` にそのままコピーすればディレクトリ全体に限定できる）、`file_count`（マッチ数）を持つ | ### 集約の挙動 * パターンが**ファイル名セグメント**にしかマッチしないファイル（ディレクトリセグメントにマッチがない）は静かに破棄されます。これは「フォルダを探す」ツールであり、「ファイルを探す」ツールではないためです。マッチするファイルがあるはずなのに候補ディレクトリが 0 件返る場合は、`search` を直接呼び出すフォールバックを検討してください。 * 各マッチは、パス内で**最も浅い**位置にあるパターン出現を基準に、次の `/` で切り詰められて集約されます。例：`local:///Users/me/Documents/Notion-Export-abc/workspace/page.md` がキーワード `Notion` でヒットすると、ファイルがどれだけ深くても `.../Documents/Notion-Export-abc` に集約されます。 ### 使用すべきとき * ユーザーが曖昧または異言語の語でコンテナを表現しており（「Notion ノートの中で」「Dropbox の論文フォルダで」「ワークバックアップで」）、実際のパスがわからないとき * `search` を呼び出す前に、`path_glob` の値を決定するため ### 使用すべきでないとき * 内容/トピックそのものを探すクエリ（「履歴書を探す」「AI 論文を探す」）—— 直接 `search` を呼ぶ。混合検索はすでにタイトル/ファイル名/本文/パスをカバー * ファイルタイプのみでフィルター（「すべての PDF」）—— `search` に `path_glob="*.pdf"` を直接渡す * コンテナ意図のない漠然としたクエリ（「最近のもの」）—— `search` を直接 ### 使用例 ```bash theme={null} # ユーザー：「Notion ノートの中の購入レシートを探して」 # Step 1：実際のパスを特定 linkly find-paths --patterns Notion,notion --limit 5 # 例：.../Documents/Notion-Export-abc/workspace（1240 ファイル）が返る # Step 2：そのコンテナ内で内容検索 linkly search "shopping receipt" --path-glob "*Notion-Export*" ``` ## レスポンスメタデータ 成功した各ツール応答には現在の UTC 時刻が付加され、呼び出し側がモデルの学習データのカットオフに依存せずに「先月」「今年」「過去 30 日間」などの相対日付を計算できるようになっています。 * **Markdown 出力**：応答末尾に区切りブロックが追加されます： ``` --- [meta] now=2026-05-08T14:43:14Z ``` * **JSON 出力**：トップレベルに `_meta` オブジェクトが追加されます： ```json theme={null} { ..., "_meta": { "now": "2026-05-08T14:43:14Z" } } ``` エラー応答（`isError: true`）には**メタデータが付加されません** —— エラー本体がすでに失敗の原因を伝えており、タイムスタンプを付加するとシグナルが希薄になるためです。 ユーザーが相対日付を使う場合は、最新のツール応答から `now` を読み取り、対応する ISO 8601 日付を計算してから `search` の `modified_after` / `modified_before` に渡します。 ## ワークフロー例 ### 完全なワークフロー：CLI 方式 以下の例は、CLI を使って完全なドキュメント検索を行う方法を示しています： ```bash theme={null} # ステップ 1：関連ドキュメントを検索 linkly search "microservice architecture design" --limit 5 # ステップ 2：対象ドキュメントのアウトラインを表示（doc_id が abc123 の場合） linkly outline abc123 # ステップ 3：関心のあるセクションを読み取り（対象が第 80-150 行の場合） linkly read abc123 --offset 80 --limit 70 ``` ### 完全なワークフロー：MCP 方式 AI アシスタントが MCP プロトコルでツールを呼び出す場合、リクエスト形式は以下の通りです： ```json theme={null} // ステップ 1：検索 { "method": "tools/call", "params": { "name": "search", "arguments": { "query": "microservice architecture design", "limit": 5 } } } // ステップ 2：アウトラインを表示 { "method": "tools/call", "params": { "name": "outline", "arguments": { "doc_ids": ["abc123"] } } } // ステップ 3：内容を読み取り { "method": "tools/call", "params": { "name": "read", "arguments": { "doc_id": "abc123", "offset": 80, "limit": 70 } } } ``` ## よくある質問 Linkly AI は現在、以下の形式に対応しています： | 形式 | 拡張子 | アウトライン対応 | | -------- | ---------------------------------------- | -------- | | Markdown | `.md`, `.mdx` | Yes | | Word | `.docx` | Yes | | EPUB | `.epub` | Yes | | PDF | `.pdf` | Partial | | プレーンテキスト | `.txt` | No | | HTML | `.html`, `.htm` | Partial | | 画像（OCR） | `.png`, `.jpg`, `.jpeg`, `.bmp`, `.webp` | No | ドキュメントに利用可能なアウトラインがない場合（`has_outline: false`）、以下の方法があります： 1. `read` ツールを直接使用して、ドキュメントの内容をページごとに閲覧します 2. まずドキュメントの冒頭（デフォルト 200 行）を読み取り、大まかな内容を把握してから続きを読むか判断します 推奨フロー： 1. まず `outline` でドキュメントの構造を把握します（アウトラインがある場合） 2. アウトライン内の行範囲に基づいて、`read` の `offset` と `limit` パラメータで対象セクションを正確に読み取ります 3. 1 回の読み取りは最大 500 行です。`offset` を調整してページごとに読み取ります デフォルトポートは **60606** です。このポートが使用中の場合、アプリは自動的に他のポートを試行します。Linkly AI Desktop の設定で実際に使用されているポートを確認できます。 以下をお試しください： * より正確なキーワードを使用する * 自然言語での記述を使用する（ベクトルセマンティックマッチングを活用） * キーワードと同義語を組み合わせる（例：`"authentication auth login sign-in"`） * `--type` で特定のドキュメントタイプをフィルターし、検索範囲を絞り込む