v1.2.0 release preparation

The release preparation package identifies itself as 1.2.0. Publication is pending; the default installation below still launches published v1.1.7 until the v1.2.0 tag and release are available. To test this checkout in isolation, use uv sync --locked --dev, then uv run papergraph-mcp --version and uv run papergraph-mcp doctor. To test a wheel, build with uv build, install the resulting 1.2.0 wheel in a separate environment, and launch that environment's papergraph-mcp. Do not reuse the stable uvx --from ...@v1.1.7 command to test the new features.

See the v1.2.0 preparation notes 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. Published installation examples remain pinned to v1.1.7.

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

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 and offline quality corpus.

See the expansion walkthrough, offline JSON, reference tree, and v1.1.5 client verification matrix. The pinned commands below install the published v1.1.7 release.

Why Researchers Use It

PaperGraph does not verify proofs, perform semantic theorem matching, or claim that similarly worded results are equivalent.

Quick Start

Install uv, then verify the pinned GitHub release without cloning:

uvx --from git+https://github.com/lotchuazzz-crypto/papergraph-mcp.git@v1.1.7 papergraph-mcp --version
uvx --from git+https://github.com/lotchuazzz-crypto/papergraph-mcp.git@v1.1.7 papergraph-mcp doctor

Pinning the v1.1.7 tag keeps MCP client installations reproducible.

Add PaperGraph to an MCP client that accepts JSON-style stdio configuration:

{
  "mcpServers": {
    "papergraph": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/lotchuazzz-crypto/papergraph-mcp.git@v1.1.7", "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 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. 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 and the v1 Release Checklist. Example outputs are available as a Reading Report, a Cross-Paper Reading Plan, a Reference Search, a Reference Resolution, a Starter Summary, and a Starter Manifest.

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

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

中文

PaperGraph 能帮你做什么

PaperGraph v1.1.7 是稳定的 evidence-first 数学论文阅读工作流：先看 Paper Map，再检查 proof 和 citation 证据，用 Evidence Triage 理解稀疏抽取结果，对被阻塞的外部引用做 scholarly metadata 搜索，然后把选定候选闭环到用户确认的 arXiv、本地 PDF、DOI、URL 或出版信息。

v1.1.6 修复了重新导入时丢失阅读数据及引用解析输入边界；v1.1.7 仅做维护清扫，不改变既有工作流。下方安装命令固定到已发布的 v1.1.7；参见 v1.1.6 修复说明 和 v1.1.7 Release。

v1.1.4 引入有界引用扩展：默认最多追踪 2 层、导入 10 篇新论文。v1.1.5 进一步改善引用身份匹配：保留解析证据，审慎规范化 DOI/arXiv，明确冲突、服务状态和选择理由。新任务默认 unique_strong_v2，已有 unique_strong_v1 任务保持旧行为。升级到 schema 9 前请备份 workspace，旧版本无法打开新 schema。分数不是概率，多来源元数据一致也不代表独立验证。只支持 arXiv 源码和明确提供的本地 PDF，不绕过付费墙。见完整操作示例及客户端验证状态。

为什么适合数学论文阅读

PaperGraph does not verify proofs，也不做 semantic theorem matching；它不会声称两个措辞相似的结果数学上等价。

快速开始

先安装 uv，然后验证固定版本：

uvx --from git+https://github.com/lotchuazzz-crypto/papergraph-mcp.git@v1.1.7 papergraph-mcp --version
uvx --from git+https://github.com/lotchuazzz-crypto/papergraph-mcp.git@v1.1.7 papergraph-mcp doctor

如果你的 MCP client 使用 JSON 风格的 stdio server 配置，可以添加：

{
  "mcpServers": {
    "papergraph": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/lotchuazzz-crypto/papergraph-mcp.git@v1.1.7", "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，展示可复用提示词，解释为什么需要 uv，并在安装软件、修改客户端配置或重启客户端前询问你。

如果你暂时没有支持 MCP 的 client，也可以先用 CLI：运行上方固定版本的 uvx --from ... papergraph-mcp doctor 和下方 workspace 命令。

如果目标目录已经存在，请让 agent 先运行 git fetch --tags origin，再判断仓库是否是最新。否则已有 clone 可能仍停留在旧的本地 origin/main。

第一次完整使用可以跟着 First PaperGraph Workspace 走。稳定承诺见 PaperGraph v1 Core Contract，发布前检查见 v1 Release Checklist。示例输出见 Reading Report、Cross-Paper Reading Plan、Reference Search 和 Reference Resolution。

普通用户请求优先走 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

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

uv sync
uv run pytest -q -p no:cacheprovider

Contributing And License

Bug reports, research-reading workflows, reproducible fixtures, and PRs are welcome. Please read Contributing before submitting changes. PaperGraph is released under the MIT License.