Skip to main content
Glama
deeneskoruzh
wedo911

citeguard

by wedo911
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

citeguard

Zurückgezogene Beiträge werden noch Jahre nach ihrer Zurücknahme zitiert. Andrew Wakefields betrügerischer Artikel von 1998, der die MMR-Impfung mit Autismus in Verbindung brachte — 2010 zurückgezogen —, wurde seither über tausendmal seit der Zurücknahme zitiert, und das von Forschenden, die kaum eine einfache Möglichkeit hatten, das zu erkennen. Eine JMIR-Studie aus dem Jahr 2026 ergab, dass frei verfügbare KI-Werkzeuge „retracted literature nicht zuverlässig erkennen können“, ausgerechnet in dem Moment, in dem KI-gestützte und Forschung und Schreiben explodiert. citeguard überbrückt dieses Lücke: eine Quellenangabe wird gegen Crossref — kostenlos, ohne API-Schlüssel — geprüft, bevor sie in ein Paper, eine Zusammenfassung oder ein Review einfließt.

Drei Anwendungsflächen, ein verifizierter Erkennungsalgorithmus:

Zugang

Anwendungsfall

Ort (Quellcode)

Python-Bibliothek + CLI

wissenschaftliche Schreibende, Skripte

src/citeguard/

MCP server

KI-Agenten für Recherche/Schreiben

mcp-server/

GitHub Action

CI in einem Lab- oder das Journal-Repo

action.yml

Warum das so aufgebaut ist

Die Erkennungslogik ist nicht aus Dokumentationen abgeleitet — sie wurde durch Anfragen an die echte Crossref-API für bekannte Fälle und das Lesen der tatsächlichen Antwortstrukturen erfunden. Anschließend wurden Tests gegen die gespeicherten echten Antworten geschrieben (committed in tests/fixtures/, gemeinschaftlich von der Python- und spätere TypeScript-Implementierung). Zwei echte Paper fungieren als Referenzfall der „Ground Truth“:

  • Wakefield et al., 1998, The Lancet (das MMR-Autismus-Paper): Die eigene Crossref-Metadaten des Verlags enthalten keinerlei strukturierte Rückzugsdaten — eine update-to-Prüfung allein würde das stillschweigend übersehen. Das eigentliche Signal steckt in einem separaten updated-by-Feld, in dem Crossref die Rücknahme (zusammen mit einer frühen 2004-Korrektur) aus der Retraction Watch database selbst nachgetragen hat. Dieses Feld zu ignorieren, hieße, das bedeutendste zurückgezogene Paper der Medizin zu ver passe.

  • Mehra et al., 2020, The Lancet (das Surgisphere-bezogene COVID-19/Hydroxychloroquine-Papper): Hier hat der Verlag strukturierte Daten direkt über update-to in den Datenerecord eingepflegt. Ein anderes Feld, eine andere Herkunft, die gleiche Inhaltliche Tatsache.

  • Watson & Crick, 1953, Nature wird in jedem Testsuite eingesetzt – eine eindeutig echte, definitiv nicht zurückgezogene Veröffentlichung, die niemals markiert werden darf.

The research follows daher drei unabhängige Signale in gegebener Reihenfolge: update-to (vom Verlag gemeldet), updated-by (oft aus der Retraction-Watch-Datenbank, erwischt, was Verlage auslassen) und eine psatzkategorie per Titelpräfix („RETRACTED:“, „WITHDRAWN:“ usw.) für ältere/unverbundene Fälle ohne strukturierte Metadaten in lie at one will both Feldern. Each Signal bekommt eine angemessene Schwere zugewiesen — ein Titel beginnend mit „Expression of Concern“ ist nicht identisch a retraction, and older Versionen, die diesen Unterschied eingeebnet haben, sind selbst als Bug enttarnt worden durch Testen an realen Titeln, nicht nur an synthetisch erzeugten. Siehe src/citeguard/analyze.py für die unter: kommentierte Implementierung.

Related MCP server: Citation Guard

Schnellstart

CLI:

pip install -e .
citeguard doi 10.1016/S0140-6736(97)11096-0
citeguard file references.bib --fail-on retracted   # for CI, see below

MCP server (tragen Sie ihn in die Konfiguration Ihres Clients ein, z. B. .mcp.json):

{ "mcpServers": { "citeguard": { "command": "node", "args": ["/path/to/citeguard/mcp-server/dist/index.js"] } } }

GitHub Action (in einem Workflow eines anderen Repos):

- uses: wedo911/citeguard@main
  with:
    path: references.bib
    fail-on: concern   # never | retracted | concern | corrected

