How do I use io.github.lonexreb/retractguard?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@io.github.lonexreb/retractguard Scan my reference list for retracted papers" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

io.github.lonexreb/retractguard

by lonexreb

Overview Schema Source Related Servers Score Discussions Admin

Python

Local

CiteGuard

PyPI DOI License: MIT

The free, open, OpenAlex-native watchdog for retracted and problematic citations.

CiteGuard tells you — and keeps telling you — when your references, your authors, or your institution's papers cite research the community has flagged as retracted, corrected, or subject to an expression of concern.

It exists because the existing options each fall short: scite is proprietary and paywalled, RetractoBot had to license Scopus (no open citation database existed at the time), and OpenAlex collapses all editorial status into a single is_retracted boolean that can't tell a retraction from a correction — and has produced false positives in the past.

Now that the Retraction Watch dataset is open (via Crossref) and the OpenAlex citation graph is CC0, CiteGuard can do this fully in the open, for free.

Status: early development. Building the MVP. See GOAL.md for the mission and CLAUDE.md for the build guide.

What it does

Check a reference list. Paste a DOI or upload a .bib file → get a per-reference status: retracted, corrected, expression of concern, hijacked-journal, or clean.
Nuanced status, not a boolean. Every flag carries its source (Retraction Watch / OpenAlex / Crossref), an evidence link, a date, and a confidence note. When sources disagree, CiteGuard surfaces the conflict instead of silently guessing.
Watch an institution. Point it at a ROR ID → get a digest when any of that institution's works cites (or becomes) a newly-flagged paper.
Use it from an AI agent. An MCP server exposes the same logic as tools (check_references, get_editorial_status, watch_institution) for Claude, Cursor, and any MCP-compatible client.

Related MCP server: article-mcp

Why it's trustworthy

Integrity tooling can do real harm if it's wrong — a false "retracted" flag damages a real author. CiteGuard is conservative by design: it corroborates before flagging, prefers the documented editorial notice, and marks a work UNKNOWN rather than guess. Every core capability ships with a published eval reporting precision and recall on a gold set.

Who it's for

Research-integrity officers and journal editors screening submissions
Academic librarians at OpenAlex-adopting institutions
Systematic reviewers (one retracted included study can invalidate a review)
Developers and meta-scientists building on the MCP server
Authors checking their own bibliography before submission

Architecture

One core, two surfaces.

                 ┌─────────────────────────────┐
   OpenAlex ─────▶                             │
   (CC0 graph)   │   editorial-status model    │──▶  MCP server
                 │   + resolution logic        │      (check_references,
   Retraction ──▶│   (conservative)            │       get_editorial_status,
   Watch (open)  │                             │       watch_institution)
                 │                             │──▶  reference-list checker
   Crossref ─────▶                             │      (DOI / .bib → statuses,
   (DOI norm.)   └─────────────────────────────┘       thin web UI)

Repository layout:

src/citeguard/
  openalex.py         # keyed, rate-aware, ID-lookup-first OpenAlex client
  retractionwatch.py  # ingest + normalize the Retraction Watch dump
  status.py           # the EditorialStatus model + resolution logic (core)
  checker.py          # reference-list checker (DOI / .bib -> statuses)
  mcp_server.py       # MCP server exposing the three tools
tests/                # pytest unit + functional tests
evals/                # gold sets + precision/recall harness
data/                 # local RW dump + cached lookups (gitignored)

Design constraints (important)

Free-tier-aware. OpenAlex API keys are required (since Feb 13, 2026); the free tier is small and search costs ~10× a record lookup. CiteGuard resolves to IDs first and looks up by ID; bulk work uses the free monthly snapshot, and the live API is reserved for incremental checks.
Open and reproducible. CC0 ethos, with proper attribution to Retraction Watch and OpenAlex, thorough docs, and a Zenodo DOI.

Getting started (dev)

Requires Python 3.11+ and uv.

uv sync                                   # install dependencies
export OPENALEX_API_KEY=...               # your OpenAlex key
export CITEGUARD_MAILTO=you@example.org   # polite-pool contact

uv run pytest                             # run tests
uv run python -m evals.run                # run the eval harness (precision/recall)
uv run python -m citeguard.mcp_server     # launch the MCP server locally

Connect it as an MCP server

CiteGuard exposes get_editorial_status, check_references, and watch_institution to any MCP client. After pip install retractguard (or uv tool install retractguard), the retractguard-mcp command launches the stdio server.

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "retractguard": {
      "command": "retractguard-mcp",
      "env": {
        "OPENALEX_API_KEY": "your-key",
        "CITEGUARD_MAILTO": "you@example.org"
      }
    }
  }
}

Cursor / other clients — point them at the same retractguard-mcp command (stdio transport). Running from a checkout instead of an install? Use "command": "uv", "args": ["run", "retractguard-mcp"] with "cwd" set to the repo.

