BibDesk RAG

BibDeskで管理する文献を、Codexから検索・参照するためのローカルツールです。書誌情報で候補を絞り、PDFや補足資料の短い抜粋を、citekey・DOI・ファイルの場所・PDFページ番号とともに取得できます。

BibDeskの .bib と添付ファイルを読み取り専用で扱い、検索用の索引を別の場所に作ります。対象は登録した1つのライブラリと、そのライブラリにリンクされたファイルです。ライブラリの書き換えや添付ファイルの移動は行いません。

本体は KentoYana/BibDeskRAG、Homebrew Formulaは KentoYana/homebrew-tap で管理しています。v0.1.0のRelease にはソース配布・wheel・Homebrew用ビルド依存bundleと SHA256SUMS を掲載します。ソースから利用する場合は 開発とソースからの利用 を参照してください。

Homebrewで導入してCodexから使う

必要なものは、Mac、Homebrew、手元のBibDeskライブラリと添付ファイル、ローカルMCPを利用できるCodexです。Homebrew版にはPython環境が付属するため、利用者によるpyenv・pipの設定は不要です。Codex CLIは任意の接続設定ツールで、本体の依存関係として自動インストールされません。コマンドで登録する場合は下記の手順で用意し、CLIを使わない場合は アプリからの設定方法 を使ってください。

この手順は同じMac上のCodexとの接続を対象にします。ChatGPTの通常Chatへの接続は、この配布の対応範囲に含めません。別途ローカルプラグインを登録する必要もありません。

1. インストールする

Homebrewの外部tapからインストールします。

brew install KentoYana/tap/bibdesk-rag
bibdesk-rag --version

2. 自分のライブラリを登録し、索引を作る

以下は同じターミナルで実行します。/absolute/path/to/references.bib を自分の .bib の絶対パスに置き換えてください。空白を含むパスも引用符で囲んで指定できます。

bibdesk_rag_config="$HOME/Library/Application Support/bibdesk-rag/config.toml"
bibdesk-rag --config "$bibdesk_rag_config" init --bib "/absolute/path/to/references.bib"
bibdesk-rag --config "$bibdesk_rag_config" index
bibdesk-rag --config "$bibdesk_rag_config" status --json

init は設定を作成し、index は書誌情報と対応する添付ファイルの本文を索引化します。初回はファイル数・サイズに応じて時間がかかります。status で文献数と抽出状態を確認してください。本文を抽出できない添付があっても、書誌情報は検索できます。

既存の設定は上書きしません。登録済みなら init を繰り返さず、現在の設定を確認して update を使ってください。標準では設定と索引を ~/Library/Application Support/bibdesk-rag/ に保存します。原本やHomebrewのインストール先には保存しません。

3. Codexに読み取り専用MCPを登録する

コマンドで登録する場合は、まず codex --version でCodex CLIが使えるか確認します。未導入なら、HomebrewのCodex CLIをインストールしてください。すでに使えるCLIがあれば、追加インストールは不要です。

brew install --cask codex
codex --version

CLIが使えることを確認できたら、次を実行します。CLIを使わず登録する場合は Codex接続ガイド を参照してください。

codex mcp add bibdesk-rag -- "$(brew --prefix)/bin/bibdesk-rag-mcp" \
  --config "$HOME/Library/Application Support/bibdesk-rag/config.toml"
codex mcp get bibdesk-rag

この操作でCodexのMCP設定に bibdesk-rag を追加します。同名の登録がある場合は、先に codex mcp get bibdesk-rag で内容を確認してください。Homebrewの版番号を含まない実行パスを使うため、通常のアップグレード後も登録を使えます。索引を作る操作はCLIで行い、Codexへ公開するのは検索・参照の6ツールだけです。

登録内容の表示だけでは接続成功の確認にはなりません。Codexのアプリまたはセッションを再起動し、新しいチャットで次の検索を試してください。MCPサーバーはCodexが起動するため、ターミナルで常時起動したり brew services に登録したりする必要はありません。OpenAI公式MCP設定手順

4. Codexで検索する

次の依頼をCodexに送ります。「調べたいテーマ」を、自分が調べたい研究テーマやキーワードに置き換えてください。

bibdesk-rag MCPを使って、私の文献ライブラリから
「調べたいテーマ」に関連する文献を最大5件探してください。

まず書誌情報から候補を選び、取得できる本文で内容を確認してください。

タイトル、著者、発表年、citekey、DOIを一覧にし、
それぞれがテーマとどう関係するかを短く説明してください。
本文に基づく説明には、短い抜粋とPDFページ番号を添えてください。

本文を確認できなかった文献や、検索機能を利用できない場合は、
その旨を明記してください。

