Bibverify

Bibverify

破壊的な編集を行わずに、書誌情報の実在性とメタデータの整合性を検証します。

中国語 · インストール · クイックスタート · MCP · 開発

Bibverify は、研究者、編集者、自動化ツール、AI アシスタント向けの BibTeX メタデータ検証ツールです。まず DOI、PMID、PMCID、または arXiv の識別子を完全一致で検索し、その後、タイトル、著者、年、掲載誌、ページ情報を根拠として候補を評価します。

Bibverify は、書誌レコードが検索対象のソースで見つかるかどうか、またメタデータが一致するかどうかを評価します。研究結果が真実であること、データが真正であること、または掲載誌に信頼性があることを証明するものではありません。データベースにレコードが見つからないからといって、参考文献が捏造された証拠にはなりません。デフォルトでは、ソースの .bib ファイルは上書きされません。

主な特長

• DOI、PMID、PMCID、arXiv ID を優先して検索します。
• Crossref、OpenAlex、Semantic Scholar、PubMed、Europe PMC、CORE、DBLP、arXiv、bioRxiv などに対応しています。
• 識別子、タイトル、著者、年、掲載誌、ページ情報を照合する、説明可能なマルチシグナルマッチングを行います。解決可能な DOI のタイトルが大きく異なる場合、タイトル検索で隠されることなく identifier_conflict として扱われます。
• プロバイダーの結果を構造化し、真の該当なしと、レート制限、認証、ネットワーク、解析、プロバイダーの各エラーを区別します。
• 非破壊的なマージにより、プロバイダーが返さない abstract、keywords、file、note、カスタムフィールドを保持します。競合する永続識別子が自動的に上書きされることはありません。
• 接続プールを共有し、再試行、指数バックオフ、429/5xx 応答に対する Retry-After のサポートを備えています。
• 成功した GET 応答を有効期限付きの SQLite キャッシュに保存します。失敗はキャッシュされません。
• クロスプラットフォームのパス、エンコーディング、Unicode ファイル名、UTF-8 BOM、CRLF を処理します。
• JSON 出力、安定した終了コード、Python API、公式 SDK に基づく MCP サーバーを提供します。
• アトミックな出力書き込みと、バイト単位で内容を保持するバックアップに対応しています。

要件

• Windows、macOS、または Linux
• 有効にしたメタデータ API へのネットワークアクセス
• Python ディストリビューションを使用する場合は Python 3.11–3.14 が必要です。npm、コンテナ、ネイティブパッケージにはランタイムが同梱されています。

GitHub Actions では、サポート対象の 4 つの Python バージョンすべてで、3 つのオペレーティングシステムをテストしています。

インストール

現在公開されているリリースは v0.3.0 です。このブランチでは v0.4.0 の準備を進めています。v0.4.0 と記されたコマンドは、リンク先の npm、GHCR、または GitHub Release のアーティファクトが公開された後にのみ使用できます。

恒久的にインストールせずに実行するには、次のコマンドを使用します。

uvx bibverify --version

v0.4.0 からは、Node.js ユーザーは依存関係不要の npm ランチャーを利用できます。対応するネイティブリリースをダウンロードして SHA256SUMS を検証し、すべての引数と終了コードを引き継ぎます。

npx --yes @hylouis233/bibverify --version
pnpm dlx @hylouis233/bibverify --version
bunx --bun @hylouis233/bibverify --version

分離された Python 環境で CLI を継続的に利用するには、uv tool または pipx を使用します。

uv tool install bibverify

pipx install bibverify

仮想環境内では、通常の pip も使用できます。

python -m pip install --upgrade bibverify

各リリースでは、スモークテスト済みのネイティブパッケージも GitHub Releases で提供しています。v0.4.0 からは、 Windows x64 と、macOS および glibc 2.28 以降の Linux の x64・ARM64 を対象とするリリースマトリックスになります。musl ベースの Linux ユーザーは、Python パッケージまたはコンテナーイメージを使用してください。Windows ARM64 は、MCP ランタイムの依存関係が現在 Windows ARM64 用の wheel を提供していないため、まだネイティブ版を公開していません。npm は Windows 11 のエミュレーション環境でテスト済みの x64 ビルドを自動的に使用します。あるいは、ARM64 コンテナーを使用できます。

同じリリースでは、マルチアーキテクチャ対応のコンテナーも公開します。

docker run --rm ghcr.io/hylouis233/bibverify:0.4.0 --version

パッケージマネージャーのマニフェストは、未検証のビルド入力ではなく、最終リリースのバイト列から生成されます。Homebrew、Scoop、WinGet は、まだカタログに登録されていません。v0.4.0 では GitHub Release に提出可能な状態のマニフェストが添付されますが、その後も各外部カタログへの登録手続きや審査が必要です。展開状況については配布チャネルを参照してください。

