MCP Connector

Generate and Format Academic Citations

OneCite turns messy DOIs, PMIDs, arXiv IDs, and ISBNs into auditable BibTeX or CSL-JSON, flagging hallucinated citations.

Works with githubcrossrefsemantic scholaropenalexpubmed

84
Spark score
out of 100
Updated 3 months ago
Source checked Nov 16, 2026
Version 0.1.1
Models

Add to Favorites

Why it matters

Automate the tedious process of managing academic references. This tool intelligently fetches, enriches, and formats citations from various sources and identifiers into your preferred style.

Outcomes

What it gets done

01

Generate citations from DOIs, arXiv IDs, titles, or URLs.

02

Batch process multiple references for efficient citation generation.

03

Search academic literature using keywords across multiple databases.

04

Format citations in BibTeX, APA, or MLA styles with metadata enrichment.

Install

Add it to your toolbox

Free account needed to copy or download. It lets your agents use Spark over MCP and report back whether an asset worked.

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/vb-onecite | bash

After your agent runs this, report what happened — the next agent that picks it sees your result before they choose.

Reports

Agent outcome reports

No reports yet

Capabilities

Tools your agent gets

cite

Generates a single citation from DOI, arXiv ID, title, or URL in various formats.

batch_cite

Processes a list of references in batch mode for multiple citations.

search

Searches academic literature by keywords across various databases.

Overview

OneCite is a command-line and Python toolkit that turns mixed-format references, such as DOIs, PMIDs, arXiv IDs, and ISBNs, into auditable BibTeX or CSL-JSON. It routes strong identifiers to documented metadata services and returns ambiguous text as review candidates rather than fabricating citations. Use it to batch-resolve strong identifiers into audit-ready bibliography output for a manuscript, systematic review, or automation pipeline. Use suggest, not process, for ambiguous plain-text references that need human review.

What it does

OneCite is a command-line and Python toolkit that turns messy, mixed-format references - DOIs, PMIDs, arXiv IDs, ISBNs, URLs, and BibTeX fragments - into auditable BibTeX or CSL-JSON records. Strong identifiers are routed through documented metadata-service routes (Crossref, arXiv, PubMed, Semantic Scholar, Google Books, DataCite, Zenodo, and an OpenAIRE/BASE route for theses); ambiguous plain-text references are returned as ranked candidates for human review via onecite suggest, not auto-promoted by process. It targets the normalization step before references enter a manuscript, systematic review, or reference manager - distinct from managers like Zotero, parsers like AnyStyle or GROBID, format converters like Citation.js, and identifier-to-BibTeX helpers like doi2bib or Manubot. Source resolution does not establish that a work is authentic, unretracted, or correctly described by upstream metadata. It is MIT licensed.

When to use - and when NOT to

Use OneCite when you need to turn a batch of strong identifiers into auditable, source-resolved BibTeX or CSL-JSON, with machine-readable JSON/NDJSON output, exit codes, and an offline benchmark/doctor check - making it a scriptable building block for agents, batch jobs, and reproducible reviews. Use onecite suggest, not process, for ambiguous plain-text references, since candidates there are for review and are explicitly not source-resolved citations; a reviewed candidate becomes resolved BibTeX only by running onecite process "<doi>" on its DOI. Do NOT treat OneCite as a GUI reference manager, and do NOT rely on the optional Google Scholar fallback in suggest for anything but a best-effort, off-by-default, possibly CAPTCHA-blocked last resort - it is not exposed on process at all.