CodexがMCPの search_papers と search_fulltext を呼び、所蔵資料の出典を伴う結果を返すことが接続確認になります。結果が0件でも接続失敗とは限りません。PDFページ番号はファイル先頭を1とする番号で、論文に印刷されたページ番号とは異なる場合があります。

Related MCP server: calibre-mcp

日常の使い方

BibDeskで文献や添付ファイルを追加・変更した後は、索引を更新します。自動監視・自動更新は行いません。

bibdesk-rag --config "$HOME/Library/Application Support/bibdesk-rag/config.toml" update

ファイルのサイズと更新日時だけでは変更を判断できない場合は update --verify-hashes を使います。index は索引全体を作り直す操作です。どちらもBibDeskの原本は変更しません。

アプリを更新する場合は、次を実行します。

brew update
brew upgrade KentoYana/tap/bibdesk-rag

更新後はCodexのMCP接続を再起動します。Homebrewのupgrade・reinstall・uninstall時に設定や索引を削除するフックはありません。

アンインストール

まずCodexから bibdesk-rag の接続登録を外します。CLIを使う場合は次を実行し、CodexのアプリやCLIセッションを終了して、動作中のMCPサーバーを停止します。CLIがない場合の解除方法は 接続解除ガイド にあります。

codex mcp remove bibdesk-rag

その後、本体と専用のPython環境を削除します。

brew uninstall KentoYana/tap/bibdesk-rag

元の .bib と添付ファイル、保存済みの設定・索引は残ります。 設定・索引も不要なら、Finderの「移動 → フォルダへ移動」で ~/Library/Application Support/bibdesk-rag/ を開き、中身を確認して設定と索引をゴミ箱へ移動してください。保存先を変更した場合やCodex CLIも削除する場合は、詳しい削除手順 に従ってください。

検索できるものとデータの扱い

• 対応形式はPDF・CSV・TSV・XLSX・ZIPです。書誌情報と抽出できた本文をSQLite FTS5で検索します。意味検索・埋め込みモデル・OCRは使いません。

• PDFはページ番号、CSV/TSVはレコード行、XLSXはシートと行、ZIPは内部ファイル名を出典として返します。本文の検索結果にはchunk IDがあります。

• 本文なし・部分抽出・未対応形式を区別します。画像だけのPDF、暗号化や破損のある資料、段組・表などは本文を十分取得できない場合があります。研究上の主張は原本で確認してください。

• BibDesk RAGの索引作成・検索はローカルで完結し、外部API送信やモデルの自動ダウンロードはしません。Codexへ返した書誌情報・抜粋は、Codex側のモデル処理に渡ります。 その扱いはCodexの契約・設定に従います。

• 索引は平文のSQLiteです。アプリは設定・索引を0600で作成します。バックアップやMacのアクセス権は利用者が管理してください。

検索の絞り込み、独自の保存先、複数ライブラリ、抽出制約の詳細は CLI・設定ガイド を参照してください。

困ったとき

DBの整合性は bibdesk-rag doctor --json で検査できます。大きなDBでは検査用のメモリが必要です。問い合わせや不具合報告には、バージョン、実行コマンド、エラー文を添えてください。パス・書誌情報・本文などの私的な情報は必要に応じて伏せてください。

開発とソースからの利用

Python 3.11以上を対象とし、開発用の .python-version は3.12.13です。Homebrew版は python@3.14 と独立したvirtualenvを使用します。Homebrew利用者に以下の作業は不要です。

ソースのルートで、pyenvのローカル設定と標準venv・pipを使います。

pyenv install -s 3.12.13
pyenv local 3.12.13
python -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m pytest
.venv/bin/ruff check src tests tools

ソース版のコマンドは .venv/bin/bibdesk-rag と .venv/bin/bibdesk-rag-mcp です。Codexへ登録するときは後者の絶対パスを指定します。pyenvのglobal設定は変更しません。依存元BibDeskParserのビルドバックエンド名は uv_build ですが、uvコマンドやuvによる環境管理は使いません。

配布・検証・設計

.venv/bin/python -m build

sdistとwheelを dist/ に生成します。公開用Formulaには、実際に公開した固定URLと確認済みSHA-256が必要です。このリポジトリのFormulaは生成用テンプレートであり、インストール用のFormulaは外部tapにあります。ローカル検証と公開手順は Homebrew配布手順 にまとめています。

• 検証記録 / Homebrew検証 / MCP検証

• Codex接続の詳細 / CLI・設定・抽出仕様

• 設計と拡張：ローカルembedding、ハイブリッド検索、OCR、図表解析は未実装です。

• MIT License / 第三者ライセンスと依存一覧