scholar-sidekick-mcp

# Scholar Sidekick MCP Server

[MCP](https://modelcontextprotocol.io) server for [Scholar Sidekick](https://scholar-sidekick.com) — catch AI-fabricated citations, one at a time or across a whole bibliography, from any AI assistant. It also checks retraction and open-access status, and resolves any scholarly identifier (DOI, PMID, PMCID, ISBN, arXiv, ISSN, NASA ADS bibcode, WHO IRIS URL) into 10,000+ CSL styles or nine export formats.

## Highlights

- **Citation-fabrication detection** — `verifyCitation` cross-checks a claimed citation against the resolved record at its identifier, detecting the dominant AI-driven fabrication pattern documented by [Topaz et al. (Lancet 2026)](https://doi.org/10.1016/S0140-6736(26)00603-3) — real DOI + invented title — that simple identifier resolution cannot catch. Long-form explainer at [scholar-sidekick.com/citation-integrity](https://scholar-sidekick.com/citation-integrity).
- **Whole-bibliography audit** — `auditBibliography` runs that same check plus a retraction lookup across an entire reference list in one call, taking raw BibTeX, RIS, or CSL JSON and returning a per-entry verdict table with a corpus summary.
- **Retraction & open-access checks** — `checkRetraction` surfaces retractions, corrections, and expressions of concern (Crossref / Retraction Watch); `checkOpenAccess` returns OA status and the best legal landing or PDF URL (Unpaywall). Both accept any identifier type and resolve it to a DOI under the hood.
- **Eight identifier types out of the box** — DOIs, PMIDs, PMCIDs, ISBNs, arXiv IDs, ISSNs, NASA ADS bibcodes, and WHO IRIS URLs (rare in citation tooling).
- **Batch-friendly resolve / format / export** — each accepts a single identifier or a comma- or newline-separated list; the server normalises the list and resolves them in one round trip.
- **10,000+ citation styles** — five hand-tuned builtins (Vancouver, AMA, APA, IEEE, CSE) plus any [CSL style ID](https://github.com/citation-style-language/styles), with alias and dependent-style resolution.
- **Nine export formats** — BibTeX, RIS, CSL JSON, EndNote (XML/Refer), RefWorks, MEDLINE, Zotero RDF, CSV, plain text.
- **Composable workflow** — chain `resolveIdentifier` → `formatCitation` → `exportCitation` in one prompt for an end-to-end "raw IDs → exportable bibliography" pipeline.
- **Provenance metadata on every response** — formatted output is followed by a metadata block (`requestId`, `formatter`, `styleUsed`, `warnings`) so the assistant can show users *which* engine produced each citation.
- **No key required** — works anonymously against the public Scholar Sidekick API (rate-limited free tier); add a free first-party `ssk_` key for higher limits, or a RapidAPI key for paid/managed tiers.
- **Hosted HTTP endpoint (no install)** — prefer not to run a local stdio server? Connect any HTTP-capable MCP client straight to `https://scholar-sidekick.com/api/mcp` (Streamable HTTP, same 7 tools). See [Hosted HTTP endpoint](#hosted-http-endpoint-no-install).
- **REST API twin** — the same endpoints are available as the [Scholar Sidekick REST API](https://scholar-sidekick.com/docs) for non-MCP integrations.

## Tools

| Tool | Description |
| --- | --- |
| **verifyCitation** | Verify a claimed citation against the resolved record at its identifier. Detects the Topaz et al. (Lancet 2026) fabrication pattern — real DOI + invented title — that `resolveIdentifier` alone cannot catch. Returns one of four verdicts (`matched` / `mismatch` / `ambiguous` / `not_found`) plus per-field similarity scores and the resolved record so the user can see where the cited title and the actual paper diverged. Optional Stage 3 LLM screen rescues informal-abbreviation false positives (paid plans / first-party authentication only). One citation per call. |
| **auditBibliography** | Run the `verifyCitation` check plus a retraction lookup across a *whole* bibliography in one call. Accepts raw BibTeX, RIS, or CSL-JSON text, or a pre-parsed `claims[]` array; returns a per-entry verdict table and a corpus summary. Capped at 25 entries per call. |
| **resolveIdentifier** | Resolve DOIs, PMIDs, PMCIDs, ISBNs, arXiv IDs, ISSNs, ADS bibcodes, and WHO IRIS URLs to structured bibliographic metadata (CSL JSON). Accepts a single identifier or a comma/newline-separated batch. |
| **formatCitation** | Format one or many identifiers into Vancouver, AMA, APA, IEEE, CSE, or any of 10,000+ CSL styles. Output as text, HTML, or JSON. Returns formatted citations plus a provenance metadata block. |
| **exportCitation** | Export one or many identifiers to BibTeX, RIS, CSL JSON, EndNote (XML/Refer), RefWorks, MEDLINE, Zotero RDF, CSV, or plain text — ready to write to disk or hand to a reference manager. |
| **checkRetraction** | Check whether a single work has been retracted, corrected, or had an expression of concern raised. Sourced from Crossref `updated-by` (Retraction Watch). Resolves DOI/PMID/PMCID/arXiv/ADS inputs to a DOI before lookup. One identifier per call. |
| **checkOpenAccess** | Check whether a single work is openly accessible and where to find the best legal version. Sourced from Unpaywall. Returns OA status (gold/green/hybrid/bronze/closed), best landing/PDF URL, license, and version. Resolves DOI/PMID/PMCID/arXiv/ISBN/ADS inputs to a DOI before lookup. One identifier per call. |

All seven tools are read-only (`readOnlyHint: true`, `destructiveHint: false`). The exact
`tools/list` payload — descriptions, JSON Schemas, and annotations — is committed as
[`tools.json`](tools.json) and ships in the npm tarball, so you can review the full tool
surface without running anything.

## Setup

**No key required.** The server works anonymously against the public Scholar Sidekick API
(`https://scholar-sidekick.com`) at a rate-limited free tier — just install and go. To raise
your limits, create a free first-party `ssk_` key at
[scholar-sidekick.com/account](https://scholar-sidekick.com/account) and set `SCHOLAR_API_KEY`.
For paid/managed tiers, subscribe on
[RapidAPI](https://rapidapi.com/scholar-sidekick-scholar-sidekick-api/api/scholar-sidekick) and
set `RAPIDAPI_KEY` (which routes calls through the RapidAPI gateway).

> **Prefer zero install?** There's also a **hosted HTTP endpoint** at
> `https://scholar-sidekick.com/api/mcp` (Streamable HTTP) — connect any HTTP-capable MCP
> client directly, no `npx` needed. See [Hosted HTTP endpoint](#hosted-http-endpoint-no-install)
> below. The stdio package documented here is the local-install alternative (and the path for
> RapidAPI-keyed users).

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows). The `env` block is optional — omit it to run anonymously:

```json
{
  "mcpServers": {
    "scholar-sidekick": {
      "command": "npx",
      "args": ["-y", "scholar-sidekick-mcp@latest"],
      "env": {
        "SCHOLAR_API_KEY": "ssk_your-first-party-key"
      }
    }
  }
}
```

### Claude Code

```bash
# Anonymous (no key):
claude mcp add scholar-sidekick -- npx -y scholar-sidekick-mcp@latest

# With a free first-party key for higher limits:
claude mcp add scholar-sidekick \
  -e SCHOLAR_API_KEY=ssk_your-first-party-key \
  -- npx -y scholar-sidekick-mcp@latest
```

### Claude Code plugin (server + skill in one step)

This repo is also a **Claude Code plugin marketplace**. Installing the plugin wires
up the MCP server *and* the companion agent skill together — no separate
`claude mcp add`, no `env` block:

```bash
/plugin marketplace add mlava/scholar-sidekick-mcp
/plugin install scholar-sidekick@scholar-sidekick
```

The plugin runs the server anonymously (no key). For higher rate limits, add a free
`ssk_` key from [scholar-sidekick.com/account](https://scholar-sidekick.com/account)
via `claude mcp add` as shown above, or use the hosted endpoint below.

### Cursor / VS Code / Windsurf

Add to `.cursor/mcp.json` or `.vscode/mcp.json` (the `env` block is optional):

```json
{
  "mcpServers": {
    "scholar-sidekick": {
      "command": "npx",
      "args": ["-y", "scholar-sidekick-mcp@latest"],
      "env": {
        "SCHOLAR_API_KEY": "ssk_your-first-party-key"
      }
    }
  }
}
```

### Run in a container (sandboxed)

The server speaks MCP over stdio and needs outbound HTTPS to the Scholar Sidekick API and
nothing else — no filesystem access, no shell. If your policy is that MCP servers don't get
host access, build the image in this repo and run it isolated:

```bash
docker build -t scholar-sidekick-mcp .
```

```json
{
  "mcpServers": {
    "scholar-sidekick": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--read-only", "--cap-drop", "ALL", "--security-opt", "no-new-privileges",
        "-e", "SCHOLAR_API_KEY",
        "scholar-sidekick-mcp"
      ]
    }
  }
}
```

`-i` is required — that's the stdio pipe. Drop the `-e` line if you're running anonymously.
No image is published to a registry; build it locally so you're running a bundle you built
from source you can read.

### Agent skill (optional)

Install a companion [Agent Skill](https://skills.sh) that teaches Claude Code, Cline, and other agents when and how to use these tools — it complements the server config above:

```bash
npx skills add mlava/scholar-sidekick-mcp
```

## Hosted HTTP endpoint (no install)

Don't want to run a local stdio server? Scholar Sidekick is also a **hosted Streamable HTTP
MCP** at `https://scholar-sidekick.com/api/mcp` — the same seven tools, no `npx`, no local
process. It works **anonymously** (rate-limited free tier); add an `Authorization: Bearer ssk_…`
header (a free key from [scholar-sidekick.com/account](https://scholar-sidekick.com/account)) for
higher limits.

Point any HTTP-capable MCP client at it:

```json
{
  "mcpServers": {
    "scholar-sidekick": {
      "type": "http",
      "url": "https://scholar-sidekick.com/api/mcp"
    }
  }
}
```

In Claude Desktop, use **Settings →