クイックスタート

DOI を BibTeX に変換する

bibverify doi 10.1038/nature12373 --key example2013

機械可読形式のレスポンスを取得するには、次のコマンドを使用します。

bibverify doi 10.1038/nature12373 --json

.bib ファイルを検証する

まず、基本設定ファイルを作成します。

bibverify config init

references.bib を設定ファイルの隣に置き、次のコマンドを実行します。

bibverify check --config config.json

コマンドラインから入力パスと出力パスを上書きできます。

bibverify check references.bib --config config.json --output-dir bibverify-output

ファイルに書き込まずに結果を確認するには、次のコマンドを実行します。

bibverify check references.bib --dry-run --json

レポートを確認した後、信頼度の高いフィールド更新を明示的に適用します。Bibverify は最初にバイト単位で完全なバックアップを作成します。

bibverify check references.bib --apply

PowerShell の例：

py -m bibverify check '.\Bibliography\references.bib' --output-dir '.\Verification results'

互換性のため v0.2 形式も引き続き利用できますが、新しいスクリプトではサブコマンドを使用してください。

bibverify config.json
bibverify --doi 10.1038/nature12373 --key example2013

設定

最小限の設定例を以下に示します。

{
  "language": "EN",
  "bib_file": "references.bib",
  "encoding": "auto",
  "output_dir": "bibverify-output",
  "user_info": {
    "email": "[email protected]",
    "app_name": "Bibverify"
  }
}

よく使われるすべてのオプションについては、config_template.json を参照してください。

パスの動作は、予測しやすいように設定されています。

• 相対パスの bib_file と output_dir は、シェルの現在のディレクトリではなく、config.json があるディレクトリを基準に解決されます。
• output_dir を省略した場合、出力は入力の参考文献ファイルと同じ場所に書き込まれます。
• encoding: "auto" は、UTF-8 BOM 付き、UTF-8、GB18030 の順に試します。Latin-1 にフォールバックして不明なバイト列を文字化けに変換することはありません。

API キーとメールアドレス

キーはローカル設定に保存できますが、環境変数のほうが安全で、誤ってコミットされにくくなります。

環境変数	用途
BIBVERIFY_EMAIL	Crossref の polite pool と連絡先情報
BIBVERIFY_OPENALEX_API_KEY	OpenAlex
BIBVERIFY_SEMANTIC_SCHOLAR_API_KEY	Semantic Scholar
BIBVERIFY_PUBMED_API_KEY	PubMed/NCBI
BIBVERIFY_CORE_API_KEY	CORE

PowerShell：

$env:BIBVERIFY_EMAIL = '[email protected]'
$env:BIBVERIFY_OPENALEX_API_KEY = '...'
bibverify check --config config.json

Bash または Zsh：

export BIBVERIFY_EMAIL='[email protected]'
export BIBVERIFY_OPENALEX_API_KEY='...'
bibverify check --config config.json

クエリと照合の設定

{
  "query_settings": {
    "delay_between_requests": 0.5,
    "timeout": 10,
    "connect_timeout": 3.05,
    "read_timeout": 20,
    "max_retries": 3,
    "backoff_factor": 0.5,
    "stop_on_first_match": true,
    "match_threshold": 0.86,
    "ambiguous_threshold": 0.68,
    "auto_update_threshold": 0.92,
    "cache_enabled": true,
    "cache_ttl_hours": 168,
    "cache_path": ".bibverify-cache.sqlite3"
  }
}

connect_timeout と read_timeout は、それぞれ接続の確立とレスポンスの読み取りに上限を設けます。互換性のため、timeout フィールドも引き続き使用できます。match_threshold は候補を自動で採用する基準を制御し、ambiguous_threshold はレビュー対象となる妥当な候補を制御します。また、auto_update_threshold はフィールド変更に対する追加の条件です。値が高いほど、より慎重になります。相対キャッシュパスは設定ディレクトリを基準に解決されます。

bioRxiv の公式 details ルートでは、任意のタイトル検索はできません。そのため Bibverify は、完全一致する 10.1101/... DOI の場合にのみ bioRxiv を呼び出し、タイトルのみでの検索は Crossref や Europe PMC など、利用規約上それをサポートするプロバイダーに任せます。

CLI リファレンス

