MathPaperLib

Русская версия

MathPaperLib keeps the papers you work with in one folder, ~/Literature, under names such as Bondarenko 2021 - Inverse spectral problems for functional-differential operators with involution.pdf, and gives an AI agent tools to find papers, download them, read them page by page and search their full texts. The tools run as an MCP server, which any agent harness with MCP support can start, and as the lit command.

arXiv and Math-Net.Ru serve files under identifiers (2107.12209v1.pdf, rm9740.pdf), so a folder of downloads cannot be read by eye. A PDF saved by hand from a publisher's site keeps the name the site gave it, and the tool that fetched the other papers knows nothing about it. When every project keeps its own papers, a paper used by two projects is downloaded and indexed twice.

MathPaperLib keeps one library per user. Each paper is stored once, under a name built from its authors, year and title. A PDF downloaded by hand goes into the inbox folder, where it is identified from its first pages and filed under the same rule. A project keeps only its registry, the list of papers it uses with their roles, and reads the files from the library. Full-text search covers LaTeX sources and the text layers of PDFs; it combines BM25 with the multilingual embedding model intfloat/multilingual-e5-small, run on the CPU.

The library

~/Literature/
  Bondarenko 2021 - Inverse spectral problems for functional-differential operators with involution.pdf
  Bondarenko 2021 - Inverse spectral problems for functional-differential operators with involution.tex
  Shkalikov 2016 - Vozmushcheniya samosopryazhennykh i normalnykh operatorov s diskretnym spektrom.pdf
  library.json
  inbox/
  .lit/

library.json records the metadata of every paper, its identifiers (arXiv, DOI, Math-Net.Ru), the names of its files and their SHA-256 checksums. .lit/ holds what is derived from the papers: text layers of PDFs, rendered pages, parts of transcriptions and the search index. To keep the library elsewhere, set MATHPAPERLIB_HOME or pass --library.

A file is named Authors Year - Title. One or two authors are listed by surname, three or more give First et al.; the year comes from the metadata, or else from the arXiv identifier. Cyrillic is transliterated and accents are removed, so every name is ASCII. Characters that Windows, macOS or Linux forbid in file names are replaced, a name longer than 140 characters is cut at a word, and a name already taken gets (2). The name is given when the paper enters the library and does not change afterwards.

Related MCP server: Personal Research Assistant MCP

The inbox

Put a PDF you downloaded into inbox/ and run lit inbox, or let the agent call the inbox tool. The identifier is looked for in this order: an arXiv number in the file name, an arXiv number in the text of the first two pages, a DOI in the same text. Since the first DOI on a page may belong to a cited paper, the identifier is accepted only when at least 60 % of the title words of four letters or more occur on those pages. The accepted file moves into the library under its name and is indexed; in a project it is also attached to the registry entry with the same identifier, if that entry has no file yet. A file that is not identified stays in the inbox with the reason, and lit inbox FILE --id DOI takes it under the identifier you give.

Projects

A project is a folder with sources/papers.json or a [sources] table in project.toml. Its registry gives every paper a code S1, S2, …, the role of the paper in the project, a checked description and the status of its theorem cards; lit catalog builds sources/catalog.md from the registry. Search inside a project is limited to the papers of its registry. Every key of the table below is optional:

[sources]
registry = "sources/papers.json"
catalog = "sources/catalog.md"
cards = "sources/cards"            # theorem cards S*.md, `verified:` in the header
results = "sources/results.md"
library = "output/literature"      # a library of this project only
direct_hosts = ["mathnet.ru"]      # hosts reached past the VPN tunnel

Requests to a host from direct_hosts go out from the address of a network interface other than the default route, that is, past a VPN tunnel; the default list is mathnet.ru.

The project is taken from --root, else from MATHPAPERLIB_PROJECT, else it is the nearest project up from the current folder. With --no-project, or when no project is found, the tools work on the library alone; the MCP tool use_project selects a project during a session.

A project made with the lit.py of the AutoMath research template keeps its files in output/literature/ under identifier names. lit migrate copies them into the library under new names together with their text layers and transcription parts, then rewrites the registry. The old folder stays until you delete it; with --move the files are moved instead. --dry-run lists what would be moved and changes nothing: a trial run without it already rewrites the registry, and a second run then finds nothing to move.

Installation

The package runs with uv. The first start of the MCP server, or the first indexing or search from the command line, downloads the embedding model from Hugging Face, about 470 MB; the server begins to answer only after the download ends.

Command line:

uv tool install git+https://github.com/LeoLourson/MathPaperLib
lit where

The MCP server is started by uvx --from git+https://github.com/LeoLourson/MathPaperLib mathpaperlib mcp and talks over stdio.

• Claude Code: /plugin marketplace add LeoLourson/MathPaperLib, then /plugin install mathpaperlib@mathpaperlib. The plugin adds the MCP server and two skills, literature and transcribe-paper.

• DSH: the bundle dsh-mathpaperlib lives in dsh/. Link it into node_modules of a profile and add it to dependencies and to dsh.profile.bundles. It adds the MCP server, the two skills and a prompt section with the path of the library and the number of PDFs waiting in its inbox. To run a local checkout instead of the GitHub version, override the entry mcp-mathpaperlib in the profile patch with command: uv and args: [run, --directory, <checkout>, lit, --no-project, mcp].

• Codex, in ~/.codex/config.toml:

  [mcp_servers.mathpaperlib]
  command = "uvx"
  args = ["--from", "git+https://github.com/LeoLourson/MathPaperLib", "mathpaperlib", "mcp"]

• Any other MCP client: the same command. The skills in skills/ are plain SKILL.md files; copy them where the harness reads instructions, or into AGENTS.md.

Commands

REF is a registry code (S4), an identifier, or the beginning of a file name in the library. The MCP server offers the same actions as tools.

Limits

Only open copies are downloaded: arXiv sources and PDFs, Math-Net.Ru PDFs with open full text, and the open-access PDF that OpenAlex knows for a DOI. For any other paper add records the metadata, and the PDF comes through the inbox or attach.

The inbox recognises a paper only by an arXiv number or a DOI. A scan without a text layer, or a paper whose first two pages carry neither, stays in the inbox until it is named with --id.

Titles are transliterated, not translated: a paper in Russian gets its Russian title in Latin letters even when an English title is known. An author given by initials alone appears in the name as those initials.

Messages of the tool are in Russian; descriptions of the MCP tools and the skills are in English.

Development

uv sync
uv run pytest
node dsh/test/smoke.mjs

The tests need neither the network nor the model. License: MIT.