science2code-mcp

A local MCP server that grounds coding agents in scientific papers you already hold. An agent checks a quote against your PDFs and gets back the paper's own words with a page and a locator, or a typed refusal. No language model is in the loop, so nothing can hallucinate a passage, and it never claims whose idea a sentence is.

What it is for

You are building software and want its design grounded in real literature. Drop the papers in a folder; when an agent cites one ("Paper X says Y"), this server confirms Y is verbatim in X, or refuses. It keeps citations honest.

It does not summarise, rank, or decide which paper is relevant. Those remain your work and the agent's. This is the fact-checker underneath them.

Related MCP server: rag-mcp-server

What it is not, and the context-window question

Be clear about this before you rely on it. An agent can read the extracted .txt files, and doing so puts them in the context window, which is the cost you are probably trying to avoid. science2code does not remove that cost. It was never a "read all my papers cheaply" tool. It removes a different cost: to verify a quote, the agent sends one string and gets a small answer back, without loading the paper. So it makes checking cheap and trustworthy; it does not make comprehension free. If what you want is "give the agent the relevant bits without dumping everything in," that is semantic retrieval, a different tool this is not.

Install

Requires Python 3.10 or newer and poppler-utils (which supplies pdftotext).

pip install "science2code-mcp[mcp]"     # from a checkout: pip install -e ".[mcp]"

The core has zero third-party dependencies and is stdlib only. The mcp extra adds the server runtime (fastmcp); dev adds pytest and ruff.

Quickstart

mkdir ~/papers && cp *.pdf ~/papers/
science2code index ~/papers      # extract text once, write manifest.json
science2code status ~/papers     # what is held, stale, or has no text layer

Then register the server with your MCP client and point the environment variable SCIENCE2CODE_CORPUS at ~/papers. The full walkthrough, including correcting a title and handling a scanned PDF, is in docs/QUICKSTART.md.

The two tools an agent sees

• verify_quote(text, paper_id?): is this quote really in this paper? Returns the document's own characters with a page and a character locator, or a typed refusal. Omit paper_id to check every held document.

• find_passage(query, paper_ids?): where does this phrase occur? A literal search that returns passages in the paper's words, or zero hits. It is not semantic, does not rank by relevance, and does not summarise.

Outcomes

Every response carries exactly one outcome from a closed set, so a caller can enumerate every answer the server can give.

The two identity outcomes use pure character comparison with no similarity threshold, so a paraphrase can never be returned as the document's own words.

The ceiling

It reports whether a string is in a document and where. It does not judge whether a passage supports a claim, and it cannot detect a relevant work you never read. Both are human judgements, and it never asserts whose claim a sentence carries. Every response says so.

It never deletes a file

No deletion primitive is imported anywhere in the package, a test over the syntax tree keeps it that way, and writes go through one temp-and-replace helper. Where something ought to be removed, the command is printed for you to run.

Optional: build the corpus from Zotero (read only)

You never need Zotero. But if your papers live there, a separate, strictly read-only command can fill the folder from a tagged subset over Zotero's built-in local API:

science2code-zotero sync --tag mytag --out ./papers   # symlinks the tagged PDFs
science2code index ./papers

It only reads Zotero (HTTP GET), never writes to it, and removes only links it made itself. science2code-zotero annotations --tag mytag lists your highlights as candidate quotes. The core never imports any of this.

Licence

AGPL-3.0-or-later. See LICENSE. To cite the software, see CITATION.cff.