bibverify check [BIB_FILE] [--config PATH] [--output-dir DIR] [--format txt|json|jsonl|csv] [--dry-run|--apply] [--json]
bibverify doi DOI [--key KEY] [--config PATH] [--json]
bibverify config init [--output PATH] [--force]
bibverify doctor [--config PATH] [--json]
bibverify providers list [--json]
bibverify cache clear [--config PATH]
bibverify benchmark [--dataset PATH]
bibverify mcp [--config PATH] [--workspace-root DIR] [--transport stdio|streamable-http]
bibverify agent init [--target generic|codex|claude|cursor] [--output PATH]
bibverify skill export [--target ...]

終了コード：

コード	意味
0	検証が完了し、メタデータに不整合がありません
1	分類されていないコマンド失敗用に予約されたランタイムエラーです
2	メタデータに差異があるか、信頼度の高い更新があります
3	曖昧、未検出、または識別子の不整合がある項目についてレビューが必要です
4	プロバイダーを利用できず、検証が未完了です
5	入力ファイル、設定、または項目が無効です

--json を指定すると、標準出力には JSON のみが出力されます。診断メッセージは標準エラー出力に送られるため、CI やスクリプトで安全にコマンドを使用できます。

出力ファイル

references.bib という入力ファイルに対して、Bibverify は次のファイルを作成することがあります。

• bibverify_report_<timestamp>.<format>：状態、候補、プロバイダーエラー、信頼度、フィールドの出典情報を含む完全なレポートです。形式は txt、json、jsonl、または csv です。
• references_backup_<timestamp>.bib：ソースのバイト単位で同一のコピーです。
• references_updated_<timestamp>.bib：非破壊的なマージを適用した後の完全な参考文献リストです。変更がない場合は作成されません。
• references_review_<timestamp>.bib：曖昧、未検出、ソースを利用できない、識別子の不整合がある、または無効な項目です。レビューが必要なものがない場合は作成されません。

レポート全体の complete 値が true になるのは、すべての項目の検証が完了した場合のみです。別のソースで候補が見つかっていても、プロバイダーがレート制限を受けている、または到達不能な場合は false になります。各 field_diffs レコードには、元の値と提案値、ソース、信頼度、正規化後の同等性、アクション、理由が含まれます。

各出力は output_settings で個別に無効化できます。--dry-run はこれらの設定を上書きし、書き込みを一切行いません。デフォルトのコマンドは変更案を書き込むだけです。ソースを変更するのは、バックアップを作成した後に --apply を指定した場合のみです。

プロバイダーの優先順位付け

静的な優先順位は、あくまで出発点です。

1. DOI がある場合は Crossref の優先度を上げ、最初に DOI の完全一致エンドポイントを使用します。解決可能な DOI に対してタイトルが実質的に異なる場合は、identifier_conflict として処理を停止します。
2. PMID、PMCID、または生物医学分野のヒントがある場合は、PubMed と Europe PMC の優先度を上げます。
3. arXiv 識別子がある場合は、arXiv の優先度を上げます。
4. コンピューターサイエンス分野の出版物に関するヒントがある場合は、DBLP の優先度を上げます。

現在、Unpaywall は主要な書誌メタデータプロバイダーではなく、オープンアクセス情報を補足するプロバイダーとして扱われています。プロバイダーの状態は、matched、no_match、ambiguous、rate_limited、auth_error、network_error、parse_error、provider_error、skipped を区別します。

MCP と AI アシスタント

Bibverify は公式の MCP Python SDK を使用し、ローカルの stdio および Streamable HTTP トランスポートに対応しています。

stdio サーバーを起動します：

bibverify mcp --config config.json --workspace-root .

MCP クライアントの設定：

{
  "mcpServers": {
    "bibverify": {
      "command": "bibverify",
      "args": ["mcp", "--config", "config.json"]
    }
  }
}

Node 向けの MCP クライアントでは、npm ランチャーを直接使用できます：

{
  "mcpServers": {
    "bibverify": {
      "command": "npx",
      "args": ["--yes", "@hylouis233/bibverify", "mcp"]
    }
  }
}

コンテナー化された stdio MCP では、現在のディレクトリのみが書き込み可能なワークスペースになります：

docker run --rm -i -v "$PWD:/workspace" ghcr.io/hylouis233/bibverify:0.4.0 \
  mcp --workspace-root /workspace

Streamable HTTP を起動します：

bibverify mcp --transport streamable-http --config config.json

MCP は、デフォルトで設定ディレクトリをワークスペースのルートとして扱います。そのルート外にある設定ファイルや .bib ファイルの読み取りを拒否し、レポート、キャッシュ、更新データのルート外への書き込みをブロックします。アクセス範囲を広げるには、サーバーの起動時に --workspace-root を明示的に設定してください。公式 MCP SDK が、プロトコルネゴシエーション、スキーマ、構造化された結果、進捗状況、キャンセルを処理します。

利用可能なツール：

• doi_to_bibtex
• rank_lookup_sources
• explain_update_diff
• verify_bib_file

