Skip to main content

ツール概要

Linkly AI は MCP(Model Context Protocol)を通じて AI アシスタントに9 つのツールを公開しています。クラウドゲートウェイ(mcp.linkly.ai、および linkly mcp --remote)ではさらにクラウド専用の 2 つのツール——library_search と library_link——が加わり、合計 11 個になります。中心にあるのは、段階的なドキュメントアクセスワークフローです:
その周りに、3 つの発見系ユーティリティツール——list_libraries(ナレッジライブラリの一覧表示)、explore(ドキュメントコレクションの概要表示)、find_paths(キーワードでフォルダパスを特定し、search の path_glob に渡す)——に加えて、list(コンテナの列挙:フォルダ内のファイル、ライブラリ、またはノート)と、唯一のノート書き込みツール note_save(ノートの作成 / 編集)があります。

search

ドキュメントを検索し、関連する結果を取得

outline

ドキュメントのアウトラインを表示し、構造を把握

grep

正規表現で特定のテキストパターンを検索

read

ドキュメントの内容を読み取り、詳細情報を取得

list_libraries

ナレッジライブラリとそのドキュメント数を一覧表示

explore

ドキュメントコレクションのテーマと構造の概要を表示

find_paths

キーワードでフォルダパスを特定し、search の path_glob に渡す

list

コンテナ内の項目を列挙する——フォルダ、ライブラリ、またはノート

note_save

ノートを作成・編集する。書き込みあり(ローカル接続では唯一の書き込みツール)

library_search

まだリンクしていないものも含めて、クラウドライブラリのカタログを検索する——クラウドゲートウェイ専用

library_link

クラウドライブラリをリンクして検索可能にする、または指定したライブラリのリンクを解除する(action: "unlink")——クラウドゲートウェイ専用、書き込みあり
library_search と library_link はクラウドゲートウェイにしか存在しません。そこで書き込みを行うのは library_link で、クラウドライブラリをアカウントのリンク済み集合に追加するか、action: "unlink" であなたが指定した 1 件を外します。以下のその他のツールはすべて読み取り専用です。
note_save(およびクラウドゲートウェイ上の library_link)を除くすべてが読み取り専用です——ドキュメントを読むだけで、内容を書き換えることはありません。note_save はノートのディレクトリにしか書き込めず、しかも削除ツールは存在しません。ノートの削除はアプリ上でご自身が行う必要があります。

検索(search)

インデックス済みのローカルドキュメントを検索し、最も関連性の高い結果リストを返します。

パラメータ

