SPB Git

Repository Public Research preview

README.md 6.1 KB 126 lines markdown

1# scholarly-mcp23An MCP server that lets an agent **look references up instead of recalling them**: search the4scholarly record, check that a citation is real and correctly described, audit a whole5bibliography, and spot retracted work. It reads four public services — Crossref, OpenAlex, arXiv6and doi.org — and needs no account.78The rule it enforces: a citation is verified when its DOI resolves **and** the registered title,9first author and year agree with what is cited. A DOI that merely exists verifies nothing; a real10DOI pasted onto the wrong paper is reported as a mismatch.1112## Tools1314| Tool | What it does | Services |15|---|---|---|16| `verify_doi` | DOI resolves and the record matches the citation | Crossref, doi.org, arXiv |17| `verify_bibliography` | One status per entry of a `.bib` file, BibTeX text or reference list | Crossref, doi.org, arXiv |18| `resolve_reference` | Finds the record of a reference without DOI, or says there is none | Crossref, arXiv |19| `check_retractions` | Retractions, expressions of concern, corrections for up to 200 DOIs | Crossref, OpenAlex |20| `search_works` | Search by text, title, author, year, type | Crossref (default) or OpenAlex |21| `get_work` | Registered metadata of one work | Crossref, doi.org, arXiv, OpenAlex |22| `search_arxiv` | Search or look up preprints | arXiv |23| `get_citations` | Works citing a work | OpenAlex |24| `get_references` | What a work cites | Crossref, OpenAlex |25| `related_works` | Works related by shared concepts | OpenAlex |26| `author_works` | Works of an author by ORCID, id or name | OpenAlex |27| `get_open_access` | Legal open copies of a work | OpenAlex, arXiv |28| `format_citation` | APA, Chicago, MLA, BibTeX, RIS, CSL-JSON from registry metadata | as `get_work` |29| `bibtex_from_doi` | BibTeX from the registration agency, or generated | doi.org, Crossref |30| `parse_bibtex` | Offline: entries, missing DOIs, duplicate keys, syntax errors | none |31| `scholarly_status` | Configuration, counters, OpenAlex budget left | none |3233Every tool is read-only. Statuses returned by the verification tools: `verified`,34`doi_missing_found`, `metadata_mismatch`, `doi_not_found`, `doi_invalid`, `ambiguous`,35`not_found`, `retracted`, `unverifiable`, `error`. A registry outage is reported as `error`,36never as `not_found`.3738## Install3940Node.js 20 or newer.4142```bash43npm install44node server.mjs        # speaks MCP on stdio45```4647Claude Code:4849```bash50claude mcp add scholarly -- node /absolute/path/to/scholarly-mcp/server.mjs51```5253Any MCP client:5455```json56{ "mcpServers": { "scholarly": { "command": "node", "args": ["/absolute/path/to/scholarly-mcp/server.mjs"], "env": { "SCHOLARLY_ROOT": "/path/to/your/papers" } } } }57```5859## Configuration6061| Variable | Default | Effect |62|---|---|---|63| `SCHOLARLY_ROOT` | working directory | Only directory bibliography files may be read from |64| `OPENALEX_API_KEY` | unset | Your own OpenAlex key, for a larger allowance on OpenAlex-backed tools |65| `SCHOLARLY_MAILTO` | unset | Contact address sent to Crossref and OpenAlex ("polite pool") |66| `SCHOLARLY_TIMEOUT_MS` | 20000 | Per-request timeout |6768## What it sends, and what it does not6970- Each request carries the client name `scholarly-mcp/1.0` and the query itself (a DOI, a title,71  an author name). Nothing about the user, the machine or the project is added.72- No contact address is sent unless you set `SCHOLARLY_MAILTO`. It then goes to Crossref and73  OpenAlex only.74- `OPENALEX_API_KEY` is sent to OpenAlex only and never appears in tool output.75- Files: only `.bib`, `.bibtex`, `.txt` and `.md` inside `SCHOLARLY_ROOT`, 5 MB at most,76  symbolic links resolved before the check. The server writes nothing.77- Registry text (titles, abstracts, notices) is returned as data with a notice that it is78  untrusted. That reduces the risk of prompt injection through a crafted title; it does not79  remove it.8081## Limits you should know8283- **OpenAlex without a key** shares a small daily allowance among everyone behind the same IP84  address (0.10 USD on 2026-11-10: roughly a hundred list calls). When it is spent, the85  OpenAlex-backed tools return `rate_limited`. Verification tools do not depend on OpenAlex.86- **Coverage.** Crossref and arXiv do not list most books, theses, reports and working papers,87  nor many regional journals. `not_found` means "not in these registries".88- **Heuristics.** Matching rests on title similarity (Sørensen-Dice on normalised words, 0.9 to89  match, 0.75 to be "close"), family-name comparison and year. Thresholds are in90  `lib/match.mjs`; every verdict includes the compared values.91- **Registry errors.** Crossref metadata is sometimes wrong. A mismatch says the citation and92  the registry disagree, not which one is right.93- **Retractions** come from Crossref update notices and the OpenAlex flag. Both lag and both94  have gaps: `no_notice` is not a guarantee.95- **Open access.** `get_open_access` reports authorised copies only.96- **arXiv** allows one request every three seconds; the server queues accordingly, so a97  bibliography with many arXiv-only entries is slow.98- It cannot check that a cited work supports the claim citing it.99100## Tests101102```bash103npm test             # 17 offline tests, recorded registry answers, no network104npm run test:live    # 10 tests against the real services through the MCP protocol105```106107Live tests need the network and no account. The OpenAlex test skips when the key-less budget is108exhausted.109110Checked once by hand on 2026-11-10 but not in the automated suite, to spare the shared OpenAlex111budget: `related_works`, `author_works` (by ORCID and by name), `search_works` with source112`openalex`, `get_references` with source `openalex`, `get_open_access` for a journal article and113a `pmid:` lookup. Each returned a plausible answer; a later change in OpenAlex would not be caught114by `npm run test:live`.115116Not tested: bibliographies above a few dozen entries in one call; references in non-Latin117scripts; BibLaTeX constructs such as `crossref` inheritance; behaviour under a real OpenAlex118budget exhaustion (the `rate_limited` path is tested with a simulated HTTP 429 only).119120## Companion skill121122`@spboucher/citation-verification` packages the same engine as a command-line tool with the123rules for reading its results.124125MIT licence.126
Files main
Menu

Theme