Codex、Claude、Cursor、または汎用 MCP クライアント向けのセットアップファイルを生成します：

bibverify agent init --target codex --output .bibverify-agent --config config.json
bibverify doctor --config config.json

配布チャネル

チャネル	コマンドまたは成果物	提供状況
PyPI	python -m pip install bibverify	公開済み
uv	uvx bibverify または uv tool install bibverify	公開済み
pipx	pipx install bibverify	公開済み
npm	npx --yes @hylouis233/bibverify	v0.4.0 で提供予定。未公開
pnpm / Bun	pnpm dlx @hylouis233/bibverify / bunx --bun @hylouis233/bibverify	v0.4.0 で提供予定。未公開
GHCR	docker pull ghcr.io/hylouis233/bibverify:0.4.0	v0.4.0 で提供予定。未公開
ネイティブ	Windows x64、macOS、および glibc 2.28+ の Linux x64/ARM64	v0.4.0 で提供予定。未公開
Homebrew	リリース成果物 bibverify.rb	v0.4.0 で提出用マニフェストを用意予定。カタログは未公開
Scoop	リリース成果物 bibverify.json	v0.4.0 で提出用マニフェストを用意予定。カタログは未公開
WinGet	リリース成果物 Hylouis233.Bibverify*.yaml	v0.4.0 で提出用マニフェストを用意予定。カタログは未公開
MCP Registry	io.github.Hylouis233/bibverify	検索用メタデータは公開済み。上記パッケージのいずれかからインストールしてください

npm パッケージは、別の実装ではなく小規模なランチャーです。PyPI、npm、ネイティブパッケージ、コンテナーのいずれでも、検証エンジンには同じ Python コードベースを使用します。リリース成果物には SHA256SUMS が含まれます。npm は実行前に選択されたバイナリを検証し、Homebrew、Scoop、WinGet のマニフェストには同じリリースハッシュが指定されています。

Python API

from bibverify.checker import BibTeXChecker

checker = BibTeXChecker("config.json")
summary = checker.run()
print(summary["counts"])

from bib_check import BibTeXChecker は 0.3 リリース系列の間、引き続き互換性がありますが、新しいコードでは上記のパッケージインポートを使用してください。

開発

git clone https://github.com/Hylouis233/bibverify.git
cd bibverify
python -m venv .venv

環境を有効化した後、次を実行します。

python -m pip install -e ".[dev]"
python -m pytest
python -m ruff check src tests tools bib_check.py
python -m ruff format --check src tests tools bib_check.py
python -m mypy
python -m build
python -m twine check dist/*
python -m bibverify benchmark --dataset benchmarks/cases.json
python -m pip_audit . --strict
(cd npm && npm ci && npm test && npm pack --dry-run)
docker build --tag bibverify:dev .

プッシュする前に、python tools/fix.py を実行してください。このコマンドは、CI がチェックするパスだけを対象に ruff format とインポートの並べ替えを適用し、その後 CI の ruff check と ruff format --check コマンドを実行します。手動で修正が必要な箇所がある場合は失敗します。pre-commit install を実行すると、コミットフックとして同じコマンドが実行されます（.pre-commit-config.yaml を参照）。

CI では、Python 3.11～3.14 を使用して Windows、macOS、Linux でテストを実施します。プロバイダーのフィクスチャ、ゴールデン書き込み安全性テスト、リンティング、型チェック、カバレッジ、オフラインベンチマーク、依存関係の監査、Python および npm パッケージのビルド、コンテナーのスモークテスト、CycloneDX SBOM が含まれます。GitHub Actions はコミット SHA に固定され、MCP Publisher はバージョンを固定し、SHA-256 で検証されます。PyPI と npm は来歴証明を付与した Trusted Publishing を使用し、GHCR は SBOM とビルド来歴を含むマルチアーキテクチャイメージを公開します。

benchmarks/cases.json は、短いタイトルによる誤検出、DOI の競合、プレプリントのタイトルのバリエーション、Unicode／LaTeX、作り出された著者の組み合わせを対象とする、小規模なオフライン回帰テストセットです。完全な科学的評価ではなく、そのスコアを実世界の性能の上限として解釈してはいけません。より幅広く再配布可能な、人手でラベル付けされたケースの提供を歓迎します。

引用

Bibverify が研究に役立った場合は、次のように引用してください。

@software{bibverify2025,
  title = {Bibverify: A Multi-Platform BibTeX Reference Verification Tool},
  author = {Hong Liu},
  year = {2025},
  url = {https://github.com/Hylouis233/bibverify},
  doi = {10.5281/zenodo.17338090}
}

ライセンス

MIT ライセンス