# scansci-pdf

**Repository Path**: glorythesky/scansci-pdf

## Basic Information

- **Project Name**: scansci-pdf
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-07
- **Last Updated**: 2026-06-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ScanSci PDF

[![PyPI version](https://img.shields.io/pypi/v/scansci-pdf)](https://pypi.org/project/scansci-pdf/)
[![Python](https://img.shields.io/pypi/pyversions/scansci-pdf)](https://pypi.org/project/scansci-pdf/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-compatible-green)](https://modelcontextprotocol.io)

> 学术论文下载 MCP 服务器 — 13+ 数据源、100+ 高校 WebVPN、并行竞速下载引擎

---

## 为什么选择 ScanSci PDF？

- **一个工具，13+ 数据源** — arXiv、Sci-Hub、LibGen、Unpaywall、OpenAlex、Semantic Scholar、DOAJ、EuropePMC、CORE、PMC、出版商直链等，自动选择最快可用源
- **100+ 高校 WebVPN** — 通过中国高校机构代理访问付费论文全文，CAS 认证，密码不经过工具
- **CARSI 联邦认证** — 支持 ScienceDirect、Springer、Wiley、IEEE、Taylor & Francis、Nature 等出版商的机构登录
- **Cloudflare 绕过** — CloakBrowser 反检测浏览器（Chromium 指纹修补）+ curl_cffi TLS 指纹模拟 + FlareSolverr 浏览器引擎
- **并行竞速引擎** — 多数据源同时尝试，首个成功立即返回，无需逐个等待
- **智能列表解析** — 支持 APA 引文、BibTeX、DOI 列表，自动补全缺失 DOI 后批量下载
- **自动重命名** — PDF 自动重命名为 `作者年份_标题.pdf` 格式
- **引文导出** — 一键获取 BibTeX、RIS、EndNote 格式引文
- **网络诊断** — 自动检测 DNS 封锁、代理配置、Tor 连接问题，给出针对性修复建议

---

## 前置准备（可选但推荐）

### Elsevier API Key — ScienceDirect 直接下载

ScienceDirect/Elsevier 是最大的学术出版商。配置 API Key 后可直接通过 API 下载 PDF，**无需浏览器登录**，速度从 15-30 秒降到 1-2 秒。

**申请步骤：**

1. 访问 [Elsevier Developer Portal](https://dev.elsevier.com/) 注册账号（已有 Elsevier 账号可直接登录）
2. 点击 **"My API Key"** → 创建新应用 → 选择 **"ScienceDirect Article Retrieval"** API
3. 复制生成的 API Key，运行配置命令：

```bash
# 方式一：通过 MCP 工具（推荐，会自动打开浏览器引导）
scansci_pdf_elsevier_setup

# 方式二：直接配置
scansci_pdf_config_set(key="elsevier_api_key", value="你的APIKey")
```

> **提示：** 申请完全免费，无需机构邮箱，个人邮箱即可。配置后所有 Elsevier/ScienceDirect/Cell Press 论文自动走 API 快速通道。

---

## 快速开始

### 安装

```bash
pip install scansci-pdf
```

### MCP 配置

在任何支持 MCP 的 Agent 中添加以下配置即可使用：

```json
{
  "mcpServers": {
    "scansci-pdf": {
      "command": "scansci-pdf",
      "args": ["run"]
    }
  }
}
```

支持 MCP 的 Agent 和客户端：

| 客户端 | 说明 |
|--------|------|
| Claude Desktop | Anthropic 官方桌面客户端 |
| Claude Code | Anthropic 命令行 Agent |
| Cursor | AI 代码编辑器 |
| Windsurf | AI 代码编辑器 |
| Cline | VS Code 插件 Agent |
| Cherry Studio | 多模型桌面客户端 |
| OpenClaw | MCP 客户端 |
| 任何 MCP 兼容客户端 | MCP 是开放协议，任何实现均可接入 |

<details>
<summary>HTTP 模式（远程/Web 调用）</summary>

适用于远程部署或不支持 stdio 的场景：

```bash
scansci-pdf run --mode streamable_http --host 0.0.0.0 --port 8000
```
</details>

### 检查环境

```bash
scansci-pdf check
```

---

## 工作原理

下载一篇论文时，ScanSci PDF 会同时启动多个数据源，按优先级分层竞速：

```
Tier 1 (4s)  ─ 出版商直链（OA/机构访问）
Tier 2 (5s)  ─ OpenAlex / Unpaywall / DOAJ
Tier 3 (8s)  ─ EuropePMC / CORE / PMC / arXiv
Tier 4 (25s) ─ LibGen / Sci-Hub（带 FlareSolverr 绕过）
Tier 5 (20s) ─ WebVPN / CARSI 机构代理
```

首个成功下载的源立即返回，其余自动取消。自适应评分系统会根据历史成功率和延迟动态调整源的优先级。

---

## MCP 工具

### 论文下载

| 工具 | 描述 |
|------|------|
| `scansci_pdf_smart_download` | **推荐** 零配置下载，自动尝试所有源 + Tor |
| `scansci_pdf_download` | 下载单篇论文（完整参数控制） |
| `scansci_pdf_batch_download` | 批量下载多篇论文 |
| `scansci_pdf_resolve_and_download` | 解析列表 → 补全 DOI → 批量下载 |

### 付费墙登录

| 工具 | 描述 |
|------|------|
| `scansci_pdf_login` | **推荐** 统一登录：输入 DOI 自动识别出版商并打开浏览器 SSO |
| `scansci_pdf_camofox_login` | camofox 持久化浏览器登录 |
| `scansci_pdf_camofox_status` | 检查 camofox-browser 状态 |
| `scansci_pdf_camofox_import_cookies` | 导入 Netscape cookie 到 camofox |
| `scansci_pdf_import_browser_cookies` | 打开浏览器捕获登录 cookie |

### 搜索与解析

| 工具 | 描述 |
|------|------|
| `scansci_pdf_search` | 按关键词搜索论文（OpenAlex） |
| `scansci_pdf_parse_list` | 解析 APA/BibTeX/DOI 列表文件 |

### 引文管理

| 工具 | 描述 |
|------|------|
| `scansci_pdf_citation` | 获取论文引文（BibTeX/RIS/EndNote） |
| `scansci_pdf_import_bib` | 导入 .bib 文件并下载全部论文 |

### 机构代理（WebVPN / CARSI / EZProxy）

| 工具 | 描述 |
|------|------|
| `scansci_pdf_vpnsci_set_school` | 设置 WebVPN 学校 |
| `scansci_pdf_vpnsci_login` | WebVPN 浏览器 CAS 认证 |
| `scansci_pdf_vpnsci_status` | WebVPN 登录状态 |
| `scansci_pdf_vpnsci_schools` | 搜索支持的大学 |
| `scansci_pdf_vpnsci_test` | 测试 WebVPN 连接性 |
| `scansci_pdf_carsi_login` | CARSI 出版商机构登录 |
| `scansci_pdf_carsi_status` | CARSI 状态与 cookie 检查 |
| `scansci_pdf_ezproxy_login` | EZProxy 图书馆代理登录 |
| `scansci_pdf_ezproxy_status` | EZProxy 状态检查 |

### 系统管理

| 工具 | 描述 |
|------|------|
| `scansci_pdf_auto_setup` | 一键环境检测与自动配置 |
| `scansci_pdf_setup_check` | 检测系统环境并给出安装建议 |
| `scansci_pdf_health_check` | 检查所有数据源可用性与延迟 |
| `scansci_pdf_network_diagnose` | 网络诊断 + 修复建议 |
| `scansci_pdf_source_scores` | 各数据源历史成功率排名 |
| `scansci_pdf_config_get` / `config_set` | 查看/修改配置 |
| `scansci_pdf_cache_clear` | 清除下载缓存 |

### Tor 管理

| 工具 | 描述 |
|------|------|
| `scansci_pdf_tor_install` | 自动下载安装 Tor Expert Bundle |
| `scansci_pdf_tor_start` | 启动内嵌 Tor SOCKS5 代理 |
| `scansci_pdf_tor_stop` | 停止 Tor 代理 |

---

## 下载策略

| 策略 | 描述 |
|------|------|
| `fastest`（默认） | 多数据源并行，最快获胜 |
| `oa_first` | 优先开放获取，Sci-Hub 兜底 |
| `scihub_only` | 仅使用 Sci-Hub |
| `legal_only` | 仅使用合法数据源（不含 Sci-Hub/LibGen） |

---

## 付费墙：机构登录

### 统一登录（推荐）

只需一行，自动识别出版商、打开浏览器、引导完成 SSO 登录，cookie 跨所有下载复用：

```
scansci_pdf_login(identifier="10.1126/science.aec6396")
```

`identifier` 可以是 DOI 或出版商名（`elsevier`, `wiley`, `nature`, `springer`, `ieee`, `science`, `tandfonline`, `acs`, `rsc`, `aip`, `aps`, `iop`, `oxford`, `acm`）。

### WebVPN（高校代理）

通过中国高校机构代理访问论文全文：

```
1. scansci_pdf_vpnsci_schools(query="北京")      → 搜索学校
2. scansci_pdf_vpnsci_set_school(school="你的学校")
3. scansci_pdf_vpnsci_login                     → 浏览器 CAS 认证
4. scansci_pdf_vpnsci_test                      → 确认连接正常
```

支持 100+ 所高校。

### CARSI（出版商联邦认证）

直接通过出版商机构登录页面认证，无需 WebVPN 中转：

```
1. scansci_pdf_config_set(key="carsi_enabled", value="true")
2. scansci_pdf_config_set(key="carsi_idp_name", value="你的学校名称")
3. scansci_pdf_carsi_login(publisher="sciencedirect")
```

支持：sciencedirect, springer, wiley, ieee, tandfonline, nature

### EZProxy（图书馆代理）

通过学校图书馆 EZProxy 服务访问：

```
1. scansci_pdf_config_set(key="ezproxy_enabled", value="true")
2. scansci_pdf_config_set(key="ezproxy_login_url", value="https://libproxy.你的学校.edu.cn/login?url={url}")
3. scansci_pdf_ezproxy_login
```

---

## 配置参考

通过 `scansci_pdf_config_set` 修改：

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `scihub_enabled` | `true` | 启用 Sci-Hub |
| `download_strategy` | `fastest` | 下载策略 |
| `output_dir` | `~/.scansci-pdf/papers` | PDF 输出目录 |
| `auto_rename` | `true` | 自动重命名 PDF |
| `network_proxy` | （空） | HTTP/SOCKS 代理地址 |
| `batch_workers` | `10` | 批量下载并发数 |
| `vpnsci_enabled` | `false` | 启用 WebVPN |
| `vpnsci_school` | （空） | WebVPN 学校名称 |
| `carsi_enabled` | `false` | 启用 CARSI 联邦认证 |
| `carsi_idp_name` | （空） | CARSI 机构名称 |
| `flaresolverr_url` | `http://localhost:8191/v1` | FlareSolverr 服务地址 |
| `use_tor_for_scihub` | `false` | Sci-Hub 使用 Tor |

---

## 高级功能（可选）

以下功能为可选项，适用于特定网络环境或高级需求。

### Docker 部署

适用于需要将 scansci-pdf 作为长期运行服务的场景，或不想在本机安装 Python 环境的用户。Docker 容器内置 MCP 服务器和 Tor 代理，数据通过 Docker 卷持久化。

```bash
docker compose up -d
```

| 服务 | 说明 | 端口 |
|------|------|------|
| `scansci-pdf` | MCP 服务器 | 8000 |
| `tor` | Tor SOCKS5 代理 | 1080 |

Docker 配置方式：

```json
{
  "mcpServers": {
    "scansci-pdf": {
      "command": "docker",
      "args": ["compose", "-f", "path/to/docker-compose.yml", "run", "--rm", "scansci-pdf"]
    }
  }
}
```

### Tor 匿名代理

Tor 用于在 Sci-Hub、LibGen 等网站被网络封锁的地区匿名访问。如果你的网络可以直连 Sci-Hub，则不需要 Tor。内嵌 Tor 会自动下载 Tor Expert Bundle（约 30MB），无需 Docker 或系统级安装。

```bash
# 首次使用：自动下载安装 Tor
scansci_pdf_tor_install

# 启动 Tor SOCKS5 代理
scansci_pdf_tor_start

# 如果 Tor 本身也被封锁（连接超时），启用 obfs4 桥接绕过
scansci_pdf_tor_start(use_bridges=true)

# 下载时通过 Tor 访问
scansci_pdf_download(identifier="10.1038/nature12373", use_tor=true)
```

二进制文件存储在 `~/.scansci-pdf/tor/`，不污染系统环境。

### FlareSolverr（Cloudflare 绕过）

当 Sci-Hub、LibGen 等站点触发 Cloudflare 防护时，FlareSolverr 可以自动绕过。需要 Docker 运行 FlareSolverr 服务：

```bash
docker run -d -p 8191:8191 ghcr.io/flaresolverr/flaresolverr
```

ScanSci PDF 会自动检测 Cloudflare 并回退到 FlareSolverr，无需手动配置。如果已安装 curl_cffi，会优先使用 TLS 指纹模拟（更快，无需 Docker）。

---

## 故障排查

**Sci-Hub 下载失败** — 运行 `scansci_pdf_health_check(detailed=true)` 查看数据源状态。域名轮换自动处理。如果遇到 Cloudflare 防护，安装 FlareSolverr 或 curl_cffi。

**Tor 连接失败** — 确认 Tor 运行在 `socks5h://127.0.0.1:1080`。如 Tor 也被封锁，使用 `scansci_pdf_tor_start(use_bridges=true)` 启用桥接。

**WebVPN 登录失败** — 需要 CloakBrowser（自动安装）。登录在你的浏览器中完成，密码不经过本工具。

**下载速度慢** — 运行 `scansci_pdf_health_check(detailed=true)` 检查数据源延迟。如 Sci-Hub 在你的网络被封锁，尝试 `legal_only` 策略或配置代理。

**网络问题** — 运行 `scansci_pdf_network_diagnose` 获取全面的连接诊断报告和针对性修复建议。

---

## 架构说明

本项目采用分层架构：

| 层级 | 内容 | 许可 |
|------|------|------|
| 公开层 | 所有 `.py` 源码、配置、文档 | Apache 2.0 |
| 保护层 | `_core/*.pyx`（Cython 源码） | 专有，不公开 |
| 分发层 | `_core/*.pyd`（编译二进制） | 随 PyPI 包分发 |

从 GitHub 克隆的用户使用纯 Python 回退实现（功能相同，性能略低）。从 PyPI 安装的用户自动获得编译版本。

---

## 赞助者

<a href="https://github.com/qwlei328-maker"><img src="https://avatars.githubusercontent.com/u/257463305?v=4" width="50" height="50" alt="qwlei328-maker" title="Natasha"/></a>
<a href="https://github.com/jingqingqiu1"><img src="https://avatars.githubusercontent.com/u/87510394?v=4" width="50" height="50" alt="jingqingqiu1" title="jingqingqiu1"/></a>
<a href="https://github.com/minqifeng"><img src="https://avatars.githubusercontent.com/u/61303605?v=4" width="50" height="50" alt="minqifeng" title="minqifeng"/></a>

---

## 致谢

本项目在开发过程中参考和借鉴了以下开源项目：

- **[FlareSolverr](https://github.com/FlareSolverr/FlareSolverr)** — 早期反 bot 绕过架构设计
- **[ref-downloader](https://github.com/ltczding-gif/ref-downloader)** — Publisher 专用下载策略（Elsevier crasolve 检测、Wiley PDFDirect、AIP loading page 等）
- **[paper-fetch-skill](https://github.com/Dictation354/paper-fetch-skill)** — 论文获取 Agent Skill 设计
- **[paper-fetcher](https://github.com/fermionoid/paper-fetcher)** — 论文下载流程参考
- **[cloakbrowser](https://github.com/CloakHQ/CloakBrowser)** — Chromium stealth 浏览器引擎

感谢以上项目作者的开源贡献。

---

## 许可证

[Apache License 2.0](LICENSE)

例外：`src/scansci_pdf/_core/` 中的 Cython 编译扩展（`.pyd`/`.so`）为预编译二进制，仅通过 PyPI 分发。其 Cython 源码（`.pyx`）为专有代码，不包含在本仓库中。