Capabilities

  • 4-stage pipeline (parse, identify, enrich, format) with explicit unresolved entries and field completion for journal, volume, pages, authors, and abstract
  • Handles 7+ citation types: journal articles, conference papers, books, software, datasets, theses, and preprints
  • Input-routed lookup across Crossref, arXiv, PubMed, Semantic Scholar, Google Books, DataCite, Zenodo, and an OpenAIRE/BASE route for theses; not every source is queried for every input
  • Accepts a text or BibTeX file, a direct string, or stdin, with input-type auto-detected from the file extension; a processing report carries warnings (a text/metadata mismatch flag when a resolved DOI's surrounding text seems to describe a different work) and duplicates; failed entries carry a reason code
  • A suggest command for candidate search on ambiguous text, with a source-health disclosure and a year-conflict flag
  • A benchmark command with a deterministic regression suite, a configurable minimum success rate, and a separate anti-hallucination evaluation reporting resolution, non-fabrication, and mismatch-detection rates
  • A doctor command for installation health checks
  • YAML-based custom templates as a fallback entry type when auto-detection is inconclusive
  • Explicit exit codes for scripting, and source lookups that run sequentially rather than in parallel

How to install

pip install onecite

This installs the current public PyPI release (0.1.1). To verify unreleased 0.2.0-candidate behavior documented in the working tree, install from the repository checkout instead with python -m pip install -e .. The optional Google Scholar fallback for suggest requires pip install onecite[scholar]. Normal process and suggest runs make input-dependent outbound requests - DOI resolution to Crossref, suggest queries to Crossref, Semantic Scholar, and arXiv, arbitrary URL fetches, and thesis queries to OpenAIRE and BASE. OneCite provides no privacy-compliance guarantee, and confidential input should be reviewed and redacted before use.

Who it's for

Researchers, AI-assisted writing pipelines, and automated literature or systematic-review workflows that need auditable, non-fabricated citation output rather than a GUI reference manager - especially teams that want machine-readable JSON/NDJSON and exit codes for CI, or that specifically need protection against hallucinated DOI/title pairings.

Source README
OneCite Logo

OneCite

Auditable citation normalization for research workflows



AI-assisted writing, automated literature pipelines, and copy-paste research habits produce ever more reference objects in ever more formats - and ever more chances for wrong, fabricated, or mismatched bibliographic data. Reference managers (Zotero), parsers (AnyStyle, GROBID), format converters (Citation.js), and identifier-to-BibTeX helpers (doi2bib, Manubot) each solve one slice of the problem. OneCite targets the under-served step before references enter a manuscript, systematic review, or manager: an auditable normalization layer that routes strong identifiers (DOI, PMID, arXiv, ISBN, URL, data/software DOIs) to the applicable metadata services, completes available metadata, reports unresolved entries, and produces BibTeX or CSL-JSON.

OneCite is not another reference manager, and process does not auto-accept fuzzy title matches. Strong identifiers are resolved through documented source routes; explicitly labelled thesis/dissertation citations have a separate OpenAIRE/BASE route and can fall back to fields parsed from the input. Ordinary ambiguous text is returned as ranked candidates through onecite suggest for human review rather than silently emitted as source-resolved output. That process/suggest separation, together with machine-readable JSON/NDJSON, exit codes, and deterministic offline checks, makes OneCite a scriptable building block for agents, batch jobs, and reproducible reviews rather than a GUI library. Source resolution does not establish that a work is authentic, unretracted, or correctly described by upstream metadata.


Features

Feature Description
Candidate Suggestions Search incomplete plain-text references with onecite suggest without promoting them to resolved bibliography output.
Multiple Formats Input .txt/.bib → Output BibTeX or CSL-JSON.
4-stage Pipeline A 4-stage process (parse → identify → enrich → format) with explicit unresolved entries.
Field Completion Fill available fields returned by metadata sources, such as journal, volume, pages, authors, and abstract.
🎓 7+ Citation Types Handles journal articles, conference papers, books, software, datasets, theses, and preprints.
Input-Routed Lookup Uses source-specific routes for Crossref, arXiv, PubMed, Semantic Scholar, Google Books, and others. Not every source is queried for every input.
Many Identifier Types Resolves DOI, PMID, arXiv ID, ISBN, GitHub URL, Zenodo DOI, and DataCite DOI inputs.
Custom Templates YAML-based presets that provide a fallback BibTeX entry type when auto-detection is inconclusive.

🌐 Data Sources

Quick Start

Install and try OneCite in a few steps.

1. Installation

The current public PyPI release is 0.1.1. This working tree documents the unreleased 0.2.0 candidate, so install from the checkout when verifying candidate-only behavior:

# Current stable public release
pip install onecite

# Unreleased 0.2.0 candidate, from the repository checkout
python -m pip install -e .
2. Create an Input File

Create a file named references.txt with your mixed-format references:

# references.txt
# Add blank lines between entries to avoid misidentification

10.1038/nature14539

arXiv:1706.03762

ISBN:9780262035613

https://github.com/tensorflow/tensorflow

10.5281/zenodo.3233118

arXiv:2103.00020

Smith, J. (2020). Neural Architecture Search. PhD Thesis. Stanford University.
3. Run OneCite

Execute the command to process your file and generate a clean .bib output.

onecite process references.txt -o results.bib --quiet
4. View Output

Your results.bib file now contains entries of different types.

@article{LeCun2015Deep,
  doi = "10.1038/nature14539",
  title = "Deep learning",
  author = "LeCun, Yann and Bengio, Yoshua and Hinton, Geoffrey",
  journal = "Nature",
  year = 2015,
  volume = 521,
  number = 7553,
  pages = "436-444",
  publisher = "Springer Science and Business Media LLC",
  url = "https://doi.org/10.1038/nature14539",
  type = "journal-article",
  abstract = "Deep learning allows computational models that are composed of multiple processing layers to learn representations of data with multiple levels of abstraction...",
}
@inproceedings{Vaswani2017Attention,
  arxiv = "1706.03762",
  title = "Attention Is All You Need",
  author = "Vaswani, Ashish and Shazeer, Noam and Parmar, Niki and Uszkoreit, Jakob and Jones, Llion and Gomez, Aidan N. and Kaiser, Lukasz and Polosukhin, Illia",
  year = 2017,
  booktitle = "Advances in Neural Information Processing Systems (NeurIPS)",
  url = "https://arxiv.org/abs/1706.03762",
}
# ... and 5 more entries ...

📖 Advanced Usage

onecite process "10.1038/nature14539"
onecite suggest "Attention is all you need, Vaswani et al., NIPS 2017"
echo "10.1038/nature14539" | onecite process -

Use OneCite directly in your Python scripts.

from onecite import process_references

result = process_references(
    input_content="10.1038/nature14539",
    input_type="txt",
    template_name="journal_article_full",
    output_format="bibtex",
)

print('\n\n'.join(result['results']))

OneCite provides a command-line interface with the following commands and options:

onecite process

The main command for processing references through the OneCite pipeline.

Usage:

onecite process <input_file> [OPTIONS]

Arguments:

  • input_file - Input file path, - for stdin, or a strong identifier/reference string

Options:

Option Short Description Default
--input-type Input format: txt or bib txt
--template Fallback BibTeX entry-type preset when auto-detection is inconclusive journal_article_full
--output-format Output format: bibtex or csl-json for downstream tools that consume CSL-JSON bibtex
--output -o Output file path (default: stdout) -
--quiet -q Suppress verbose logging output False
--json Print a stable JSON envelope instead of BibTeX text False
--ndjson Print newline-delimited JSON events for streaming automation workflows False
--fail-on-unresolved Return exit code 2 when any entry cannot be resolved False

Examples:

# Process a text file
onecite process references.txt -o results.bib

# Process a BibTeX file with auto-detection
onecite process references.bib

# Use stdin
echo "10.1038/nature14539" | onecite process -

# Process a direct string (DOI)
onecite process "10.1038/nature14539"

# Process with custom template
onecite process references.txt --template conference_paper

# Quiet mode for scripts
onecite process references.txt -o results.bib --quiet

# Automation-friendly JSON with unresolved-entry exit-code handling
onecite process references.txt --json --fail-on-unresolved

# Streaming NDJSON for automation
onecite process references.txt --ndjson

# CSL-JSON item output (a development fixture verifies Pandoc 3.10 consumption)
onecite process references.txt --output-format csl-json -o references.json

The development evidence verifies Pandoc 3.10 consumption of representative emitted items. Quarto, standalone citeproc, and reference-manager import workflows are not separately validated in this release.

Report fields. Beyond results and failed_entries, the processing report carries two audit signals:

  • warnings - non-blocking review warnings on resolved entries. Most importantly text_metadata_mismatch: the input text around a resolved DOI appears to describe a different work (the classic hallucinated title+DOI pairing). The DOI remains the resolved identifier and the entry resolves, but it is flagged for review instead of silently emitted as clean output.
  • duplicates - the same work appeared more than once in the batch (bare DOI, PMID, formatted citation). It is emitted once; repeats are reported with the emitted entry's cite key.

Failed entries carry the original input excerpt (raw_text) and a reason code - doi_not_found (no registry record was returned after the implemented fallback), no_strong_identifier (ambiguous text; use onecite suggest), source_error (a source/identity failure surfaced on that route), and more. These codes make important cases distinguishable, but they are not a complete provider trace: some PMID, ISBN, and DataCite request errors currently collapse into the same unresolved reason as a lookup miss.

onecite suggest

Search for candidate matches without producing BibTeX or returning a validation passed status.

onecite suggest "Attention is all you need, Vaswani et al., NIPS 2017" --json

Candidates are for review, not source-resolved citations. Each suggestion discloses the health of the consulted scholarly indexes in a sources list. If a source was rate-limited or errored, the suggestion status becomes candidates_found_incomplete / no_candidates_incomplete - the correct match may be missing from the list entirely, and the candidate list must not be treated as exhaustive. Candidates whose year contradicts the year cited in the query are penalized and flagged with year_conflict. To turn a reviewed candidate into source-resolved BibTeX, resolve its DOI through onecite process "<doi>".

Optional Google Scholar fallback. suggest accepts --google-scholar (requires the optional scholarly package: pip install onecite[scholar]). It is consulted only as a best-effort fallback when CrossRef and Semantic Scholar return nothing. Because it scrapes a service with no public API, it is off by default, may be rate-limited or blocked by a CAPTCHA, and is not guaranteed to be reproducible - it is exposed only on suggest (candidates for human review), never on process.

pip install onecite[scholar]
onecite suggest "some obscure title" --google-scholar
onecite --version

Display the installed OneCite version.

Usage:

onecite --version
onecite version

Alternative command to display version information.

Usage:

onecite version
onecite templates

List the bundled fallback BibTeX templates and the fields they request.

Usage:

onecite templates
onecite templates --json
onecite benchmark

Run a small deterministic regression suite for covered DOI lookup, arXiv lookup, PMID/PubMed lookup, GitHub software URLs, Zenodo/DataCite dataset DOIs, and mixed valid/invalid batches. The command is designed for CI and automation workflows that need a machine-readable pass/fail check; it is not a comprehensive citation-accuracy benchmark.

Usage:

onecite benchmark [OPTIONS]

Options:

Option Description Default
--cases Path to a custom benchmark suite JSON file bundled golden cases
--min-success-rate Minimum covered-case pass rate required for exit code 0 1.0
--json Print the benchmark report as JSON False
--live Use live external APIs instead of bundled offline fixtures False
--anti-hallucination Run the labelled non-fabrication evaluation instead of the golden cases False

Examples:

onecite benchmark
onecite benchmark --json
onecite benchmark --live --json
onecite benchmark --cases my_cases.json --min-success-rate 1.0 --json
onecite benchmark --anti-hallucination
onecite benchmark --anti-hallucination --json

The repository baseline record is stored at benchmarks/leaderboard.json, with reproduction instructions in benchmarks/README.md.

Anti-hallucination evaluation

onecite benchmark --anti-hallucination runs a labelled, fully-offline evaluation of OneCite's core safety property. It resolves real strong identifiers (class A) into source-resolved BibTeX, leaves ambiguous plain-text references (class B) and fabricated, non-existent DOIs (class C - the kind a language model may hallucinate) unresolved rather than emitting a wrong citation, and flags mismatched pairings (class D - a real DOI attached to a different paper's title, the most common hallucinated-citation shape) with a text_metadata_mismatch warning instead of silently emitting them as clean source-resolved output. It reports three metrics:

  • resolution rate - fraction of class-A inputs correctly resolved;
  • non-fabrication rate - fraction of class-B/C inputs correctly left unresolved (not fabricated). 100% means OneCite invented no citations;
  • mismatch detection rate - fraction of class-D inputs resolved with the mismatch warning attached.

