Papergraph

PaperGraph MCP

Read math papers with evidence, not guesses.

Turn arXiv papers, local LaTeX projects, and born-digital PDFs into a local theorem-centered workspace. Inspect source-backed results, proofs, citations, and dependencies; save reading progress and export Markdown reports.

What You Can Do

• Start with a Paper Map: inspect structure, main-result candidates, and external reading risks before choosing a theorem.
• Trace statements and proof-local references back to source slices; inspect direct and recursive dependencies, shared prerequisites, cycles, and unknowns.
• Discover public full-text candidates for DOI papers and review scholarly reference matches from Crossref, OpenAlex, and arXiv.
• Keep queues, sessions, checkpoints, notes, and open questions in local SQLite workspaces. Export Reading Reports and Cross-Paper Reading Plans.

Quick Start

Install uv; no Git or checkout is required:

uvx --from papergraph-mcp==1.2.3 papergraph-mcp --version
uvx --from papergraph-mcp==1.2.3 papergraph-mcp doctor

PyPI 1.2.3 is published and has passed actual public-package and local Git-free acceptance. The dedicated GitHub public-index CI has not run; the GitHub Release is not published. Diagnostics alone do not verify publication.

An MCP client can use this JSON-style stdio configuration:

{
  "mcpServers": {
    "papergraph": {
      "command": "uvx",
      "args": ["--from", "papergraph-mcp==1.2.3", "papergraph-mcp"]
    }
  }
}

Restart the client after configuration. A bare server launch waits quietly for a stdio MCP connection; CLI commands also work without an MCP client.

For agent-assisted setup, use the repository's setup skill from the freshly fetched remote default revision. Preserve existing branches and local changes; ask before installing software, changing client configuration, or restarting. The optional Git-source route requires Git and live verification of the selected version tag against its reviewed package source.

Read Your First Paper

Editable DrawCMS source.

1. Keep the workspace database outside the repository. Preview inputs with plan-starter-project; it validates files without importing or writing. Run bootstrap-reading-project after review to create the workspace and reading artifacts. Local LaTeX inputs must name the main .tex file.
2. Open the Paper Map and Evidence Triage, choose a result, then inspect its statement, proof, source slices, and dependency evidence.
3. Review external import plans, save checkpoints and notes, and export a report or cross-paper plan. Follow the first-workspace walkthrough for commands and examples.

For raw arXiv requests, use load_arxiv_request; conflicting IDs or links require user selection before loading. For DOI discovery, discover-doi DOI finds candidates without downloading. add-doi-paper WORKSPACE DOI can import a requested root paper when exactly one eligible public PDF exists; multiple candidates require selection.

For an existing workspace, replace the placeholders with actual IDs:

uvx --from papergraph-mcp==1.2.3 papergraph-mcp get-paper-map --workspace WORKSPACE --paper-id PAPER_ID
uvx --from papergraph-mcp==1.2.3 papergraph-mcp get-dependency-reading WORKSPACE PAPER_ID --target-result-id RESULT_ID --detail compact

Arguments are command-specific: check each command's --help. Compact dependency output retains access to full evidence.

Evidence Boundaries

• PaperGraph does not verify proofs, infer hidden prerequisites, or establish semantic theorem equivalence. Empty dependencies do not prove independence; extracted reading orders are not complete mathematical dependency graphs.
• Long PDFs support raw source pagination through workspace_read_source_blocks and its next handle. New automatic PDF proof evidence covers only the first physical line with an explicit proof heading; ownership can remain unknown, and later proof references remain unknown. Raw continuation is readable but does not become dependency evidence automatically. Existing excerpts retain their extraction policy until explicit reimport.
• External references become reviewable plans, not automatic downloads. Bounded reference expansion requires an explicitly approved finite policy; ambiguous matches await review. Metadata is not full text, and no workflow bypasses paywalls.
• Papers and reading state remain local. Back up workspaces before schema upgrades; older versions cannot open schema 9.

Documentation

• v1.2.3 release notes · Publication evidence · Artifact verification
• Local LaTeX extraction and independent acceptance
• Core contract · Historical v1.1.5 client evidence
• Examples: Reading Report · Cross-Paper Reading Plan · Reference Search · Reference Resolution
• Starter outputs: Summary · Manifest
• v1.2.2 release notes · Publication evidence · Artifact verification
• Contributing · MIT License