papergraph-mcp
PaperGraph MCP turns math papers into evidence-grounded reading maps for AI agents: extract results, trace proof evidence, plan reading order, and review external dependencies without guessing.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/lotchuazzz-crypto--papergraph-mcp)HTML
<a href="/listings/lotchuazzz-crypto--papergraph-mcp"><img src="/api/listings/lotchuazzz-crypto--papergraph-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then verify the pinned PyPI package. This path needs uv/uvx and index access, without Git or a checkout:
uvx --from papergraph-mcp==1.2.0 papergraph-mcp --version uvx --from papergraph-mcp==1.2.0 papergraph-mcp doctor
Pinning `papergraph-mcp==1.2.0` keeps the package version reproducible. The repository checker defaults to this verified PyPI path: `python scripts/check_onboarding.py --smoke-test` launches the pinned version command; without `--smoke-test` it only inspects prerequisites and local refs. Repository/Git context and checkout freshness are separate from PyPI readiness. The published 1.2.0 doctor still recommends Git-source installation and may report unavailable Git context outside a checkout; this nonfatal warning does not block PyPI startup. See [publication and no-Git acceptance](docs/reference/pypi-preparation.md).
Optional Git-source installation requires Git as well as uv/uvx:
uvx --from git+https://github.com/lotchuazzz-crypto/papergraph-mcp.git@v1.2.0 papergraph-mcp --version uvx --from git+https://github.com/lotchuazzz-crypto/papergraph-mcp.git@v1.2.0 papergraph-mcp doctor
Select `--install-source git` when using the repository checker for that route. The PyPI 1.2.0 page retains the README embedded in its original release build; editing main does not update that description. Corrections belong to a separately approved new version; never move the v1.2.0 tag or replace its published files.
Add PaperGraph to an MCP client that accepts JSON-style stdio configuration:
{
"mcpServers": {
"papergraph": {
"command": "uvx",
"args": ["--from", "papergraph-mcp==1.2.0", "papergraph-mcp"]
}
}
}Restart the MCP client after changing its configuration. The server uses stdio, so running the command without `--help` or `--version` waits quietly for an MCP client connection.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 87 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <div align="center">
- # PaperGraph MCP
- [](https://github.com/lotchuazzz-crypto/papergraph-mcp/actions/workflows/ci.yml)
- [](https://www.python.org/)
- [](LICENSE)
- [](https://github.com/lotchuazzz-crypto/papergraph-mcp/releases)
- **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.
- </div>
- ## 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](https://docs.astral.sh/uv/getting-started/installation/); no Git or checkout is required:
- ```sh
- 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](docs/reference/v1.2.3-publication.md). 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:
- ```json
- {
- "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](.agents/skills/setting-up-papergraph/SKILL.md) 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
- [](docs/assets/papergraph-request-flow.png)
- [Editable DrawCMS source](docs/assets/papergraph-request-flow.drawcms).
- 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](docs/walkthroughs/first-workspace.md) 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:
- ```sh
- 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](docs/walkthroughs/bounded-reference-expansion.md) 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](docs/reference/v1.2.3-release-notes.md) · [Publication evidence](docs/reference/v1.2.3-publication.md) · [Artifact verification](docs/reference/v1.2.3-artifact-verification.md)
- - [Local LaTeX extraction and independent acceptance](docs/reference/latex-extraction.md)
- - [Core contract](docs/reference/v1-core-contract.md) · [Historical v1.1.5 client evidence](docs/reference/client-compatibility.md)
- - Examples: [Reading Report](docs/examples/reading-report-example.md) · [Cross-Paper Reading Plan](docs/examples/cross-paper-reading-plan-example.md) · [Reference Search](docs/examples/reference-search-example.json) · [Reference Resolution](docs/examples/reference-resolution-example.json)
- - Starter outputs: [Summary](docs/examples/starter-summary-example.md) · [Manifest](docs/examples/papergraph-starter-manifest-example.json)
- - [v1.2.2 release notes](docs/reference/v1.2.2-release-notes.md) · [Publication evidence](docs/reference/v1.2.2-publication.md) · [Artifact verification](docs/reference/v1.2.2-artifact-verification.md)
- - [Contributing](CONTRIBUTING.md) · [MIT License](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.