Skip to content
Back to search

bibverify

Cross-platform BibTeX verification for researchers and AI assistants — CLI, Python API, MCP server, and explainable multi-source matching.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Hylouis233/bibverify with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Hylouis233/bibverify'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hylouis233--bibverify/badge.svg)](/listings/hylouis233--bibverify)

HTML

<a href="/listings/hylouis233--bibverify"><img src="/api/listings/hylouis233--bibverify/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The current published release is v0.3.0. This branch prepares v0.4.0; commands marked **v0.4.0** become usable only after their linked npm, GHCR, or GitHub Release artifact has been published.

Run without a permanent installation:

uvx bibverify --version

Starting with v0.4.0, Node.js users can use the zero-dependency npm launcher. It downloads the matching native release, verifies `SHA256SUMS`, and forwards every argument and exit code:

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

For a persistent CLI in an isolated Python environment, use `uv tool` or `pipx`:

uv tool install bibverify
pipx install bibverify

Inside a virtual environment, regular pip also works:

python -m pip install --upgrade bibverify

Each release also provides smoke-tested native packages on [GitHub Releases](https://github.com/Hylouis233/bibverify/releases). Beginning with v0.4.0, the release matrix covers Windows x64 plus macOS and glibc 2.28+ Linux on both x64 and ARM64. musl-based Linux users should use the Python package or container image. Windows ARM64 is not published natively yet because an MCP runtime dependency does not currently provide Windows ARM64 wheels; npm automatically uses the tested x64 build under Windows 11 emulation, or you can use the ARM64 container instead.

The same release publishes a multi-architecture container:

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

Package-manager manifests are generated from the final release bytes, not from unverified build inputs. Homebrew, Scoop, and WinGet are not live catalog entries yet: v0.4.0 will attach submission- ready manifests to GitHub Release, after which each external catalog still requires onboarding or review. See [Distribution channels](#distribution-channels) for rollout status.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 437 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Bibverify
  2. <!-- mcp-name: io.github.Hylouis233/bibverify -->
  3. <p align="center">
  4. <strong>Verify bibliographic existence and metadata consistency without destructive edits.</strong>
  5. </p>
  6. <p align="center">
  7. <a href="README_CN.md">Chinese</a> · <a href="#install">Install</a> · <a href="#quick-start">Quick start</a> · <a href="#mcp-and-ai-assistants">MCP</a> · <a href="#development">Development</a>
  8. </p>
  9. <p align="center">
  10. <a href="https://pypi.org/project/bibverify/"><img src="https://img.shields.io/pypi/v/bibverify.svg" alt="PyPI"></a>
  11. <a href="https://pypi.org/project/bibverify/"><img src="https://img.shields.io/pypi/pyversions/bibverify.svg" alt="Python versions"></a>
  12. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
  13. <a href="https://github.com/Hylouis233/bibverify/actions/workflows/ci.yml"><img src="https://github.com/Hylouis233/bibverify/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  14. </p>
  15. Bibverify is a BibTeX metadata verification tool for researchers, editors, automation, and AI assistants. It starts with exact DOI, PMID, PMCID, or arXiv identifiers and then scores candidates from title, author, year, venue, and pagination evidence.
  16. Bibverify evaluates whether a bibliographic record can be located in the queried sources and whether its metadata agrees. It does not prove that research findings are true, data is authentic, or a venue is reputable. A missing database record is not evidence that a reference is fabricated. By default, the source `.bib` file is never overwritten.
  17. ## Highlights
  18. - Identifier-first lookup for DOI, PMID, PMCID, and arXiv IDs.
  19. - Crossref, OpenAlex, Semantic Scholar, PubMed, Europe PMC, CORE, DBLP, arXiv, bioRxiv, and more.
  20. - Explainable multi-signal matching across identifiers, title, authors, year, venue, and pages. A resolvable DOI with a materially different title becomes `identifier_conflict` instead of being hidden by title search.
  21. - Structured provider outcomes distinguish a genuine no-match from rate limiting, authentication, network, parsing, and provider failures.
  22. - Non-destructive merging preserves `abstract`, `keywords`, `file`, `note`, and custom fields that providers do not return; conflicting persistent identifiers are never overwritten automatically.
  23. - A shared connection pool with retries, exponential backoff, and `Retry-After` support for `429/5xx` responses.
  24. - An expiring SQLite cache for successful GET responses; failures are never cached.
  25. - Cross-platform path, encoding, Unicode filename, UTF-8 BOM, and CRLF handling.
  26. - JSON output, stable exit codes, a Python API, and an MCP server built on the official SDK.
  27. - Atomic output writes and byte-preserving backups.
  28. ## Requirements
  29. - Windows, macOS, or Linux
  30. - Network access to the enabled metadata APIs
  31. - Python 3.11–3.14 when using the Python distribution; npm, containers, and native packages bundle their runtime
  32. GitHub Actions tests all three operating systems across all four supported Python versions.
  33. ## Install
  34. The current published release is v0.3.0. This branch prepares v0.4.0; commands marked **v0.4.0**
  35. become usable only after their linked npm, GHCR, or GitHub Release artifact has been published.
  36. Run without a permanent installation:
  37. ```bash
  38. uvx bibverify --version
  39. ```
  40. Starting with v0.4.0, Node.js users can use the zero-dependency npm launcher. It downloads the
  41. matching native release, verifies `SHA256SUMS`, and forwards every argument and exit code:
  42. ```bash
  43. npx --yes @hylouis233/bibverify --version
  44. pnpm dlx @hylouis233/bibverify --version
  45. bunx --bun @hylouis233/bibverify --version
  46. ```
  47. For a persistent CLI in an isolated Python environment, use `uv tool` or `pipx`:
  48. ```bash
  49. uv tool install bibverify
  50. ```
  51. ```bash
  52. pipx install bibverify
  53. ```
  54. Inside a virtual environment, regular pip also works:
  55. ```bash
  56. python -m pip install --upgrade bibverify
  57. ```
  58. Each release also provides smoke-tested native packages on
  59. [GitHub Releases](https://github.com/Hylouis233/bibverify/releases). Beginning with v0.4.0, the
  60. release matrix covers Windows x64 plus macOS and glibc 2.28+ Linux on both x64 and ARM64. musl-based
  61. Linux users should use the Python package or container image. Windows ARM64 is not published natively
  62. yet because an MCP runtime dependency does not currently provide Windows ARM64 wheels; npm
  63. automatically uses the tested x64 build under Windows 11 emulation, or you can use the ARM64 container
  64. instead.
  65. The same release publishes a multi-architecture container:
  66. ```bash
  67. docker run --rm ghcr.io/hylouis233/bibverify:0.4.0 --version
  68. ```
  69. Package-manager manifests are generated from the final release bytes, not from unverified build
  70. inputs. Homebrew, Scoop, and WinGet are not live catalog entries yet: v0.4.0 will attach submission-
  71. ready manifests to GitHub Release, after which each external catalog still requires onboarding or
  72. review. See [Distribution channels](#distribution-channels) for rollout status.
  73. ## Quick start
  74. ### Convert a DOI to BibTeX
  75. ```bash
  76. bibverify doi 10.1038/nature12373 --key example2013
  77. ```
  78. For a machine-readable response:
  79. ```bash
  80. bibverify doi 10.1038/nature12373 --json
  81. ```
  82. ### Verify a `.bib` file
  83. Create a starter configuration:
  84. ```bash
  85. bibverify config init
  86. ```
  87. Place `references.bib` next to the configuration and run:
  88. ```bash
  89. bibverify check --config config.json
  90. ```
  91. You can override the input and output paths from the command line:
  92. ```bash
  93. bibverify check references.bib --config config.json --output-dir bibverify-output
  94. ```
  95. Inspect results without writing any file:
  96. ```bash
  97. bibverify check references.bib --dry-run --json
  98. ```
  99. After reviewing the report, explicitly apply high-confidence field updates. Bibverify creates a byte-for-byte backup first:
  100. ```bash
  101. bibverify check references.bib --apply
  102. ```
  103. PowerShell example:
  104. ```powershell
  105. py -m bibverify check '.\Bibliography\references.bib' --output-dir '.\Verification results'
  106. ```
  107. The v0.2 forms remain available for compatibility, although new scripts should use subcommands:
  108. ```bash
  109. bibverify config.json
  110. bibverify --doi 10.1038/nature12373 --key example2013
  111. ```
  112. ## Configuration
  113. A minimal configuration looks like this:
  114. ```json
  115. {
  116. "language": "EN",
  117. "bib_file": "references.bib",
  118. "encoding": "auto",
  119. "output_dir": "bibverify-output",
  120. "user_info": {
  121. "email": "your_email@example.com",
  122. "app_name": "Bibverify"
  123. }
  124. }
  125. ```
  126. See [`config_template.json`](config_template.json) for every commonly used option.
  127. Path behavior is intentionally predictable:
  128. - Relative `bib_file` and `output_dir` values are resolved from the directory containing `config.json`, not the shell's current directory.
  129. - If `output_dir` is omitted, output is written next to the input bibliography.
  130. - `encoding: "auto"` tries UTF-8 with BOM, UTF-8, and GB18030. It does not fall back to Latin-1 and silently turn unknown bytes into mojibake.
  131. ### API keys and email
  132. Keys can be stored in a local configuration, but environment variables are safer and harder to commit accidentally:
  133. | Environment variable | Used for |
  134. |---|---|
  135. | `BIBVERIFY_EMAIL` | Crossref polite pool and contact information |
  136. | `BIBVERIFY_OPENALEX_API_KEY` | OpenAlex |
  137. | `BIBVERIFY_SEMANTIC_SCHOLAR_API_KEY` | Semantic Scholar |
  138. | `BIBVERIFY_PUBMED_API_KEY` | PubMed/NCBI |
  139. | `BIBVERIFY_CORE_API_KEY` | CORE |
  140. PowerShell:
  141. ```powershell
  142. $env:BIBVERIFY_EMAIL = 'you@example.com'
  143. $env:BIBVERIFY_OPENALEX_API_KEY = '...'
  144. bibverify check --config config.json
  145. ```
  146. Bash or Zsh:
  147. ```bash
  148. export BIBVERIFY_EMAIL='you@example.com'
  149. export BIBVERIFY_OPENALEX_API_KEY='...'
  150. bibverify check --config config.json
  151. ```
  152. ### Query and matching settings
  153. ```json
  154. {
  155. "query_settings": {
  156. "delay_between_requests": 0.5,
  157. "timeout": 10,
  158. "connect_timeout": 3.05,
  159. "read_timeout": 20,
  160. "max_retries": 3,
  161. "backoff_factor": 0.5,
  162. "stop_on_first_match": true,
  163. "match_threshold": 0.86,
  164. "ambiguous_threshold": 0.68,
  165. "auto_update_threshold": 0.92,
  166. "cache_enabled": true,
  167. "cache_ttl_hours": 168,
  168. "cache_path": ".bibverify-cache.sqlite3"
  169. }
  170. }
  171. ```
  172. `connect_timeout` and `read_timeout` separately bound connection setup and response reads; the compatibility `timeout` field remains available. `match_threshold` controls automatic candidate acceptance, `ambiguous_threshold` controls which plausible candidates enter review, and `auto_update_threshold` is an additional gate for field changes. Higher values are more conservative. Relative cache paths are resolved from the config directory.
  173. The official bioRxiv `details` route does not provide arbitrary title search. Bibverify therefore calls bioRxiv only for an exact `10.1101/...` DOI and leaves title-only discovery to providers whose contracts support it, such as Crossref and Europe PMC.
  174. ## CLI reference
  175. ```text
  176. bibverify check [BIB_FILE] [--config PATH] [--output-dir DIR] [--format txt|json|jsonl|csv] [--dry-run|--apply] [--json]
  177. bibverify doi DOI [--key KEY] [--config PATH] [--json]
  178. bibverify config init [--output PATH] [--force]
  179. bibverify doctor [--config PATH] [--json]
  180. bibverify providers list [--json]
  181. bibverify cache clear [--config PATH]
  182. bibverify benchmark [--dataset PATH]
  183. bibverify mcp [--config PATH] [--workspace-root DIR] [--transport stdio|streamable-http]
  184. bibverify agent init [--target generic|codex|claude|cursor] [--output PATH]
  185. bibverify skill export [--target ...]
  186. ```
  187. Exit codes:
  188. | Code | Meaning |
  189. |---:|---|
  190. | `0` | Verification completed and metadata is consistent |
  191. | `1` | Runtime error reserved for uncategorized command failures |
  192. | `2` | Metadata differences or high-confidence updates exist |
  193. | `3` | Ambiguous, not-found, or identifier-conflict entries require review |
  194. | `4` | A provider was unavailable and verification is incomplete |
  195. | `5` | The input file, configuration, or entry is invalid |
  196. With `--json`, stdout contains JSON only. Diagnostics go to stderr, which keeps the command safe for CI and scripts.
  197. ## Output files
  198. For an input named `references.bib`, Bibverify may create:
  199. - `bibverify_report_<timestamp>.<format>`: complete states, candidates, provider errors, confidence, and field provenance in `txt`, `json`, `jsonl`, or `csv`.
  200. - `references_backup_<timestamp>.bib`: byte-for-byte copy of the source.
  201. - `references_updated_<timestamp>.bib`: complete bibliography after non-destructive merging; omitted when nothing changes.
  202. - `references_review_<timestamp>.bib`: ambiguous, not-found, unavailable-source, identifier-conflict, or invalid entries; omitted when nothing needs review.
  203. The report-level `complete` value is true only when every entry completed verification. A rate-limited or unreachable provider makes it false even if another source found a candidate. Each `field_diffs` record includes original/suggested values, source, confidence, normalized equivalence, action, and reason.
  204. Each output can be disabled independently through `output_settings`. `--dry-run` overrides those settings and performs zero writes. The default command only writes proposals; only `--apply` changes the source after a backup.
  205. ## Provider ranking
  206. Static priority is only the starting point:
  207. 1. A DOI promotes Crossref and uses its exact endpoint first. A resolvable DOI with a materially different title stops as `identifier_conflict`.
  208. 2. PMID, PMCID, or biomedical hints promote PubMed and Europe PMC.
  209. 3. An arXiv identifier promotes arXiv.
  210. 4. Computer-science venue hints promote DBLP.
  211. Unpaywall is currently treated as open-access enrichment, not as a primary bibliographic metadata provider. Provider states distinguish `matched`, `no_match`, `ambiguous`, `rate_limited`, `auth_error`, `network_error`, `parse_error`, `provider_error`, and `skipped`.
  212. ## MCP and AI assistants
  213. Bibverify uses the official MCP Python SDK and supports local stdio and Streamable HTTP transports.
  214. Start a stdio server:
  215. ```bash
  216. bibverify mcp --config config.json --workspace-root .
  217. ```
  218. MCP client configuration:
  219. ```json
  220. {
  221. "mcpServers": {
  222. "bibverify": {
  223. "command": "bibverify",
  224. "args": ["mcp", "--config", "config.json"]
  225. }
  226. }
  227. }
  228. ```
  229. The npm launcher can be used directly by Node-oriented MCP clients:
  230. ```json
  231. {
  232. "mcpServers": {
  233. "bibverify": {
  234. "command": "npx",
  235. "args": ["--yes", "@hylouis233/bibverify", "mcp"]
  236. }
  237. }
  238. }
  239. ```
  240. Containerized stdio MCP keeps the current directory as the only writable workspace:
  241. ```bash
  242. docker run --rm -i -v "$PWD:/workspace" ghcr.io/hylouis233/bibverify:0.4.0 \
  243. mcp --workspace-root /workspace
  244. ```
  245. Start Streamable HTTP:
  246. ```bash
  247. bibverify mcp --transport streamable-http --config config.json
  248. ```
  249. MCP treats the configuration directory as its workspace root by default. It rejects config or `.bib` reads outside that root and blocks report, cache, or update writes outside it. Broaden access only by explicitly setting `--workspace-root` when starting the server. The official MCP SDK handles protocol negotiation, schemas, structured results, progress, and cancellation.
  250. Available tools:
  251. - `doi_to_bibtex`
  252. - `rank_lookup_sources`
  253. - `explain_update_diff`
  254. - `verify_bib_file`
  255. Generate setup files for Codex, Claude, Cursor, or a generic MCP client:
  256. ```bash
  257. bibverify agent init --target codex --output .bibverify-agent --config config.json
  258. bibverify doctor --config config.json
  259. ```
  260. ## Distribution channels
  261. | Channel | Command or artifact | Availability |
  262. |---|---|---|
  263. | PyPI | `python -m pip install bibverify` | Published |
  264. | uv | `uvx bibverify` or `uv tool install bibverify` | Published |
  265. | pipx | `pipx install bibverify` | Published |
  266. | npm | `npx --yes @hylouis233/bibverify` | Planned for v0.4.0; not published yet |
  267. | pnpm / Bun | `pnpm dlx @hylouis233/bibverify` / `bunx --bun @hylouis233/bibverify` | Planned for v0.4.0; not published yet |
  268. | GHCR | `docker pull ghcr.io/hylouis233/bibverify:0.4.0` | Planned for v0.4.0; not published yet |
  269. | Native | Windows x64; macOS and glibc 2.28+ Linux x64/ARM64 | Planned for v0.4.0; not published yet |
  270. | Homebrew | Release asset `bibverify.rb` | Submission manifest planned for v0.4.0; catalog not live |
  271. | Scoop | Release asset `bibverify.json` | Submission manifest planned for v0.4.0; catalog not live |
  272. | WinGet | Release assets `Hylouis233.Bibverify*.yaml` | Submission manifests planned for v0.4.0; catalog not live |
  273. | MCP Registry | [`io.github.Hylouis233/bibverify`](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Hylouis233%2Fbibverify/versions/latest) | Published discovery metadata; install through one of the package entries above |
  274. The npm package is a small launcher rather than a second implementation. The verification engine
  275. remains the same Python codebase across PyPI, npm, native packages, and containers. Release assets
  276. include `SHA256SUMS`; npm verifies the selected binary before execution, and Homebrew, Scoop, and
  277. WinGet manifests pin the same release hashes.
  278. ## Python API
  279. ```python
  280. from bibverify.checker import BibTeXChecker
  281. checker = BibTeXChecker("config.json")
  282. summary = checker.run()
  283. print(summary["counts"])
  284. ```
  285. `from bib_check import BibTeXChecker` remains compatible during the 0.3 release line, but new code should use the package import above.
  286. ## Development
  287. ```bash
  288. git clone https://github.com/Hylouis233/bibverify.git
  289. cd bibverify
  290. python -m venv .venv
  291. ```
  292. After activating the environment:
  293. ```bash
  294. python -m pip install -e ".[dev]"
  295. python -m pytest
  296. python -m ruff check src tests tools bib_check.py
  297. python -m ruff format --check src tests tools bib_check.py
  298. python -m mypy
  299. python -m build
  300. python -m twine check dist/*
  301. python -m bibverify benchmark --dataset benchmarks/cases.json
  302. python -m pip_audit . --strict
  303. (cd npm && npm ci && npm test && npm pack --dry-run)
  304. docker build --tag bibverify:dev .
  305. ```
  306. Before pushing, run `python tools/fix.py`. It applies `ruff format` and import sorting to
  307. exactly the paths CI checks, then runs CI's `ruff check` and `ruff format --check` commands
  308. and fails on anything that needs a manual fix. `pre-commit install` runs the same command
  309. as a commit hook (see `.pre-commit-config.yaml`).
  310. CI tests Windows, macOS, and Linux on Python 3.11–3.14, including provider fixtures, golden write-safety tests, lint, typing, coverage, the offline benchmark, dependency auditing, Python and npm package builds, a container smoke test, and a CycloneDX SBOM. GitHub Actions are pinned to commit SHAs, while the MCP Publisher is version-pinned and SHA-256 verified. PyPI and npm use Trusted Publishing with provenance attestations, and GHCR publishes multi-architecture images with an SBOM and build provenance.
  311. `benchmarks/cases.json` is a small offline regression set covering short-title false positives, DOI conflicts, preprint title variants, Unicode/LaTeX, and fabricated author combinations. It is not a complete scientific evaluation and its scores must not be interpreted as real-world performance ceilings. Contributions of broader, redistributable, human-labeled cases are welcome.
  312. ## Citation
  313. If Bibverify supports your research, please cite:
  314. ```bibtex
  315. @software{bibverify2025,
  316. title = {Bibverify: A Multi-Platform BibTeX Reference Verification Tool},
  317. author = {Hong Liu},
  318. year = {2025},
  319. url = {https://github.com/Hylouis233/bibverify},
  320. doi = {10.5281/zenodo.17338090}
  321. }
  322. ```
  323. ## License
  324. [MIT License](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.