On first call the server downloads the Retraction Watch dump (~65 MB, free) into CITEGUARD_DATA_DIR (default ./data). Editorial-notice lookups (Retraction Watch, Crossref) need no key; OpenAlex corroboration and watch_institution do.

The web checker

A thin web UI for people who don't live in an editor — paste DOIs or drop a .bib file, get a per-reference status table.

retractguard-web            # then open http://127.0.0.1:8000
# or from a checkout: uv run python -m citeguard.web

Add Accept: application/json to POST /check to get the results as JSON instead of a table. It reuses the same conservative resolution logic as the MCP server — no separate code path, no separate trust model.

Roadmap (MVP)

status.py — the normalized editorial-status model (foundation)
retractionwatch.py — ingest + normalize the Retraction Watch dump
openalex.py — keyed, ID-first client
checker.py — DOI / .bib → statuses
mcp_server.py — expose the three tools
evals/ — gold set + precision/recall harness (running from step 2 onward)

Credits & data

OpenAlex — CC0 scholarly metadata and citation graph.
Retraction Watch — retraction database, made openly available via Crossref.
Crossref — DOI infrastructure.

CiteGuard is independent and not affiliated with these projects; it builds on their open data with gratitude.

License

MIT (see LICENSE) — permissive and maximally reusable, in keeping with the open-science ethos in GOAL.md.

The code is CiteGuard's. The data it builds on is not and carries its own terms: Retraction Watch (via Crossref) and OpenAlex/Crossref metadata. CiteGuard redistributes only a tiny evaluation extract (see evals/fixtures/ATTRIBUTION.md); anything at scale should be fetched from the upstream sources under their licenses.

Available Tools

3 tools

check_referencesA

Check a reference list. Provide exactly one of: dois (list of DOIs), bibtex (a .bib file's text), or paper_doi (a paper's DOI — its cited references are fetched from OpenAlex and checked).

ParametersJSON Schema

Name	Required	Description	Default
`dois`	No
`bibtex`	No
`paper_doi`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.3/5.0

Behavior3/5

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

With no annotations, the description carries the full transparency burden. It discloses that `paper_doi` causes references to be fetched from OpenAlex and checked, which is useful behavior. However, it does not mention potential network dependencies, error conditions, read-only nature, or what 'check' entails beyond the existence of an output schema.

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 two sentences with no redundant information. It front-loads the core action ('Check a reference list') and then compactly enumerates the exact input options without elaboration.

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

Completeness4/5

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

The description adequately covers the tool's purpose and input modes, and an output schema exists, so return values do not need to be described. It could be more complete with an explicit note about what 'checked' means or typical use cases, but for a three-parameter tool with clear input constraints, it is sufficiently complete.

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

Parameters5/5

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

Schema coverage is 0%, so the description is the sole source of parameter meaning. It fully defines each parameter: `dois` as a list of DOIs, `bibtex` as a .bib file's text, and `paper_doi` as a paper DOI whose cited references are processed. This adds complete semantic value beyond the bare schema.

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 clearly states the action ('Check a reference list') and the resource ('reference list'). It distinguishes the tool from siblings like get_editorial_status and watch_institution by focusing on reference checking, and further specifies the three accepted input modes.

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?

The description explicitly instructs to provide exactly one of `dois`, `bibtex`, or `paper_doi`, which is essential usage guidance. It also explains the special behavior for `paper_doi` (OpenAlex fetch). It does not explicitly say when to prefer this tool over siblings, but the sibling purposes are clearly different, so this is a minor gap.

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

get_editorial_statusA

Editorial status of one work (retracted / corrected / expression of concern / reinstated / hijacked journal / none / unknown), with source, evidence URL, date, confidence, and any source conflicts.

ParametersJSON Schema

Name	Required	Description	Default
`doi`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.3/5.0

Behavior4/5

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

With no annotations provided, the description carries the full burden. It discloses the output structure (source, evidence URL, date, confidence, conflicts) and possible status values, giving agents a clear picture of behavior. It does not mention error handling or authorization, but for a read-only lookup this is sufficient.

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?

One sentence that is front-loaded with the core purpose, followed by specific statuses and result fields. No wasted words or redundancy.

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?

Given the tool's simplicity (one parameter) and the presence of an output schema, the description is complete enough. It covers the key aspects: purpose, possible outcomes, and returned fields, without over-explaining.

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?

The schema has a single 'doi' parameter with no description. The tool description only says 'one work', implying the DOI identifies the work, but does not provide format, examples, or additional guidance. With schema coverage at 0%, the description only partially compensates.

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 clearly states the tool retrieves the editorial status of a single work, listing specific status values (retracted, corrected, etc.). This distinguishes it from sibling tools like check_references and watch_institution, which serve different purposes.

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?

