Research Scan MCP server

research-scan

Research Scan finds and verifies the 5–10 recent papers that matter most for a research question, project, or decision. Starting from a brief or a single question, it retrieves the literature, expands through citation graphs, measures coverage, verifies every DOI against the live record, and emits evidence objects — while the agent driving it plans the queries, screens the candidates and ranks the shortlist. It is an evidence pipeline for a reasoning agent, not an assistant that answers questions.

Documentation:

The work is split in two, deliberately.

The CLI is deterministic and model-free. It retrieves across OpenAlex, Semantic Scholar and arXiv, walks the citation graph, dedups, counts coverage per criterion, shortlists, verifies every DOI against the live record, applies the selection rules and renders the result. It contains no LLM SDK and makes no judgement about a paper.

The agent supplies the cognition. Planning the queries, scoring each candidate 0–3, writing gap queries when coverage is thin, and reranking the shortlist are all model decisions. The skill packages the rubrics they are made against, as plain Markdown in skills/research-scan/references/; whatever agent hosts it executes them.

Files are the interface between the two halves: the filesystem is the protocol boundary between reasoning and execution, not a storage detail. That is what lets Claude Code, Codex, Cursor or a plain Python loop drive the same chain over the same artifacts.

brief ─▶ [plan queries] ─▶ retrieve ─▶ [screen 0–3] ─▶ expand ─▶ [screen] ─▶ coverage
      ─▶ [gap round, if coverage is thin] ─▶ shortlist ─▶ [rerank] ─▶ verify ─▶ emit

Bracketed steps are the agent's; the rest are CLI stages.

Two things bound the result. A purpose — build, research or orient — decides what a paper has to do to earn a slot. A profile — quick, standard or deep — decides how much the scan costs. Both are described under How it works.

Output is a run directory of validated JSON plus a Markdown brief you can hand to a human, in which every paper's DOI, title, year and first author were checked against the live record.

Install

Python ≥ 3.11 and uv.

uvx research-scan doctor          # run any command without installing
uv tool install research-scan     # or put it on PATH permanently

Configure

configure asks for each credential, shows what is already set, writes ~/.config/research-scan/.env with mode 0600 inside a 0700 directory, and finishes by running doctor.

research-scan configure          # `setup` is an alias for the same command

Keys are read without echo. Re-running is safe: every variable shows its current value masked to the last four characters, Enter keeps it, typing replaces it. Anything already in the file that configure does not ask about — comments included — is left exactly as it was. If stdin is not a terminal it prints the file to write and exits 2 rather than hanging, which is the behaviour you want in a Dockerfile or a provisioning script.

To write the file by hand instead, .env.example in the repo is the template. Process environment beats ~/.config/research-scan/.env, which beats a repo-local ./.env.

Check it works

Shortened. The full README is on GitHub.