Skip to main content
Glama
acatome-quest-mcp

acatome-quest-mcp

by retospect

acatome-quest-mcp

Paper-request MCP for scientific papers. The missing piece between precis-mcp (navigates what's already in your library) and acatome-extract (ingests PDFs that land in an inbox).

An LLM says "I want this paper" (DOI, arXiv id, title, or free-form citation). Quest:

  1. Checks the store first — no duplicate work if we already have it.

  2. Resolves the metadata via Crossref + Semantic Scholar + arXiv.

  3. Flags misconceptions — broken DOI, DOI↔title mismatch, duplicate of an existing slug, fabrication suspect.

  4. Fetches the PDF from legitimate open-access sources only and drops it into the existing watch inbox, where acatome-extract takes over.

  5. Returns a request id in milliseconds. Slow extraction happens out of band; the MCP call never blocks.

Open access only — by policy

Quest fetches from arXiv, Unpaywall, OpenAlex, Europe PMC, and Semantic Scholar's open-access index only. It does not, will not, and cannot be configured to use Sci-Hub, LibGen, institutional proxies without explicit opt- in, or any other paywall-circumvention mechanism. Failed retrievals yield a needs_user status with the publisher URL, for you to retrieve manually.

Related MCP server: paper-fetch-mcp

Install

pip install acatome-quest-mcp
# or with uv
uv add acatome-quest-mcp

For dedup against a local acatome-store:

pip install 'acatome-quest-mcp[store]'

Four tools

Tool

What it does

submit(ref, *, dry_run=False, source=None, priority=0, created_by=None)

Resolve + optionally queue. Idempotent.

status(id=None, *, filter=None)

Read one or many requests.

update(id, mode, **kwargs)

Mutate. Modes: confirm, repoint, flag, priority, cancel.

submit_file(url?, content_base64?, filename?, request_id?, ref?, created_by?)

Attach a user-supplied PDF (e.g. Discord attachment) to an existing request or create a new one, flip to ingesting.

submit

submit(ref={"doi": "10.1021/jacs.2c01234"})
submit(ref={"title": "Anion exchange membranes for NOx reduction",
            "authors": ["Feng, Z."], "year": 2024})
submit(ref={"raw": "Feng et al. 2024, Adv. Funct. Mater. 34, 2300512"})
submit(ref={"doi": "10.1234/x"}, dry_run=True)      # resolve only, no queue
submit(ref={"doi": "10.1234/x"},
       source={"document": "ch02.tex", "line": 147})

Response:

{
  "id": "9f3b…",
  "status": "found_in_store",
  "resolved": {"doi": "10.1021/jacs.2c01234",
               "title": "…", "authors": ["…"], "year": 2024,
               "ref": "smith2022jacs"},
  "candidates": [],
  "misconceptions": []
}

status

status(id="9f3b…")
status(filter={"status": "needs_user"})
status(filter={"created_by": "asa", "has_misconception": True})
status(filter={"source_document": "ch02.tex"})

update

update(id, mode="confirm", choice=0)            # pick candidates[0]
update(id, mode="repoint", doi="10.1023/A:…")   # user-corrected DOI
update(id, mode="flag", code="retracted",
       evidence="Retraction Watch 2024-08-12")
update(id, mode="priority", priority=5)
update(id, mode="cancel")

submit_file

# User drops a PDF for an already-tracked request (reopens failed / needs_user):
submit_file(url="https://cdn.discordapp.com/…/paper.pdf",
            request_id="7f3a…",
            filename="feng2024.pdf")

# User supplies both a PDF and a DOI in one step (creates the request):
submit_file(url="https://cdn.discordapp.com/…/paper.pdf",
            ref={"doi": "10.1021/jacs.2c01234"},
            created_by="asa")

# Bytes already in memory (no URL to fetch):
submit_file(content_base64="JVBERi0xLjQKJf…",
            request_id="7f3a…")

PDF magic bytes are validated; HTML error pages are rejected. The file is written to the extractor's inbox (~/.acatome/inbox/ by default) and the request flips to ingesting. If the paper's DOI is already in the store, the tool short-circuits to found_in_store without writing anything.

CLI

The acatome-quest binary exposes the same surface as the MCP plus a couple of shell-friendly helpers:

acatome-quest submit 10.1021/jacs.2c01234
acatome-quest status <id>
acatome-quest status --filter status=needs_user
acatome-quest status --filter status=needs_user --count     # just prints "3"
acatome-quest update <id> repoint --doi 10.1023/A:…
acatome-quest submit-file --path ./feng2024.pdf --request-id 7f3a…
acatome-quest submit-file --url https://.../paper.pdf --doi 10.1021/jacs.2c01234
acatome-quest report                                         # markdown worklist
acatome-quest report --document ch04.tex --format markdown   # scoped
acatome-quest runner [--once]
acatome-quest reconcile

report renders a paste-ready markdown document for every request in needs_user, failed, or extract_failed — each entry with citation, DOI/arXiv link, failure reason, misconception evidence, and a concrete suggested action (repoint DOI, drop PDF into ~/.acatome/inbox/, request via interlibrary loan, …). Hand it to a librarian or paste into an ILL form.

Statuses

Status

Meaning

queued

Accepted, not yet fetched

resolving

Metadata lookup in progress (transient)

found_in_store

Dedup hit — slug in resolved.ref

needs_user

Disambiguation or manual fetch required

fetching

Runner has claimed and is downloading

ingesting

PDF in inbox, waiting for acatome-extract watch

ingested

Extraction done, slug in resolved.ref

extract_failed

PDF delivered but extraction failed

failed

All sources exhausted

cancelled

update(mode=cancel) was called

Misconception codes

Code

Severity

Trigger

doi_invalid

major

Crossref 404 or syntactically malformed

doi_truncated

major

404, but doi + digit resolves

doi_title_mismatch

critical

DOI resolves but title fuzz < 60 vs request

title_not_found

critical

No S2/Crossref hit (fabrication suspect)

duplicate_of

minor

Already in store under another slug

retracted

critical

S2 / Retraction Watch flag

preprint_of

info

arXiv preprint of a later journal paper

pdf_mismatch

critical

User-dropped PDF resolved to a different paper than the request it was attached to

Architecture

 agent ──submit()──► acatome-quest-mcp (FastMCP, stdio)
                            │
                            ▼
              cluster.papers.requests (Postgres)
                            │
                            ▼
           acatome-quest-runner (launchd, poll 30 s)
                  │
          fetch: arxiv → unpaywall → …
                  │
                  ▼
          ~/.acatome/inbox/<slug>__<hash>.pdf
                  │
                  ▼
          acatome-extract watch  →  acatome-store
                  ▲
                  └── runner polls by DOI, flips to `ingested`

Configuration

Env var

Default

Description

DATABASE_URL

postgresql://localhost/cluster

Postgres DSN

QUEST_SCHEMA

papers

Schema name for the requests table

ACATOME_INBOX

~/.acatome/inbox

Drop directory watched by acatome-extract

UNPAYWALL_EMAIL

(required at runner start)

Polite-pool contact

ACATOME_CROSSREF_MAILTO

(recommended)

Crossref polite pool

SEMANTIC_SCHOLAR_API_KEY

(optional)

Raises S2 rate limit

QUEST_POLL_INTERVAL

30

Runner tick seconds

QUEST_MAX_CONCURRENT

4

Max parallel fetches

QUEST_INGEST_TIMEOUT

900

Seconds to wait for ingest after PDF drop

QUEST_MAX_OPEN_PER_AGENT

50

Per-created_by cap

Development

uv sync
uv run pytest
uv run ruff check .
uv run mypy src tests

License

GPL-3.0-or-later. See LICENSE.

Available Tools

4 tools
statusA

Read one or many paper requests.

Args: id: A request id (uuid string). If given, filter is ignored. filter: Narrow the list of rows returned. Supported keys: status, created_by, has_misconception (bool), source_document, limit.

Returns: A single card (when id is set) or a list of cards.

Inputs: id, filter. Returns: result

submitA

Submit a paper request. Resolves metadata, checks dedup, queues for fetch.

Args: ref: The paper identifier. Any subset of: {doi, arxiv, pmid, title, authors, year, raw}. raw is a free-form citation string — Quest will try to extract a DOI or arXiv id from it. dry_run: If True, resolve and return candidates but do not persist. source: Provenance — e.g. {"document": "ch02.tex", "line": 147}. priority: Higher = served first by the runner. Default 0. created_by: Agent slug or user id. Used for per-agent rate-limiting.

Returns: The full request record, including resolved metadata, candidates, and misconceptions. Status will be one of: found_in_store (already have it), queued (waiting for runner), needs_user (disambiguation or bad DOI required manual action).

Idempotent: calling submit twice with the same DOI while the first request is still open returns the same request id.

Do not fabricate quotes from a paper whose status is not ingested or found_in_store.

Inputs: ref (required), dry_run, source, priority, +1 more. Returns: object

submit_fileA

Attach a user-supplied PDF to a paper request.

Use this when a user drops a PDF (e.g. a Discord attachment) for a paper that Quest could not fetch automatically, or to pre-load a PDF you already have on disk.

Args: url: A direct HTTP(S) link to the PDF. Must resolve to a fresh file (follow-redirects is enabled, so short-lived Discord CDN URLs work). Mutually exclusive with content_base64. content_base64: Base64-encoded PDF bytes, for agents that already have the file in memory. Prefer url when available so the provenance URL is recorded on the request. filename: Optional filename hint, used when naming the file written to the inbox. Falls back to the request's author/year. request_id: Attach to an existing request (preferred). Reopens failed, extract_failed, or needs_user requests. Refuses to overwrite already-closed or cancelled requests. ref: Create a new request from this reference (same shape as :func:submit) and attach the PDF. Use this when the paper isn't already being tracked. created_by: Agent or user id, used when ref is given.

Returns: The full request record, flipped to ingesting. The background runner reconciles with acatome-store once acatome-extract has done its work.

Exactly one of url / content_base64 is required, and exactly one of request_id / ref.

Inputs: url, content_base64, filename, request_id, +2 more. Returns: object

updateA

Mutate a request. Single verb with an explicit mode (see precis.put for the same pattern).

Modes: confirm: pick one of candidates by index. Requires choice. repoint: replace the DOI (user-corrected) and re-resolve. Requires doi. flag: attach a misconception. Requires code; optional severity, evidence. priority: change the runner priority. Requires priority. cancel: terminate the request.

Inputs: id (required), mode (required), choice, doi, +4 more. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: status for reading, submit for creating, submit_file for attaching PDFs, and update for modifying requests. No overlap exists, and descriptions are detailed enough to prevent confusion.

    Naming Consistency4/5

    Names are lowercase and follow a simple pattern: three verbs (status, submit, update) and one compound verb_noun (submit_file). While not perfectly uniform, the naming is clear and predictable with minor deviations.

    Tool Count4/5

    With 4 tools covering the core operations (create, read, update, attach file), the count is appropriate for the server's focused scope. It is slightly on the lower side but not insufficient.

    Completeness4/5

    The tool set covers the main lifecycle of paper requests: submission, status query, file attachment, and various update modes (including cancel). A minor gap is the lack of an explicit delete tool, but cancel effectively serves that purpose.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server for downloading academic papers from multiple sources using intelligent routing and year-aware priority selection. It enables users to retrieve metadata and download single or batch PDFs by DOI or URL.
      3
      21 PyPI
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Comprehensive MCP server for academic research workflows, enabling paper searching across multiple sources, manuscript processing with citation placeholders, search caching, and citation export.
      11
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for downloading academic papers from DOI or title, resolving references, and generating citations. Supports batch downloads, multiple mirrors, and optional Unpaywall integration.
      11
      2
      MIT