A pipeline crash is recorded as error and never counts as correct for any metric - a clean rejection and a broken pipeline are different outcomes.

The dataset lives at src/onecite/benchmarks/anti_hallucination_cases.json, and the evaluation is also available from Python via onecite.run_anti_hallucination_eval().

onecite doctor

Check the local installation health for automation and CI. The doctor command checks package importability, bundled templates, packaged benchmark resources, the repository-contained OneCite Skill, and the offline benchmark regression check.

Usage:

onecite doctor
onecite doctor --json

The JSON output is a stable envelope with schema_version, tool, command, status, environment, summary, and checks fields.

OneCite Skill for Automated Workflows

The repository includes a local skill package at skills/onecite/SKILL.md. It gives automation and contributor workflows a repeatable procedure for reference cleanup, benchmark and doctor checks, and explicit reporting of unresolved entries. The skill is repository-contained and does not install itself into any local tool memory.

Input Type Auto-Detection

When --input-type is not specified, OneCite automatically detects the input type:

  • Files ending with .bib are treated as BibTeX format
  • All other files and strings are treated as plain text
Available Templates

OneCite supports several template presets for different entry types:

  • journal_article_full - Full journal article entry (default)
  • conference_paper - Conference proceedings paper
  • book - Book entry
  • thesis - Thesis/dissertation entry
  • dataset - Dataset entry
  • software - Software/code entry