ベクトルモデルのダウンロード中でも、検索は自動的にキーワードのみモードにフォールバックし、利用に影響はありません。
時間フィルターと並べ替えについて:
  • ユーザーが明確な期間を指定する場合(「先月」「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 時刻を読み取り、そこから日付を算出してください。詳しくは下記の レスポンスメタデータ を参照。

返却フィールド

各検索結果には以下の情報が含まれます:
word_count は文字数ではありません。char_count との差は内容(句読点・空白・Markdown の割合)によって変わります。char_count はこれまでに抽出できた本文を数えたもので、OCR や文字起こしが完了していない場合や抽出が途中で打ち切られた場合は、文書の一部しか表しません。改行・結合文字・絵文字の数え方はエディターによって異なるため、エディターの文字数と比べるときは、同じテキストを同じ基準で数えているかを確かめてから、内容の欠落かどうかを判断してください。char_count には Linkly AI Desktop v0.14.1 以降が必要です。それより前のバージョンでインデックスされたドキュメントは、再抽出またはインデックスの再構築までは null を返します(read は常にその場で計算します)。クラウドライブラリのドキュメントはまだこのフィールドを返しません。

使用例

アウトライン(outline)

1 つまたは複数のドキュメントの構造化されたアウトラインとメタデータを取得し、ドキュメント構造の迅速な把握と対象セクションの特定に役立ちます。

パラメータ

アウトラインを使うべきタイミング

アウトライン機能はブックマーク付きの PDF、Markdown、DOCX、DOC、PowerPoint (PPTX)、XLSX、CSV、EPUB、RTF のドキュメントで最も効果的です。長いドキュメントや書籍を読む際に特に有効です。表形式のファイルでは、見出しではなく表がアウトラインになります:XLSX はワークシートごとに 1 エントリ(行数・列数、ヘッダー行、数行のプレビュー付き)、CSV はテーブル全体の要約が 1 エントリです。 プレーンテキストやブックマークのない PDF へのアウトラインサポートは、今後のイテレーションで追加予定です。

使用例

Grep

単一のドキュメント内で正規表現パターンにより特定の行を検索します。アウトラインが利用できない has_outline=false のドキュメントに最適です。search の後に使用して、名前、日付、用語、識別子、その他のパターンの正確な位置を特定し、read で offset を指定して前後の文脈を確認します。すべてのドキュメントタイプ(PDF、Markdown、DOCX、DOC、PPTX、XLSX、CSV、EPUB、RTF、TXT、HTML)で動作します。複数のドキュメントを検索する場合は、ドキュメントごとに grep を 1 回呼び出してください。

パラメータ

Grep とアウトラインの使い分け

使用例

読み取り(read)

ドキュメントの内容を行番号での位置指定とページネーションで読み取ります。長いドキュメントの特定部分の読み取りに適しています。Read ツールは Claude AI SDK と一貫した動作をするため、各種 Agentic AI モデルで最適な結果が得られます。

パラメータ

画像とテキストが混在するドキュメントを読む

多くのドキュメント(とくに Markdown のノートや技術文書)では、肝心な情報が図の中にあります。read は、いま読んでいる行範囲の中に現れた画像参照を、対応するインデックス済みの画像ドキュメントとして解決し、結果の末尾に添えます。どこまで添えるかは image_text で決めます: full には予算の上限があります:画像 1 枚につき最大 2000 文字、1 回の呼び出し全体で 20000 文字まで。予算を超えた画像は自動的に abstract へ格下げされ、その画像を単独で読むための案内が示されます。
まずデフォルトの abstract でどの画像が役に立つかを見極め、そのうえで該当する 1 枚だけを doc_id 指定で read する方が、最初から full を使うよりずっと節約になります。

コンテンツ形式

Read ツールは行番号付きの内容を返し、参照と位置特定が容易です:

ページネーション戦略

長いドキュメントの場合、分割して読み取ることをお勧めします:
アウトラインとの併用がより効果的です。アウトラインで対象セクションの行範囲を特定し、read でその範囲の内容を正確に読み取れます。

使用例

ライブラリ一覧(list_libraries)

ユーザーが設定したすべてのナレッジライブラリを、説明とドキュメント数とともに一覧表示します。

パラメータ

パラメータは不要です。

ユースケース

  • ユーザーが「どんなライブラリがありますか?」と質問した場合
  • search の library パラメータを使用する前に、ライブラリ名を確認する場合

ライブラリ検索(library_search)

クラウドゲートウェイ専用——linkly-ai-cloud MCP サーバーと linkly mcp --remote で利用できます。ローカル / LAN 接続にはこのツールはありません。
タイトル、説明、所有者のユーザー名でクラウドナレッジライブラリのカタログを検索します。まだリンクしていないライブラリも対象です。見つけるのはライブラリで、ドキュメントを検索するには search を、すでに検索できるものを見るには list_libraries を使ってください。

パラメータ

レスポンス

各エントリには他のツールにそのまま渡せる cloud://<owner>/<slug> に加え、タイトル、説明、所有者、カテゴリ、可視性、ドキュメント / スター / リンク数、is_owner、is_linked(すでに検索可能——再度リンクする必要なし)、can_link(招待されていない Showcase ライブラリでは cannot_link_reason: invite_required)が含まれます。Public と Showcase のライブラリは常に表示され、Private ライブラリは所有者と招待済みの読者にしか表示されません。結果は最終更新日時の新しい順です。このツールはリンク・スター・変更を一切行いません。

利用シーン

  • 「Rust に関するナレッジベースを探して使いたい」→ library_search(query="Rust") → 結果を 1 つ選ぶ → library_link → search(query=…, library="cloud://…")
  • 「自分が所有するクラウドライブラリは?」→ library_search(owner="<自分のユーザー名>")

ライブラリのリンク(library_link)

クラウドゲートウェイ専用。書き込みを行う 2 つのツールの 1 つです(もう 1 つは note_save)。同じツールが action: "unlink" でリンクを解除します——下記参照。
クラウドライブラリをアカウントにリンクし、MCP 経由で検索できるようにします。リンク直後から list_libraries に表示され、search / explore / list はその cloud://<owner>/<slug> をすぐに受け付けます。ルールはウェブサイトの「リンク」ボタンと同じです。

パラメータ

ルール

  • Public ライブラリ:サインインしていれば誰でもリンクできます。Showcase と Private ライブラリ:所有者と招待済みの読者のみ(ツールは invite_required を返し、見えない非公開ライブラリには「not found」を返します)。
  • 同じライブラリを二度リンクしても無害です——already_linked を返し、Slot を追加で消費しません。
  • リンク 1 件につき Slot を 1 つ使います(Free:1、Pro:99)。上限に達するとツールは slot_exhausted を返し、現在の件数・上限・アップグレード用リンクを添えます。AI アシスタントが解除するライブラリを勝手に選ぶことはありません。リンク済みのライブラリを一覧にしてどれを外すか尋ね、action: "unlink" で library_link を呼んでから改めてリンクします。ウェブサイトで空きを作ることもできます。

リンク解除(action: "unlink")

クラウドライブラリをアカウントのリンク済み集合から外します:list_libraries から消え、MCP 経由で検索できなくなり(あなたのアカウントのすべてのクライアントで)、その Slot が空きます。それ以外は何も変わりません——閲覧権限、招待、スターはそのまま残るので、後で再びリンクできます。library パラメータは上と同じで、list_libraries の表示と同一のものを渡します。
  • AI アシスタントはあなたが指定したライブラリだけを解除します——典型例は Slot が上限のときの「A を B に置き換えて」です。指定がなければ、リンク済みのライブラリを一覧にして尋ね、自分で選ぶことはありません。
  • リンクされていないライブラリを解除しても無害です——already_unlinked を返します。not_found は、そのライブラリがあなたのアカウントから見えないことを意味します。
  • レスポンスには使用中の Slot 数が示されるので、アシスタントはその直後に本来リンクしたかったライブラリをリンクできます。

探索(explore)

インデックス済みの全ドキュメントまたは特定のライブラリの鳥瞰的な概要を取得します。ドキュメントタイプの分布、ディレクトリ構造(ファイル数と語数の中央値付き)、上位キーワード(出典の帰属付き)を返します。

パラメータ

ユースケース

  • ユーザーがナレッジベースやドキュメントコレクションの内容を知りたい場合
  • ユーザーに特定の検索トピックがなく、利用可能なテーマや方向性を発見したい場合
  • AI アシスタントが効果的な検索戦略を策定するために、規模とトピック分布を把握する必要がある場合
探索後は、出力のキーワードやディレクトリ名を手がかりとして、後続の search クエリに活用します。

パス特定(find_paths)

インデックス済みドキュメントのファイルパスフィールドに対してキーワードで曖昧マッチングを行い、フォルダ単位で集約して上位の候補ディレクトリを返します。search の補助ツールとして位置づけられており、ユーザーがコンテナを名前で示しているのに(「Notion ノートの中で」「Dropbox の論文フォルダで」)その実際のディスク上のパスがわからないとき、まず find_paths で実際のパスを探し、それを search の path_glob パラメータに渡します。 ディスク上の実際のフォルダ名は、ユーザーの口語表現と一致しないことが多く(例:エクスポートが Notion-Export-c58e430f... のような名前で保存される)、path_glob を直接推測するのは脆弱です。

パラメータ

返却フィールド(JSON モード)

集約の挙動

  • パターンがファイル名セグメントにしかマッチしないファイル(ディレクトリセグメントにマッチがない)は静かに破棄されます。これは「フォルダを探す」ツールであり、「ファイルを探す」ツールではないためです。マッチするファイルがあるはずなのに候補ディレクトリが 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 を直接

使用例

列挙(list)

あるコンテナ内の項目を列挙します。全文マッチングは行いません——キーワードや意味で内容を探したい場合は search を使ってください。3 種類のコンテナに対応しています:folder(ディスク上のディレクトリ配下のインデックス済みファイル)、library(1 つのライブラリのファイル)、notes(ローカルのカード型ノート)。 ツールの役割分担:explore = 全体の概観 → find_paths = ディレクトリを見つける → list = 既知のコンテナ内のファイルを列挙する → outline / read = 内容を読む。列挙はサブツリー全体をフラットに再帰走査します——ディレクトリツリーは返しません。掘り下げるには項目内の絶対パスをたどるか、find_paths を使ってください。

パラメータ

返却フィールド

folder / library の項目には次が含まれます:doc_id、title、絶対 path、doc_type、word_count、char_count、total_lines、has_outline、modified_at(Unix ミリ秒、ファイルシステムの mtime)、keywords、snippet(抜粋が無効のときは null)、そして skip_reason——skip_reason が非 null の場合、その内容は読み取れないため read / grep しないでください。outline と read のどちらを使うかは total_lines + has_outline で判断します。ローカル scope の total はフィルター後の全集合の件数です。クラウドライブラリでは総数が不明な場合に total: null が返ることがあります——いずれの場合も offset + has_more でページ送りしてください。 notes の項目には次が含まれます:doc_id(read / grep / outline にそのまま渡せます)、note_id と最新の version(この 2 つは note_save で編集する際の楽観ロックの資格情報です)、title、絶対パス、created_at / modified_at(Unix ミリ秒)、tags、出典情報、そしてデフォルトで付く snippet。レスポンスにはさらに available_tags が含まれます——現在のすべてのノートのタグのうち、使用頻度が高い上位 50 件で、そのまま次回の tags フィルターに使えます。
README ポインタ:path を明示的に渡し(scope が folder またはローカル library)、かつ README 系のファイルがそのディレクトリの直下にある(サブディレクトリではない)場合にのみ、レスポンスにトップレベルの readme ポインタが付きます。クラウドライブラリでは返りません。それが存在し、かつフォルダの目的を理解する必要があるときは、まずそのドキュメントを読んでください。
ファイルシステム優先(notes):書いたばかりのノートはすぐ一覧に現れますが、その時点では doc_id は null、indexed は false です(文字数や行数もまだ空です)。インデックスが終わってから埋まります。つまり「書いたばかりのノートは一覧には出るが検索では出てこない」のは正常な挙動で、失われたわけではありません。title も null になることがあります——ファイル名が機械的に生成されたノートには使えるタイトルがないためです。その場合は抜粋、タグ、日時で見分けてください。

クラウドライブラリ

folder が扱えるのはローカルのディスクパスだけです。クラウドライブラリを列挙するには、scope="library" に library="cloud://<owner>/<slug>" を組み合わせ(--remote で利用可能)、path には相対ディレクトリプレフィックス——まさにクラウドの find_paths が返す形式——を渡します。プレフィックスはそのライブラリの全ソースの和集合に適用されます。「プレフィックスが存在しない」と「ディレクトリが空」は区別できず、最初のページ(offset=0)ではどちらも total: 0 で返ります(path を渡していた場合はヒントも付きます)。 クラウドの列挙はローカルといくつか異なります:sort="name" は非対応;skip_reason は常に null;抜粋は約 120 文字で切り詰め;最初のページ以降は total が null になることがあります——ページ送りは has_more で判断してください。

使用例

ノートの保存(note_save)

ローカルの Markdown カード型ノートを 1 件作成または編集します。これは library_link(クラウドゲートウェイ専用)と並ぶ2 つしかない書き込みツールの 1 つで、書き込めるのはノートのディレクトリだけです。YAML のメタデータはすべてサーバー側で生成されるため、呼び出し側が用意する必要はありません。

パラメータ

押さえておくべき 2 つのルール

この経路が受け付けるのは、アプリのツールバーで実現できる範囲の Markdown だけです:段落と改行、太字、取り消し線、順序付き / 順序なしリスト、プレーンテキスト。見出し、斜体、引用、コード、リンク、表、タスクリスト、画像、生の HTML は拒否され、NOTE_INVALID_INPUT が返ります。アプリの画面でご自身が手で書く場合は、この制限を受けません。本文中(コード部分を除く)の #タグ こそがノートのタグです——タグの唯一の情報源は本文であり、アプリのエディタで手書きする場合とまったく同じです。タグを削除するには対応する #タグ を消します。tags パラメータでできるのは追加だけです。古いバージョンで書かれた、タグが YAML にしか存在しないノートは自動的に修復されます:AI が最初に編集したときに、不足している #タグ が本文へ補われます。
正しい編集の順序は次のとおりです:
  1. list(scope="notes")で note_id と version を取得する
  2. read(doc_id) で現在の完全な本文を読む
  3. note_save に mode="edit"、note_id、base_version=<いま取得した version>、そして修正後の完全な本文を渡す——残したい #タグ はそのまま残し、消したいものは削除します
base_version が古い場合(その間にノートが変更された場合)は NOTE_VERSION_CONFLICT が実際のバージョン番号とともに返ります。読み直し、マージし、再試行してください。そのまま上書きしてはいけません。成功したレスポンスは毎回、ノートの実際の content(サーバーが #タグ を補っている場合があります)と新しい version を返します——以降の編集は必ず返ってきた content を土台にし、自分が送ったほうを使ってはいけません。まだインデックスされていないノートは doc_id が null ですが、作ったばかりのノートを編集できるのも、まさにこの戻り値のおかげです。抜粋だけを頼りにノート全体を書き直すことは絶対に避けてください。
**削除ツールはありません。**ノートの削除は、アプリの画面からユーザーご自身が行う必要があります。

レスポンスメタデータ

成功した各ツール応答には現在の UTC 時刻が付加され、呼び出し側がモデルの学習データのカットオフに依存せずに「先月」「今年」「過去 30 日間」などの相対日付を計算できるようになっています。
  • Markdown 出力:応答末尾に区切りブロックが追加されます:
  • JSON 出力:トップレベルに _meta オブジェクトが追加されます:
エラー応答(isError: true)にはメタデータが付加されません —— エラー本体がすでに失敗の原因を伝えており、タイムスタンプを付加するとシグナルが希薄になるためです。 ユーザーが相対日付を使う場合は、最新のツール応答から now を読み取り、対応する ISO 8601 日付を計算してから search の modified_after / modified_before に渡します。

ワークフロー例

完全なワークフロー:CLI 方式

以下の例は、CLI を使って完全なドキュメント検索を行う方法を示しています:

完全なワークフロー:MCP 方式

AI アシスタントが MCP プロトコルでツールを呼び出す場合、リクエスト形式は以下の通りです:

よくある質問

Linkly AI は現在、以下の形式に対応しています:Excel と CSV のファイルは GitHub 風の Markdown テーブルに変換され、セルのテキスト単位でインデックスされます——そのため search や grep でセルの中の語句にヒットします。アウトラインの形は形式によって異なり、.xlsx はワークシートごとに 1 エントリ(行数・列数、ヘッダー行、数行のプレビュー付き)、.csv はテーブル全体の要約が 1 エントリになります。対応するのは .xlsx と .csv のみで、旧形式の .xls や .xlsm、.xlsb、.ods は対象外です。UTF-8 でない CSV は、ファイル自身または同じディレクトリ内の隣接ファイルからエンコーディングを判定できた場合にのみデコードされます。判定できない場合は、文字化けしたままインデックスするのではなくスキップされます。どちらの形式も 1 ファイル 16 MiB が上限です。音声・動画の文字起こしはデフォルトで無効です——これらのファイルもインデックスには登録されるためファイル名では検索できますが、「中で何が話されているか」を検索するには、先にメインウィンドウの「インデックス管理」ページで、「管理」セクションの「抽出の強化」にある「音声の文字起こし」と「動画の文字起こし」をオンにする必要があります。詳しくはインデックスの設定をご覧ください。
ドキュメントに利用可能なアウトラインがない場合(has_outline: false)、以下の方法があります:
  1. read ツールを直接使用して、ドキュメントの内容をページごとに閲覧します
  2. まずドキュメントの冒頭(デフォルト 200 行)を読み取り、大まかな内容を把握してから続きを読むか判断します
推奨フロー:
  1. まず outline でドキュメントの構造を把握します(アウトラインがある場合)
  2. アウトライン内の行範囲に基づいて、read の offset と limit パラメータで対象セクションを正確に読み取ります
  3. 1 回の読み取りは最大 500 行です。offset を調整してページごとに読み取ります
デフォルトポートは 60606 です。このポートが使用中の場合、アプリは自動的に他のポートを試行します。Linkly AI Desktop のメインウィンドウで「エージェントの利用」ページを開き、「MCP 接続設定を表示」をクリックすると、実際に使用されているアドレスとポートを確認できます。
以下をお試しください:
  • より正確なキーワードを使用する
  • 自然言語での記述を使用する(ベクトルセマンティックマッチングを活用)
  • キーワードと同義語を組み合わせる(例:"authentication auth login sign-in")
  • --type で特定のドキュメントタイプをフィルターし、検索範囲を絞り込む