Content
<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)
[](https://mcpvault.io/servers/papergraph-mcp/health?utm_source=external_badge&utm_medium=referral&utm_campaign=mcp_health_report)
**Read math papers with evidence, not guesses.**
PaperGraph v1.2.0 is the stable evidence-first reading workflow for math papers: discover public full-text candidates for DOI papers, inspect source-backed proof and citation evidence, review direct and recursive dependencies, then export Markdown Reading Reports or Cross-Paper Reading Plans.
v1.1.6 fixed source re-import data loss and resolver input boundaries; v1.1.7 is a maintenance cleanup without workflow changes. See the [v1.1.6 bugfix notes](docs/reference/v1.1.6-release-notes.md) and [v1.1.7 release](https://github.com/lotchuazzz-crypto/papergraph-mcp/releases/tag/v1.1.7).
It helps AI agents turn arXiv papers, local LaTeX projects, and born-digital PDFs into a local theorem-centered workspace so a researcher can inspect where every claim came from.
[English](#english) | [中文](#中文)
</div>
---
### v1.2.0: DOI inputs and dependency reading
The immutable [v1.2.0 Git tag](https://github.com/lotchuazzz-crypto/papergraph-mcp/tree/v1.2.0)
is available, and its pinned `uvx` version/diagnostics checks have passed. The
installation examples below launch `1.2.0`; the separate GitHub Release page is
still pending. To test subsequent checkout changes in isolation, use
`uv sync --locked --dev`, then `uv run papergraph-mcp --version` and
`uv run papergraph-mcp doctor`. For a wheel, build with `uv build`, install it in a
separate environment, and launch that environment's `papergraph-mcp`.
See the [v1.2.0 notes](docs/reference/v1.2.0-release-notes.md) for
compatibility and release verification boundaries.
CLI, diagnostics and MCP initialization report the same package version.
Diagnostics `build_identity` records the build's full source commit when available,
tracked changes and a source-tree SHA-256; an installed wheel keeps its build-time
identity even when launched from another checkout. A dirty build's commit identifies
its base, not all its contents. Unknown source provenance stays unknown. Release
diagnostics name the version's tag; this field does not check publication or tag
availability. Development builds have a null `release_tag` and explicitly label
their stable installation recommendation. There is no `v1.2.0.dev0` release/tag.
In v1.2.0, `discover-doi DOI` (MCP
`discover_doi_paper`) finds exact DOI metadata and public body candidates without
downloading. Review reported access, identity evidence and version before using
`import-doi-candidate WORKSPACE DOI CANDIDATE_ID --confirm` (MCP
`workspace_import_doi_candidate`, `confirmed=true`). Import only a user-selected
root paper. For a user-requested root DOI, `add-doi-paper WORKSPACE DOI` (MCP
`workspace_add_doi_paper`) imports automatically when exactly one eligible public
PDF candidate is available. Multiple candidates require selection. External
references still require a reviewable import plan.
Provider metadata is not full text. A reported public PDF may be unavailable or
belong to a different version; neither discovery nor extraction verifies its
mathematical contents. Unavailable providers, conflicting DOI identities and
missing public PDFs are reported separately. Use `workspace_add_pdf_paper` for a
legally obtained local PDF when no usable candidate is available. HTTPS PDF
downloads are bounded to 50 MiB and preserve source/version/hash receipts beside
the workspace. Installation examples pin the available v1.2.0 tag.
`get-dependency-reading WORKSPACE PAPER_ID` (MCP
`workspace_get_dependency_reading`) lists results and source-backed main-result
candidates without choosing a definitive main theorem. Add `--target-result-id`
to inspect a chosen result's statement references, direct/recursive proof-local
dependencies, reading order and external import plan. `--direct` limits analysis
to the selected proof. Reading paths preserve `top_down` exploration and provide
`bottom_up` prerequisite order over extracted local evidence, including shared
dependencies. Direct `bottom_up` includes immediate dependencies; direct
`top_down` retains its root-only legacy shape. Cycles return `cycle_blocked`, an
empty `bottom_up`, and cycle evidence. Unknown and external prerequisites stay
visible; empty dependency evidence does not prove mathematical independence.
An explicit introductory declaration such as `Theorem 1.1 (= Theorem 3.1)`
provides a traced `author_declared_correspondence` proof entry when its target is
unique. Both statements remain separate; the proof keeps its original owner.
This records the author's declaration, not verified mathematical equivalence.
Own proofs take priority; ambiguous, missing, cyclic or over-eight-hop entries
remain unresolved and block a purported complete local reading order.
For PDF papers, `result_count`, `proof_count`, `result_kinds` and `evidence_counts`
report extracted evidence. Legacy theorem/citation graph counters retain their
LaTeX statement-graph meaning. `import_state` describes body import separately
from `metadata`; a `display_title` from DOI providers is labeled
`provider_metadata`, with its reported version and provenance receipt.
Formal declarations are retained even when numbers repeat; discussion mentions
do not create new results. Nested external citation evidence remains visible in
Triage with the original review state and confidence.
## English
### What PaperGraph Helps You Do
| Start with a Paper Map | Trace proof evidence | Resolve references | Save reading artifacts |
| --- | --- | --- | --- |
| Identify main-result candidates, result structure, proof-path evidence, and external reading risks before choosing where to read. | Inspect proof-local references, cited stops, source slices, and dependency diagnostics with explicit evidence. | Search Crossref, OpenAlex, and arXiv metadata for blocked references, then apply only a chosen candidate through the reference closure workflow. | Export deterministic Markdown reports and cross-paper reading plans that can live in Git, notes, or handoff sessions. |
PaperGraph v1.1.3 adds Scholarly Reference Resolver: low-risk online metadata search for blocked references, deterministic candidate ranking, and explicit boundary messages when the trail stops at ambiguous or non-importable records.
v1.1.4 introduced **bounded reference expansion**: approve a finite policy, then advance a saved run. Defaults are depth 2 and 10 new papers; unique strong importable identities can be selected automatically, while ambiguous references await review and independent branches continue. Runs retain budgets, evidence, decisions and recovery history. Only arXiv sources and explicitly supplied local PDFs are importable. It does not bypass paywalls or perform unlimited crawling.
v1.1.5 improves **reference identity quality**: traceable bibliography hints, conservative DOI/arXiv normalization, explicit conflicts, provider outcomes and saved matching explanations. New runs use `unique_strong_v2`; existing `unique_strong_v1` tasks keep their legacy resolver. Back up workspaces before upgrading to schema 9; older versions cannot open them. Scores are not probabilities, and metadata agreement is not independent verification. See the [release preparation notes](docs/reference/v1.1.5-release-notes.md) and [offline quality corpus](tests/fixtures/reference_quality/README.md).
See the [expansion walkthrough](docs/walkthroughs/bounded-reference-expansion.md), [offline JSON](docs/examples/reference-expansion-example.json), [reference tree](docs/examples/reference-expansion-example.md), and [v1.1.5 client verification matrix](docs/reference/client-compatibility.md). The pinned commands below install the available v1.2.0 Git tag.
### Why Researchers Use It
| Need | How PaperGraph behaves |
| --- | --- |
| "Do not invent dependencies." | PaperGraph reports evidence-backed links and explains empty results as extraction limits, not mathematical facts. |
| "Show me the exact source." | Results, proofs, dependencies, and citations carry source spans that can be sliced back out of the original paper. |
| "Let me review external papers first." | External references become import plans. Cross-paper plans separate selected-paper citation evidence from unresolved outside risks. |
| "Keep my reading state." | Workspaces store queues, sessions, checkpoints, notes, blocked targets, and open questions locally. |
PaperGraph does not verify proofs, perform semantic theorem matching, or claim that similarly worded results are equivalent.
### Quick Start
Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then verify the pinned Git tag without cloning:
```powershell
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
```
Pinning the `v1.2.0` tag keeps MCP client installations reproducible.
Add PaperGraph to an MCP client that accepts JSON-style stdio configuration:
```json
{
"mcpServers": {
"papergraph": {
"command": "uvx",
"args": ["--from", "git+https://github.com/lotchuazzz-crypto/papergraph-mcp.git@v1.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.
### Ask your agent to set it up
Give a coding agent this request:
> I use an MCP-capable agent/client. Clone (or inspect an existing checkout of) https://github.com/lotchuazzz-crypto/papergraph-mcp and help me configure PaperGraph. Before reading setup instructions, fetch and verify the remote default revision; updating an old feature branch does not make its instructions current. Preserve existing branches and local changes, using a separate clean checkout if needed. Unless I request a historical version, read .agents/skills/setting-up-papergraph/SKILL.md from that current revision and follow it. If the fetch fails, tell me freshness is unknown.
Compatible agents can follow the repository-local [`setting-up-papergraph`](.agents/skills/setting-up-papergraph/SKILL.md) skill. The agent should show you a reusable PaperGraph prompt, explain why `uv` is needed, and ask before installing software, changing client configuration, or restarting the client.
If you do not use an MCP-capable client yet, PaperGraph can still be run from the CLI with the pinned `uvx --from ... papergraph-mcp doctor` command above and the workspace commands below.
If your agent clones into a directory that already exists, ask it to run `git fetch --tags origin` before treating the checkout as current. Existing clones can otherwise remain pinned to an old local `origin/main`.
For a complete first run, follow [First PaperGraph Workspace](docs/walkthroughs/first-workspace.md). The Workspace Starter commands `plan-starter-project` and `bootstrap-reading-project` create `START_HERE.md`, `papergraph-starter-manifest.json`, Reading Reports, and a Cross-Paper Reading Plan from explicit paper inputs. For the stable surface, see [PaperGraph v1 Core Contract](docs/reference/v1-core-contract.md) and the [v1 Release Checklist](docs/reference/v1-release-checklist.md). Example outputs are available as a [Reading Report](docs/examples/reading-report-example.md), a [Cross-Paper Reading Plan](docs/examples/cross-paper-reading-plan-example.md), a [Reference Search](docs/examples/reference-search-example.json), a [Reference Resolution](docs/examples/reference-resolution-example.json), a [Starter Summary](docs/examples/starter-summary-example.md), and a [Starter Manifest](docs/examples/papergraph-starter-manifest-example.json).
For raw user requests, prefer `load_arxiv_request(input=...)` or `papergraph-mcp load-arxiv-request "..."`. These high-level entry points validate bare IDs, URLs, Markdown links, and prose before loading. To inspect the decision without loading, call `validate_arxiv_request` or `papergraph-mcp validate-arxiv-request "..."`. If validation returns `action: ask_user_to_choose`, ask the user to choose; detecting a conflict and then continuing is a failure. Use `load_arxiv_paper` only after the user has provided one already-disambiguated arXiv ID.
### A Typical Reading Flow
```mermaid
flowchart LR
Paper[Paper] --> Results[Extract results]
Results --> Evidence[Inspect proof evidence]
Evidence --> Path[Build reading path]
Path --> Queue[Create reading queue]
Queue --> Imports[Review external import plan]
Queue --> Session[Resume reading session]
```
1. Load a paper from arXiv, local LaTeX, or PDF.
2. List theorem-like results and choose a target theorem.
3. Inspect the theorem statement, proof evidence, source slice, and dependency diagnostics.
4. Generate a reading queue from local proof evidence.
5. Export a single-paper Reading Report when you want a durable Markdown handoff.
6. For a few related papers, export a Cross-Paper Reading Plan to see selected-paper citation evidence and remaining risks.
7. Save checkpoints and notes so the next reading session starts from known state.
### What PaperGraph Does Not Do
| It does | It does not |
| --- | --- |
| Extract and store evidence from papers. | Prove the paper is correct. |
| Follow explicit labels, proof-local references, and citation evidence. | Guess hidden mathematical prerequisites. |
| Build reviewable reading queues and import plans. | Automatically crawl the literature. |
| Keep local reading state in SQLite. | Upload private manuscripts or PDFs. |
## 中文
### PaperGraph 能帮你做什么
| 先看 Paper Map | 追踪证明证据 | 保存阅读产物 | 跨论文规划 |
| --- | --- | --- | --- |
| 在选择阅读目标前，先看到 main-result candidates、结果结构、proof-path evidence 和 external reading risks。 | 查看 proof-local references、citation stops、source slices 和 dependency diagnostics，并保留证据来源。 | 导出确定性的 Markdown report，方便放进 Git、笔记或交接会话。 | 对一组显式给定的小规模相关论文，导出跨论文阅读计划、选中论文之间的 citation evidence 和剩余风险。 |
PaperGraph v1.2.0 是稳定的 evidence-first 数学论文阅读工作流：先看 Paper Map，再检查 proof 和 citation 证据，用 Evidence Triage 理解稀疏抽取结果，对被阻塞的外部引用做 scholarly metadata 搜索，然后把选定候选闭环到用户确认的 arXiv、本地 PDF、DOI、URL 或出版信息。
v1.2.0 改善首次使用诊断、DOI 公开正文入口和证明依赖阅读。Git 标签已可安装，正式 GitHub Release 页面仍待创建。根 DOI 论文仅在阅读策略允许且存在唯一合格公开 PDF 时直接导入；其他候选需要选择，新发现的外部引用仍先审阅。直接与递归依赖、共享前置结果、环和未知证据分别报告，不推断隐藏的数学关系。见 [v1.2.0 说明](docs/reference/v1.2.0-release-notes.md)。
v1.1.6 修复了重新导入时丢失阅读数据及引用解析输入边界；v1.1.7 仅做维护清扫，不改变既有工作流。下方安装命令固定到已发布的 v1.2.0 Git 标签；参见 [v1.1.6 修复说明](docs/reference/v1.1.6-release-notes.md) 和 [v1.1.7 Release](https://github.com/lotchuazzz-crypto/papergraph-mcp/releases/tag/v1.1.7)。
v1.1.4 引入有界引用扩展：默认最多追踪 2 层、导入 10 篇新论文。v1.1.5 进一步改善引用身份匹配：保留解析证据，审慎规范化 DOI/arXiv，明确冲突、服务状态和选择理由。新任务默认 `unique_strong_v2`，已有 `unique_strong_v1` 任务保持旧行为。升级到 schema 9 前请备份 workspace，旧版本无法打开新 schema。分数不是概率，多来源元数据一致也不代表独立验证。导入需要可访问正文，不绕过付费墙。见[完整操作示例](docs/walkthroughs/bounded-reference-expansion.md)及[客户端验证状态](docs/reference/client-compatibility.md)。
### 为什么适合数学论文阅读
| 研究者关心的问题 | PaperGraph 的回答 |
| --- | --- |
| 不要猜依赖。 | 只报告有证据的链接；空依赖结果解释为抽取限制，而不是数学事实。 |
| 我要看到原文位置。 | result、proof、dependency、citation 都尽量保留 source span，可回到原文片段。 |
| 外部论文先让我审。 | 外部引用先变成 import plan；跨论文计划会区分选中论文之间的 citation evidence 和仍在外部的 unresolved risks。 |
| 阅读项目要能继续。 | workspace 在本地保存 queue、session、checkpoint、note、blocked target 和 open question。 |
PaperGraph does not verify proofs，也不做 semantic theorem matching；它不会声称两个措辞相似的结果数学上等价。
### 快速开始
先安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)，然后验证固定版本：
```powershell
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
```
如果你的 MCP client 使用 JSON 风格的 stdio server 配置，可以添加：
```json
{
"mcpServers": {
"papergraph": {
"command": "uvx",
"args": ["--from", "git+https://github.com/lotchuazzz-crypto/papergraph-mcp.git@v1.2.0", "papergraph-mcp"]
}
}
}
```
修改配置后重启 MCP client。这个 server 使用 stdio，所以不带 `--help` 或 `--version` 直接运行时，会安静等待 MCP client 连接。
### 让 agent 帮你设置
你可以把这段话发给 coding agent：
> 我使用的是支持 MCP 的 agent/client。请克隆（如已有则先检查）https://github.com/lotchuazzz-crypto/papergraph-mcp，帮我配置 PaperGraph。读取安装说明前，请先拉取并确认远端默认分支的最新提交；更新旧功能分支不代表安装说明已更新。保留原有分支和本地改动，必要时另建干净的检出目录。除非我指定历史版本，请从这个已确认的默认分支提交读取 .agents/skills/setting-up-papergraph/SKILL.md 并按它执行。若拉取失败，请明确说明无法确认是否最新。
支持本仓库 skill 的 agent 会读取 [`setting-up-papergraph`](.agents/skills/setting-up-papergraph/SKILL.md)，展示可复用提示词，解释为什么需要 `uv`，并在安装软件、修改客户端配置或重启客户端前询问你。
如果你暂时没有支持 MCP 的 client，也可以先用 CLI：运行上方固定版本的 `uvx --from ... papergraph-mcp doctor` 和下方 workspace 命令。
如果目标目录已经存在，请让 agent 先运行 `git fetch --tags origin`，再判断仓库是否是最新。否则已有 clone 可能仍停留在旧的本地 `origin/main`。
第一次完整使用可以跟着 [First PaperGraph Workspace](docs/walkthroughs/first-workspace.md) 走。稳定承诺见 [PaperGraph v1 Core Contract](docs/reference/v1-core-contract.md)，发布前检查见 [v1 Release Checklist](docs/reference/v1-release-checklist.md)。示例输出见 [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)。
普通用户请求优先走 `load_arxiv_request(input=...)` 或 `papergraph-mcp load-arxiv-request "..."`。这些入口会在加载前验证 bare IDs、URLs、Markdown links 和自然语言描述。若验证返回 `action: ask_user_to_choose`，必须让用户选择；detecting a conflict and then continuing is a failure。Use `load_arxiv_paper` only after 用户已经给出单一、无歧义的 arXiv ID。
### 典型阅读流程
1. 从 arXiv、本地 LaTeX 或 PDF 加载论文。
2. 列出 theorem-like results，选择目标定理。
3. 查看 theorem statement、proof evidence、source slice 和 dependency diagnostics。
4. 根据本地 proof evidence 生成 reading queue。
5. 需要持久交接时，导出单篇 Reading Report。
6. 面对几篇相关论文时，导出 Cross-Paper Reading Plan，查看选中论文之间的 citation evidence 和剩余风险。
7. 保存 checkpoints 和 notes，下次继续读时不必从头开始。
## Reference
<details>
<summary><strong>Complete Tool Reference</strong></summary>
### Core Workflows
| Workflow | Main tools |
| --- | --- |
| Load papers | `open_workspace`, `workspace_add_local_paper`, `workspace_add_arxiv_paper`, `workspace_add_pdf_paper`, `workspace_list_papers`, `workspace_get_paper` |
| Start a project | `workspace_plan_starter_project`, `workspace_bootstrap_reading_project` |
| Map papers | `workspace_get_paper_map`, `workspace_export_paper_reading_report`, `workspace_export_cross_paper_reading_plan` |
| Inspect results | `workspace_list_results`, `workspace_get_result`, `workspace_get_result_proof`, `workspace_get_proof_dependencies`, `workspace_get_external_result_mentions`, `workspace_get_evidence`, `workspace_get_citations`, `workspace_search_theorems` |
| Read a proof | `workspace_export_reading_bundle`, `workspace_export_result_reading_context`, `workspace_get_source_slice`, `workspace_get_result_reading_path` |
| Resume reading | `workspace_create_reading_session`, `workspace_list_reading_sessions`, `workspace_get_reading_session`, `workspace_record_reading_checkpoint`, `workspace_add_reading_note`, `workspace_export_reading_session_summary` |
| Plan reading | `workspace_create_reading_queue`, `workspace_list_reading_queues`, `workspace_get_reading_queue`, `workspace_apply_reading_queue_to_session` |
| Resolve references | `workspace_plan_external_imports_for_result`, `workspace_plan_external_imports_for_queue`, `workspace_plan_external_imports_for_paper`, `workspace_search_external_reference`, `workspace_list_external_reference_searches`, `workspace_resolve_external_reference_candidate`, `workspace_resolve_external_reference`, `workspace_list_external_reference_resolutions` |
Original single-paper tools: `get_environment_diagnostics`, `validate_arxiv_request`, `load_arxiv_request`, `validate_arxiv_input`, `load_paper`, `load_arxiv_paper`, `list_theorems`, `get_theorem`, `get_dependencies`, `get_dependency_diagnostics`, and `where_used`.
Complete workspace tool index: `open_workspace`, `workspace_add_local_paper`, `workspace_add_arxiv_paper`, `workspace_list_papers`, `workspace_get_paper`, `workspace_search_theorems`, `workspace_get_dependencies`, `workspace_get_dependency_diagnostics`, `workspace_get_citations`, `workspace_add_pdf_paper`, `workspace_get_paper_map`, `workspace_export_paper_reading_report`, `workspace_export_cross_paper_reading_plan`, `workspace_plan_starter_project`, `workspace_bootstrap_reading_project`, `workspace_list_results`, `workspace_get_result`, `workspace_get_result_proof`, `workspace_get_proof_dependencies`, `workspace_get_external_result_mentions`, `workspace_get_evidence`, `workspace_export_reading_bundle`, `workspace_export_result_reading_context`, `workspace_get_source_slice`, `workspace_get_result_reading_path`, `workspace_create_reading_session`, `workspace_list_reading_sessions`, `workspace_get_reading_session`, `workspace_record_reading_checkpoint`, `workspace_add_reading_note`, `workspace_export_reading_session_summary`, `workspace_create_reading_queue`, `workspace_list_reading_queues`, `workspace_get_reading_queue`, `workspace_apply_reading_queue_to_session`, `workspace_plan_external_imports_for_result`, `workspace_plan_external_imports_for_queue`, `workspace_plan_external_imports_for_paper`, `workspace_search_external_reference`, `workspace_list_external_reference_searches`, `workspace_resolve_external_reference_candidate`, `workspace_resolve_external_reference`, `workspace_list_external_reference_resolutions`.
</details>
<details>
<summary><strong>CLI Shortcuts</strong></summary>
Most workspace operations are available from the CLI with `--workspace`:
```powershell
papergraph-mcp validate-arxiv-request "[math/0307200](https://arxiv.org/abs/2609.01574)"
papergraph-mcp plan-starter-project --workspace .\papergraph.sqlite3 --artifact-dir .\papergraph-starter --pdf .\paper-a.pdf=local:paper-a
papergraph-mcp bootstrap-reading-project --workspace .\papergraph.sqlite3 --artifact-dir .\papergraph-starter --pdf .\paper-a.pdf=local:paper-a --no-queue --no-session
papergraph-mcp get-paper-map --workspace .\papergraph.sqlite3 --paper-id local:paper-a
papergraph-mcp export-paper-reading-report --workspace .\papergraph.sqlite3 --paper-id local:paper-a
papergraph-mcp export-paper-reading-report --workspace .\papergraph.sqlite3 --paper-id local:paper-a --output report.md
papergraph-mcp export-cross-paper-reading-plan --workspace .\papergraph.sqlite3 --paper-id local:paper-a --paper-id arxiv:2401.12345 --output cross-paper-plan.md
papergraph-mcp export-reading-bundle --workspace .\papergraph.sqlite3 --paper-id local:paper-a
papergraph-mcp export-result-reading-context --workspace .\papergraph.sqlite3 --result-id local:paper-a::thm:main
papergraph-mcp get-source-slice --workspace .\papergraph.sqlite3 --result-id local:paper-a::thm:main
papergraph-mcp get-result-reading-path --workspace .\papergraph.sqlite3 --result-id local:paper-a::thm:main
papergraph-mcp create-reading-session --workspace .\papergraph.sqlite3 --paper-id local:paper-a
papergraph-mcp record-reading-checkpoint --workspace .\papergraph.sqlite3 --session-id SESSION --target-kind result --target-id local:paper-a::thm:main --status reviewed
papergraph-mcp add-reading-note --workspace .\papergraph.sqlite3 --session-id SESSION --text "Need to check the cited fixed point theorem."
papergraph-mcp export-reading-session-summary --workspace .\papergraph.sqlite3 --session-id SESSION
papergraph-mcp create-reading-queue --workspace .\papergraph.sqlite3 --result-id local:paper-a::thm:main
papergraph-mcp list-reading-queues --workspace .\papergraph.sqlite3
papergraph-mcp get-reading-queue --workspace .\papergraph.sqlite3 --queue-id QUEUE
papergraph-mcp apply-reading-queue-to-session --workspace .\papergraph.sqlite3 --queue-id QUEUE --session-id SESSION
papergraph-mcp plan-external-imports-for-result --workspace .\papergraph.sqlite3 --result-id local:paper-a::thm:main
papergraph-mcp plan-external-imports-for-queue --workspace .\papergraph.sqlite3 --queue-id QUEUE
papergraph-mcp plan-external-imports-for-paper --workspace .\papergraph.sqlite3 --paper-id local:paper-a
papergraph-mcp search-external-reference --workspace .\papergraph.sqlite3 --paper-id local:paper-a --blocked-id BLOCKED
papergraph-mcp list-external-reference-searches --workspace .\papergraph.sqlite3 --paper-id local:paper-a
papergraph-mcp resolve-external-reference-candidate --workspace .\papergraph.sqlite3 --paper-id local:paper-a --blocked-id BLOCKED --candidate-id CANDIDATE --import-target
papergraph-mcp resolve-external-reference --workspace .\papergraph.sqlite3 --paper-id local:paper-a --blocked-id BLOCKED --doi 10.1000/example --title "Published target"
papergraph-mcp resolve-external-reference --workspace .\papergraph.sqlite3 --paper-id local:paper-a --blocked-id BLOCKED --pdf .\reference.pdf=local:reference
papergraph-mcp list-external-reference-resolutions --workspace .\papergraph.sqlite3 --paper-id local:paper-a
```
For a compact single-paper check with an already-disambiguated ID, call `load_arxiv_paper(arxiv_id="math/0307200")`. For ordinary user text, call `load_arxiv_request(input="math/0307200")`. PaperGraph selects `main.tex`; a representative first response has `"path": "main.tex"`, `"cached": false`, and `"nodes": 7`.
</details>
<details>
<summary><strong>Evidence Boundaries</strong></summary>
PaperGraph v0.4.4 dependency traversal uses `statement_explicit_latex_refs_only`: it follows explicit LaTeX references such as `\ref`, `\eqref`, `\autoref`, `\cref`, and `\Cref` inside theorem-like statements. An empty dependency result means PaperGraph found no resolvable theorem-label references under that rule. It is not evidence that the theorem has no mathematical dependencies.
Proof dependency extraction is evidence-scoped. PaperGraph looks inside TeX proof environments, direct proof continuations, and short text immediately following a theorem-like result, including evidence tied to the immediately preceding result. It reports explicit references, simple inferred local references, and unresolved mentions separately. It does not infer unstated mathematical prerequisites.
Kind metadata is intentionally explicit:
- `raw_kind`: what the source extractor found.
- `display_kind`: the user-facing type label.
- `normalized_kind`: the stable grouping key used by tools.
</details>
<details>
<summary><strong>Local Three-Paper Walkthrough</strong></summary>
The repository includes a small fixture under `tests/fixtures/workspace_tex_project/`. A typical local demo imports `paper_a`, `paper_b`, and `paper_c`, then searches for `fixed point`:
- `workspace_search_theorems("fixed point")` returns `local:paper-a::thm:main`, `local:paper-b::thm:main`, and `local:paper-c::thm:main`.
- `workspace_get_citations("local:paper-a", direction="outgoing", include_unresolved=True)` reports citation keys `absent`, `missing`, and `paper-b`.
- The `paper-b` citation has cited arXiv ID `2401.12346`, but it does not resolve to `local:paper-b`; the row keeps `target_paper_id: null`.
- To create a resolved target, the cited arXiv ID is imported with `workspace_add_arxiv_paper`. A local paper with a similar bibliography entry is not enough; citation resolution is based on explicit cited arXiv ID evidence.
</details>
<details>
<summary><strong>Safety, Privacy, And Limits</strong></summary>
arXiv source downloads use its fixed e-print endpoint. The development DOI flow
also accepts discovered public HTTPS PDF candidates, validates public addresses
and each redirect, pins the validated connection address, checks PDF content and
limits downloads to **50 MiB**, **8 seconds** per socket operation and a **60-second**
elapsed budget. Synchronous DNS lookup cannot be interrupted by that elapsed
budget. External-reference discovery does not download papers. arXiv archives
limit compressed responses to **100 MiB**, expanded content to **500 MiB**, and
archives to **10,000** members. Absolute paths, parent traversal, symbolic links,
hard links, devices, FIFOs, and other special archive members are rejected.
Workspaces are ordinary local SQLite files. Local PDFs remain local. Extracted PDF text, source spans, and proof evidence are written only to the workspace you choose. Do not commit databases, private manuscripts, cache data, credentials, tokens, generated distributions, or raw local logs.
PDF extraction is best for born-digital PDFs; scanned PDFs or OCR-heavy files may produce sparse text and missing evidence. Complex projects may need an explicit `main_file`; the parser is not a full TeX engine.
PDF statements join only bounded adjacent source blocks, retaining their locations.
PDF result/proof responses report `text_coverage.status: unverified` and
`statement_complete: false` / `proof_complete: false`: completeness has not been
established. These flags do not assert that every text is truncated. Use
`text_coverage.continuation_source` to inspect adjoining blocks; this context is
not automatically proof evidence or a dependency. Mathematical layout is not
reconstructed, and delayed proofs without a supported association stay unresolved.
Reference assessments distinguish full author-list compatibility from
`partial_overlap`. Shared authors alone do not establish equivalent lists,
increase the full-author score, or authorize automatic candidate selection.
</details>
<details>
<summary><strong>Release Highlights</strong></summary>
- v1.1.3 adds Scholarly Reference Resolver: metadata search across Crossref, OpenAlex, and arXiv for blocked references, deterministic candidate ranking, candidate apply through Reference Import Closure, and explicit boundaries for ambiguous, old, paywalled, or metadata-only literature.
- v1.1.2 adds Reference Import Closure: user-confirmed arXiv and local PDF imports for blocked references, DOI, URL, and published metadata records for non-importable targets, and regenerated reading reports after successful imports.
- v1.1.1 adds Evidence Triage for first-use Reading Reports and Starter artifacts, with candidate-start labels, sparse dependency status, external blocker next actions, and unchanged evidence boundaries.
- v1.1.0 adds Workspace Starter planning and bootstrap commands for `START_HERE.md`, `papergraph-starter-manifest.json`, Reading Reports, and Cross-Paper Reading Plans from explicit paper inputs.
- v1.0.0 released the stable PaperGraph core: Paper Map, Reading Report, Cross-Paper Reading Plan, first-workspace onboarding, and the v1 evidence contract.
- v0.13.0 added the v1.0 readiness pass with stable core contract docs, first-workspace walkthroughs, and example Reading Report/Cross-Paper Reading Plan artifacts.
- v0.12.0 added Cross-Paper Reading Plan, a deterministic Markdown artifact for explicit paper sets with recommended sequence, selected-paper citation evidence, external risks, and evidence boundaries.
- v0.11.0 added Reading Report Export, a deterministic Markdown artifact with Paper Map context, main-result candidates, reading route, external risks, and evidence boundaries.
- v0.10.0 added Paper Map, an evidence-first first-load overview with main-result candidates, structure, reading route, and external-risk evidence.
- v0.9.3 added external import review summaries.
- v0.9.2 improved cited-result mention extraction.
- v0.9.1 added proof-adjacent dependency evidence.
- v0.9.0 introduced reading queues, sessions, and external import planning.
- v0.4.0 introduced cross-paper SQLite workspaces with `workspace_add_arxiv_paper`, `workspace_search_theorems`, and `workspace_get_citations`. Resolution remains explicit, not semantic.
</details>
<details>
<summary><strong>Development</strong></summary>
```powershell
uv sync
uv run pytest -q -p no:cacheprovider
```
The automated suite uses synthetic archives, projects, bibliography entries, and PDFs. It does not require the live arXiv service.
</details>
### Contributing And License
Bug reports, research-reading workflows, reproducible fixtures, and PRs are welcome. Please read [Contributing](CONTRIBUTING.md) before submitting changes. PaperGraph is released under the [MIT License](LICENSE).
Connection Info
You Might Also Like
No recommendations available