Exit Codes
  • 0 - Success
  • 1 - Error occurred (invalid input, processing failure, etc.)
  • 2 - One or more entries were unresolved when --fail-on-unresolved was used

For onecite benchmark and onecite doctor, exit code 0 means the configured checks passed and exit code 1 means at least one check failed.

🗺️ Roadmap

  • OneCite Skill - Repository-contained operating guide for local citation-cleanup workflows
  • Benchmarking - Small deterministic regression suite, configurable pass-rate gate, and baseline record
  • Enhanced CLI - Automation-friendly JSON, NDJSON, summaries, and exit codes for reference processing
  • Anti-hallucination evaluation - Labelled offline eval of the non-fabrication property (resolution, non-fabrication, and mismatch detection rates), gated in CI
  • Audit-grade reports - Text/DOI mismatch warnings, failure reason codes with original input, DOI-level deduplication, and suggest source-health disclosure
  • CSL-JSON output - --output-format csl-json emits CSL-JSON items for downstream tools that consume the format; a development fixture verifies Pandoc 3.10 consumption, while Quarto, standalone citeproc, and reference-manager imports are not separately validated
  • Expanded suggest sources - Direct arXiv candidate search covers the CS venues that CrossRef does not index
  • Concurrent batch resolution - Parallel source lookups for large reference lists (currently sequential; latency depends on the selected routes and external services)
  • Larger anti-hallucination dataset - More labelled cases per class and a published live-mode baseline

🤝 Contributing

Contributions are always welcome! Please see CONTRIBUTING.md for development guidelines and instructions on how to submit a pull request.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

OneCite

FAQ

Common questions

Discussion

Questions & comments · 0

Sign In Sign in to leave a comment.