linkding ブックマーク検索の使い方

基本戦略: 1語ずつ、日英両言語で取得して統合する

linkding 検索に意味的類似度は無い。 複数語は AND で絞られ過ぎるため、概念は単語に分解し、1語ずつ取得して URL の重複排除で統合する。

悪い例: q="OpenCode Zen"          → 両語を含むものだけ (件数激減)
良い例: q="OpenCode" と q="Zen" を別々に取得 → url で重複排除して統合

日本語と英単語は自動で橋渡しされないため、両言語で明示的にクエリする。

例: q="エージェント" と q="agent" を別々に取得 → url で重複排除して統合
例: q="検索" と q="search" を別々に取得 → 同上

大文字小文字の違いは区別されないため、ケース違いの再取得は不要である。

取得件数とページング

• 1回の取得は limit=50 を基本とする (小さく絞って様子見しない)
• 網羅が必要なら limit=100 以上に上げ、count (総件数) を見て offset で継続する
• count が limit を上回る場合は取りこぼしがあるため、必ずページングする
• q 空文字は全件取得 (新しい順) であり、タグ候補の収集にも使える

日付範囲検索

• linkding にあるのは下限のみ (added_since、その日時より後)
• 上限 (added_before) は MCP 側で date_added に適用する (その日時より前、境界を含まない)
• 範囲指定の例 (2026年1月分): added_since='2026-01-01T00:00:00+09:00'、added_before='2026-02-01T00:00:00+09:00'
• 日時は ISO 8601 でタイムゾーン付きで書く (日付のみはタイムゾーン解釈が不定になる)
• 不正な形式は警告なく無視される (下限は linkding 側、上限は MCP 側) ため、件数で裏取りする
• 上限指定時は上限 1000 件の候補から絞り込む (count は絞り込み後の総数、offset/limit は絞り込み後に適用)
• 更新日での絞り込みは未対応 (結果に更新日を含まないため)

構文リファレンス

書き方	意味	例
語1 語2	暗黙 AND (両方含む)	rust async
A or B	和集合 (1回で統合取得)	OpenCode or Zen
not 語	除外	rust not async
(A or B) C	括弧で結合順を指定	(rust or go) async
"..."	隣接フレーズとして1語扱い	"open code"
#タグ	タグ完全一致	#reading
!unread / !untagged	未読のみ / タグ無しのみ	rust !unread

予約語の罠

and / or / not は大文字小文字を問わず演算子になり、語として検索されない。 語として使いたい場合は引用符で囲む ("not")。 or と tags 引数の併用は避ける (結合順が意図とずれるため、絞り込みは #タグ を q 末尾に書くか別呼び出しにする)。 括弧の対応が崩れる等で構文解析に失敗すると、警告なく 0 件になる。 0 件が不審な場合は括弧・引用符の対応を先に疑う。

タグ運用

• タグ絞りは #タグ で明示する (素の語がタグ名に一致するかはサーバ設定依存のため当てにしない)
• タグ名の空白はハイフンとして扱う (tags 引数も同様に変換される)
• tags 引数 ("a,b") は #a #b を q に追加するのと等価 (AND 追加)
• タグ名が不明な場合は、広めの検索で結果の tags 配列を集めて候補を拾う

結果の読み方

• 各件は url / title / description / tags / date_added を持つ
• ヒット理由が title・description に見えない場合、URL・メモ由来の可能性がある (メモ本文は返却されない)
• description が空の件がある
• date_added で新旧を判断する

応答の JSON フォーマット

成功時は text ブロック内に次の形の JSON 文字列が入る {"count": 総件数, "results": [...]} 各件は url / title / description / tags / date_added を持つ 失敗時は isError: true が付き、本文に原因が出る linkding API error: ... は linkding 側の HTTP エラーである linkding request failed: ... は通信・設定異常である isError の場合は同条件で再試行せず、本文の原因を読む

権限エラー

結果が Permission.Declined 系エラー (ERR Error: Permission.DeclinedError 等) の場合 検索の失敗ではなく実行権限の拒否である 同条件で再試行しても成功しない 対話セッションでは利用者に承認を求める 非対話実行 (run 等) では権限要求が自動拒否されるため --auto を付ける