Was das nicht ist

  • Kein Beweis für die inhaltliche Korrektheit eines Papers. Sie prüft nur den Rückzugsstatus, nicht ob die Ergebnisse eines nicht zurückgezogenen Papers stichhaltig sind.

  • Nicht vollständig. Die Titelpräfix-Heuristik erkennt nur Verlagskonventionen, gegen die sie getestet wurde; ein sauberes Ergebnis heißt „kein bekanntes Signal gefunden“ und nicht „garantiert nie zurückgezogen“.

  • Kein Massen-abrufwerkzeug. Es ist gebaut für die Größe eines echten Literaturverzeichnisses (einige Dutzend Zitate), mit einer kleinen festen Verzögerung zwischen Crossref-Anfragen und einem optionalen persistenten Cache (src/citeguard/cache.py) — ein fairer APInnutzungsverhalten gegenüber einem kostenlosen öffentlichen Service, und kein Instrument zum Scannen von Millionen von DOIs.

Tests ausführen

# Python (55 tests, including against the real fixtures above)
pip install -e ".[dev]" && pytest -v

# MCP server (17 tests against the same real fixtures)
cd mcp-server && npm install && npm run build && npm test

Beide Testumgebungen sind netzwerkfrei und deterministisch — sie laufen gegen die gespeicherten echten API-Antworten statt gegen Live-Calls die Langsam und hängen nicht davon ab, dass Crossref erreichbar ist. Das echte Ende-zu Ende-Verhalten (das tatsächliche CLI, das echte MCP-Tool, das Ansprechen der realen API) wurde während der Entwicklung manuell und separat verifiziert. Die GitHub Action hat zusätzlich einen eigenen CI-Job (action-smoke-test), der die reale Composite Action bei jedem Push gegen eine bekannte zurückgezogene und eine bekannte saubere Literaturliste ausführt; damit wird die Action selbst — nicht nur die zugrunde liegende Bibliothek — kontinuierlich mit der Live-API getestet.

Mitwirken

Neue Signaltypen, zusätzliche Verlags-Titelkonventionen und Fehlermeldungen zu False-Positives sind gern willkommen. Wenn Sie einen neuen Fall hinzufügen, bevorzugen Sie möglichst eine echtes, ausführlich zitierten Crossref-Fixture vor einer synthetischen — genau das hat zwei echte Bugs entdeckt, die die erwartete Testsuite der Projekts während der Entwicklung gefunden hat (einen URL-Encoding-Bug im DOI-Anfragepfad und einen BibTeX-Parser, der beim Verarbeiten eines fehlerhaften @comment-Blocks den benachbarten Eintrag verschlucken konnte).

Lizenz

MIT — siehe LICENSE.

Available Tools

2 tools
check_citationCheck a Citation for RetractionA
Read-onlyIdempotent

Check a single DOI against Crossref for retraction, correction, or expression-of-concern status. Use this before citing a paper in a document, summary, or literature review -- retracted papers (including fraudulent or debunked ones) continue to be cited for years after retraction, often because whoever is citing them has no easy way to check. This tool checks three independent signal sources: publisher-asserted updates, Crossref's ingested Retraction Watch data (which catches many retractions the publisher's own metadata misses), and a title-prefix fallback ("RETRACTED:", etc.) for older or unlinked cases.

Args:

Returns: For JSON format: { "doi": string, "verdict": "retracted" | "concern" | "corrected" | "clean" | "not_found" | "error", "title": string | null, "signals": [ { "type": string, "source": string, "label": string | null, "noticeDoi": string | null, "date": string | null } ], "error": string | null }

Examples:

  • Use when: about to cite a paper in a summary, report, or literature review -- check it first

  • Use when: reviewing someone else's bibliography for outdated or unreliable sources

  • Don't use when: you need to verify a claim's accuracy generally -- this only checks retraction status, not whether the paper's content is correct

Error Handling:

  • A DOI Crossref doesn't recognize returns verdict "not_found", not an error -- it may still be a real paper Crossref just doesn't index (e.g. some preprints), not necessarily an invalid citation.

ParametersJSON Schema
NameRequiredDescriptionDefault
doiYesA DOI, e.g. "10.1016/S0140-6736(97)11096-0" (with or without a "https://doi.org/" prefix).

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior, and the description adds substantial context beyond that: three independent signal sources, Retraction Watch ingestion, title-prefix fallback, and the important distinction that an unrecognized DOI returns 'not_found' rather than 'error'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the tool's purpose and well-organized into usage, signal sources, arguments, returns, examples, and error handling. The message is somewhat long for a one-parameter tool, with mild motivational padding about retracted papers continuing to be cited, but the structure is clear and every section is operationally useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete given the tool's complexity and missing output schema: it documents the return shape, verdict enum values, signal structure, and key error-handling behavior. Annotations cover the safety profile, so no critical behavioral or call-routing information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single DOI parameter, and the description repeats the same prefix flexibility already documented in the schema. No additional syntax, constraints, or examples beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

