Skip to main content
Glama
deeneskoruzh
wedo911

citeguard

by wedo911
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

citeguard

Los artículos retractados se siguen citando durante años después de su retractación. El fraudulento artículo de 1998 de Andrew Wakefield, que vinculaba la vacuna MMR con el autismo —retractado en 2010—, ha sido citado más de mil veces después de su retractación por investigadores que no tenían una forma sencilla de saberlo. Un estudio de 2026 publicado en JMIR descubrió que las herramientas de IA de libre acceso «no pueden señalar de forma fiable la literatura retractada», justo cuando la investigación y la escritura asistidas por IA se han disparado. citeguard cierra esa brecha: compruebe una cita contra Crossref —gratis, sin clave de API— antes de que llegue a un artículo, un resumen o una reseña.

Tres interfaces, un algoritmo de detección verificado:

Interfaz

Para

Ubicación

Biblioteca de Python + CLI

Escritores académicos, scripts

src/citeguard/

Servidor MCP

Agentes de IA que investigan/escriben

mcp-server/

GitHub Action

CI en un repositorio de laboratorio o revista

action.yml

Por qué se ha construido así

La lógica de detección no se deduce de la documentación: se construyó consultando la API real de Crossref para casos conocidos y leyendo las formas reales de las respuestas, para después escribir pruebas contra las respuestas reales guardadas (confirmadas en tests/fixtures/, compartidas por las implementaciones de Python y TypeScript). Dos artículos reales fijan la verdad base:

  • Wakefield et al., 1998, The Lancet (el artículo sobre la vacuna MMR y el autismo): los metadatos de Crossref del propio editor no tienen ningún dato estructurado de retractación; comprobar solo update-to lo pasaría por alto en silencio. Lo que transmite la señal es un campo updated-by aparte, en el que Crossref ha incorporado retroactivamente la retractación (y una corrección anterior de 2004) desde la propia base de datos de Retraction Watch. Haberse dejado ese campo habría significado omitir el artículo retractado más famoso de la medicina.

  • Mehra et al., 2020, The Lancet (el artículo sobre la COVID/hidroxicloroquina relacionado con Surgisphere): aquí el editor sí adjuntó los datos estructurados directamente, mediante update-to. Un campo distinto, una procedencia distinta, el mismo hecho de fondo.

  • Watson & Crick, 1953, Nature sirve como control limpio en todas las suites de pruebas: un artículo definitivamente real y definitivamente no retractado que nunca debe marcarse.

Así, el verificador analiza tres señales independientes, en este orden: update-to (declarado por el editor), updated-by (a menudo con datos de Retraction Watch, con la que se se detecta lo que los editores pasan por alto) y un fallback por prefijo de título («RETRACTED:», «WITHDRAWN:», etc.) para casos antiguos o sin enlazar que no tienen metadatos estructurados en ninguno de los dos campos. Cada señal se asocia a la gravedad correcta: un título «Expression of Concern» no es lo mismo que una retractación, y las versiones anteriores de este código que que aplanaban esa distinción eran un error que se descubrió al hacer pruebas con títulos reales y no solo sintéticos. Véase src/citeguard/analyze.py para la implementación con todos los comentarios.

Related MCP server: Citation Guard

Inicio rápido

CLI:

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

Aquí el servidor MCP (añada la configuración al cliente, p. ej. .mcp.json):

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

GitHub Action (en el flujo de trabajo de otro repositorio):

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

Lo que esto no es

  • No es una prueba de que el contenido de un artículo sea correcto. Solo comprueba el estado de retractación, no si los hallazgos de un artículo no retractado se sostienen.

  • No es exhaustivo. La heurística del prefijo de título solo detecta las convenciones de editores contra las que se ha probado; un resultado limpio significa «no se ha encontrado ninguna señal conocida», no «la retirada está garantizada».

  • No es una herramienta de expurgo masivo. Está diseñado para el tamaño de una bibliografía real (decenas de citas), con un pequeño retraso fijo entre las llamadas a Crossref y una caché persistente opcional (src/citeguard/cache.py) —buena ciudadanía de API para un servicio público y gratuito, no un robot para escanear millones de DOIs.

Ejecutar las pruebas

# 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

Ambas suites son sin red y deterministas: funcionan contra las respuestas reales de la API almacenadas en el repositorio, no con llamadas en vivo, de modo que son rápidas y no dependen de que Crossref sea accesible. El comportamiento en vivo de extremo a extremo (el CLI real, la herramienta MCP real, entrar en la API real) se verificó de forma manual y aparte durante el desarrollo; la GitHub Action tiene además su propio trabajo de CI (action-smoke-test) que ejecuta la acción real sin en una bibliografía que se sabe retractada y otra que se sabe limpia en cada push. Así, la propia Action —no solo la librería subyacente— queda verificada de forma continua contra la API en vivo.

Contribuciones

Son bienvenidos los nuevos tipos de señales, las convenciones adicionales de títulos de editores y los informes de falsos positivos. Si añade un caso, siempre que sea posible prefiera una integración de Crossref real y citada, en vez de un símbolo sintético: eso es lo que atrapó los dos errores reales que la propia suite de pruebas del proyecto encontró durante el desarrollo (un error de codificación URL en la ruta de petición del DOI y un parser BibTeX que podía engullir una entrada adyacente al analizar un bloque @comment malformado).

Licencia

MIT — consulte 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