The description implies when to use (when you need editorial status of a work) but does not explicitly state exclusions or alternatives. The scope is clear, but no direct comparison to sibling tools is provided.

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

watch_institutionA

Scan an institution's works (by ROR ID, e.g. https://ror.org/02y3ad647) for papers that are flagged or that cite flagged papers. Repeat calls report only NEW flags (state kept locally). since is an optional YYYY-MM-DD publication-date floor — set it for large institutions.

ParametersJSON Schema

Name	Required	Description	Default
`ror`	Yes
`since`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.9/5.0

Behavior4/5

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

With no annotations, the description carries the transparency burden and does well by disclosing the incremental behavior (only NEW flags, local state) and the `since` floor. It does not address output format or rate limits, but the output schema covers return values.

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?

Two sentences deliver purpose, example, behavioral note, and parameter guidance without redundancy. Every sentence earns its place.

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

Completeness4/5

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

For a two-parameter tool with an output schema and no annotations, the description covers the core scanning purpose, incremental behavior, and parameter hints. It lacks alternative-tool guidance but is otherwise complete.

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

Parameters4/5

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

Schema description coverage is 0%, but the description compensates by explaining `since` as a YYYY-MM-DD publication-date floor and providing a concrete example for `ror`. Both parameters receive meaningful context beyond schema fields.

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

Purpose4/5

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

The description clearly states the tool scans an institution's works by ROR ID and flags papers or papers citing flagged papers, using a specific verb and resource. It does not explicitly differentiate from sibling tools like check_references, so it misses the top score.

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

Usage Guidelines3/5

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

The phrase 'Repeat calls report only NEW flags' implies a monitoring use case, and the `since` parameter guidance is included. However, there is no explicit statement of when to use this tool versus alternatives such as check_references.

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.

3 tool updatesv0.1.2Aug 7, 2026
- First observedcheck_references
- First observedget_editorial_status
- First observedwatch_institution

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Scored 2026-08-07 09:00 across 3 tools

Disambiguation5/5

Each tool targets a distinct workflow: get_editorial_status checks a single work, check_references evaluates a reference list, and watch_institution scans an entire institution. There is no meaningful overlap between them.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (get_, check_, watch_), making the API predictable and easy to navigate.

Tool Count4/5

With only 3 tools, the server is lean but focused. The count is slightly low for a broad domain, but each tool addresses a core need (single-work status, reference-list checking, institutional monitoring) without feeling trivial.

Completeness4/5

The toolset covers the primary workflows for retraction monitoring: checking a work, a reference list, and an institution's flagged/citing papers. Minor gaps exist (e.g., no direct search across all retracted works), but the core lifecycle is well represented.

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

openalex A
io.github.pipeworx-io
OpenAlex MCP — wraps the OpenAlex API (scholarly works, free, no auth)
Search Research & Data Open Data
362
Scholar Sidekick A
io.github.mlava
Catch AI-fabricated citations (real DOI + fake title). Retraction, open-access, 10,000+ CSL styles.
Research & Data Open Data
718
altmetric-mcpOAuth
com.altmetric.mcp
MCP server for Altmetric APIs - track research attention across news, policy, social media, and more
Research & Data Social Media
27
crossref A
io.github.pipeworx-io
Crossref MCP — wraps the Crossref REST API (academic papers, free, no auth)
Search Research & Data Open Data
342

Related MCP Servers

MCP Refchecker
AI & Machine Learning Research & Data Search
JonasBaath
A
license
A
quality
D
maintenance
MCP server for verifying academic citations via Semantic Scholar, OpenAlex, and CrossRef.
Updated 5 months ago (2026-04-23 22:06 UTC)
1
MIT
article-mcp
Search Research & Data
fangfuzha
A
license
A
quality
D
maintenance
Enables multi-source literature search, full-text retrieval, reference analysis, and journal quality assessment across Europe PMC, PubMed, arXiv, CrossRef, OpenAlex, and EasyScholar via the MCP protocol.
Updated 19 days ago (2026-08-23 05:22 UTC)
5
21
1
MIT
Semantic Scholar MCP Server
Research & Data Search Open Data
HenryKautz
F
license
A
quality
D
maintenance
Enables searching and retrieving academic papers, authors, citations, and recommendations from Semantic Scholar via MCP.
Updated 7 months ago (2026-02-15 22:58 UTC)
9
-
citeguard
Research & Data Open Data
wedo911
A
license
Not graded
quality
A
maintenance
Checks whether a citation has been retracted, corrected, or flagged with an expression of concern by querying Crossref — including retractions that Crossref backfills from the Retraction Watch database, which publishers often never record in their own metadata. Lets an AI agent verify a DOI, or every DOI in a reference list, before using it in research or writing.
Updated 16 days ago (2026-08-26 16:24 UTC)
1
MIT