State a specific verb and resource ('Check a single DOI against Crossref') and names the exact statuses checked. The word 'single' distinguishes it from the sibling batch tool check_citations without needing to open either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use guidance ('before citing a paper') and a clear when-not-to-use case ('verify a claim's accuracy generally'). It does not explicitly name the sibling check_citations as the alternative for multiple DOIs, so the alternative routing is only implied by the singular scope.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

check_citationsCheck All Citations in a Block of TextA
Read-onlyIdempotent

Extract every DOI found in a block of text (a reference list, a paper draft, an exported bibliography) and check each one for retraction/correction/expression-of-concern status via Crossref. Use this to sanity-check a whole reference list at once before finalizing a document, rather than checking citations one at a time.

Finds DOIs in any form: bare ("10.1016/S0140-6736(97)11096-0"), as a doi.org URL, or embedded in a formatted citation. Up to 50 unique DOIs are checked per call; if more are found, only the first 50 (in order of first appearance) are checked and the response says so.

Args:

  • text (string, 1-200000 chars): the text to scan.

Returns: For JSON format: { "totalFound": number, "checked": number, "truncated": boolean, "results": [ { "doi": string, "verdict": string, "title": string|null, "signals": [...], "error": string|null } ] }

Examples:

  • Use when: finishing a literature review or research summary -- paste the whole reference list to check it in one call

  • Don't use when: checking just one citation you already have the DOI for -- use check_citation instead, it's simpler

Error Handling:

  • Returns an error if text is empty or exceeds 200000 characters. Text with no DOI-shaped substrings returns totalFound: 0, not an error.

ParametersJSON Schema
NameRequiredDescriptionDefault
textYesFree text to scan for DOIs -- a reference list, a paper draft with inline citations, or a bibliography exported as plain text.

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Although annotations already cover readOnly, idempotent, non-destructive, and openWorld behavior, the description adds substantial behavioral detail beyond them: Crossref lookup semantics, support for bare/doi.org/formatted DOIs, a 50-unique-DOI cap with first-in-order truncation, and explicit error conditions for empty/overlong text and no-DOI text.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and primary use, then organized into Args, Returns, Examples, and Error Handling. Every section earns its place by explaining batch behavior, output shape, or edge cases that an agent otherwise could not infer.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter tool with no output schema, the description supplies the missing return shape, truncation behavior, and error handling. Combined with annotations and a fully documented schema, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single text parameter is already documented in the schema with min/max length and examples. The description's Args section largely restates the schema, so it does not materially deepen parameter semantics beyond what is already structured.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb+resource: extract every DOI in a block of text and check each for retraction/correction/expression-of-concern status via Crossref. It explicitly distinguishes this batch tool from the sibling check_citation by contrasting whole-list checking with one-at-a-time checking.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states exactly when to use this tool ('finishing a literature review or research summary -- paste the whole reference list') and when not to ('checking just one citation you already have the DOI for -- use check_citation instead'). The alternative tool is named and the condition for selecting it is stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.2
    • First observedcheck_citation
    • First observedcheck_citations
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 2 tools

Disambiguation4/5

check_citations (bulk scan of text) and check_citation (single DOI) have overlapping purposes, and the near-identical singular/plural names invite misselection. However, each description explicitly cross-references the other with 'use X instead' guidance, so an agent can reliably choose the right one.

Naming Consistency4/5

Both tools use consistent snake_case with a clear verb_noun shape, and the singular/plural convention neatly signals single vs. bulk behavior. The only downside is that the two names differ by a single character, which is a mild collision risk.

Tool Count4/5

Two tools is on the thin side, but the domain (checking retraction status of DOIs) is genuinely narrow and the single/bulk split is the one meaningful axis of variation. Nothing feels gratuitous, though a third tool would be hard to justify.

Completeness4/5

The surface covers the core lifecycle: check one DOI, check many DOIs in a block of text, with defined verdicts and error handling. A minor gap is the absence of any way to resolve a citation lacking a DOI (e.g. by title/author) into a checkable identifier.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • CiteStamp MCP server by citestamp

    CiteStamp MCP serverofficial

    citestamp
    A
    license
    Not graded
    quality
    B
    maintenance
    Ground citations before your agent emits them by checking references against public scholarly registries and flagging hallucinated or retracted ones.
    MIT

  • io.github.lonexreb/retractguar

    lonexreb
    A
    license
    A
    quality
    C
    maintenance
    Provides MCP tools to check reference lists for retracted or problematic citations, retrieve nuanced editorial statuses with evidence, and monitor institutions for newly flagged papers using open data from OpenAlex, Retraction Watch, and Crossref.
    3
    27 PyPI
    MIT