Paper Search MCP (Node.js)

中文|English

一个基于Node.js的模型上下文协议(MCP)服务器，用于搜索和下载多个学术数据库的论文，包括arXiv、Web of Science、PubMed、Google Scholar、Sci-Hub、ScienceDirect、Springer、Wiley、Scopus、Crossref等14个学术平台。

✨ 核心特性

• 🌍 14个学术平台: arXiv, Web of Science, PubMed, Google Scholar, bioRxiv, medRxiv, Semantic Scholar, IACR ePrint, Sci-Hub, ScienceDirect, Springer Nature, Wiley, Scopus, Crossref
• 🔗 MCP协议集成: 与Claude Desktop和其他AI助手无缝集成
• 📊 统一数据模型: 标准化的论文数据格式，支持所有平台
• ⚡ 高性能搜索: 并发搜索和智能速率限制
• 🛡️ 安全优先: DOI验证、查询清理、注入防护、敏感数据脱敏
• 📝 类型安全: 完整的TypeScript支持和扩展接口
• 🎯 学术论文优先: 智能过滤，优先显示学术论文而非书籍
• 🔄 智能错误处理: 统一ErrorHandler，支持重试逻辑和平台降级

📚 支持的平台

平台	搜索	下载	全文	被引统计	API密钥	特色功能
Crossref	✅	❌	❌	✅	❌	默认搜索平台，广泛的元数据覆盖
arXiv	✅	✅	✅	❌	❌	物理/计算机科学预印本
Web of Science	✅	❌	❌	✅	✅ 必需	多主题搜索、日期排序、年份范围
PubMed	✅	❌	❌	❌	🟡 可选	生物医学文献
Google Scholar	✅	❌	❌	✅	❌	广泛学术搜索
bioRxiv	✅	✅	✅	❌	❌	生物学预印本
medRxiv	✅	✅	✅	❌	❌	医学预印本
Semantic Scholar	✅	✅	❌	✅	🟡 可选	AI语义搜索
IACR ePrint	✅	✅	✅	❌	❌	密码学论文
Sci-Hub	✅	✅	❌	❌	❌	通过DOI获取论文
ScienceDirect	✅	❌	❌	✅	✅ 必需	爱思唯尔全文数据库
Springer Nature	✅	✅*	❌	❌	✅ 必需	双API：Meta v2 & OpenAccess
Wiley	❌	✅	✅	❌	✅ 必需	TDM API：仅支持DOI下载PDF
Scopus	✅	❌	❌	✅	✅ 必需	最大引文数据库

✅ 已支持 | ❌ 不支持 | 🟡 可选 | ✅* 仅开放获取

注意: Wiley TDM API不支持关键词搜索。请使用search_crossref搜索Wiley文章获取DOI，然后使用download_paper配合platform="wiley"通过DOI下载PDF。

⚖️ 合规与伦理使用（Sci-Hub / Google Scholar）

本项目包含的部分集成可能涉及法律、第三方服务条款（ToS）与伦理风险。你需要自行确保使用方式符合当地法律、机构政策以及第三方平台条款。

• Sci-Hub：在许多司法辖区可能涉及未经授权获取受版权保护内容。请仅在你拥有合法访问权的情况下使用（例如开放获取、作者公开版本或机构合法订阅）。
• Google Scholar：该集成依赖自动化抓取/解析，可能违反 Google 的服务条款，且可能触发封禁/限流。若需要严格 ToS 合规，建议优先使用官方 API 或元数据平台（如 Crossref、Semantic Scholar）。

🚀 快速开始

系统要求

• Node.js >= 18.0.0
• npm 或 yarn

安装

# 克隆仓库
git clone https://github.com/Dianel555/paper-search-mcp-nodejs.git
cd paper-search-mcp-nodejs

# 安装依赖
npm install

# 复制环境变量模板
cp .env.example .env

配置

1. 获取Web of Science API密钥
2. 访问 Clarivate Developer Portal
3. 注册并申请Web of Science API访问权限

4. 将API密钥添加到 .env 文件

5. 获取PubMed API密钥（可选）

6. 无API密钥：免费使用，限制每秒3次请求
7. 有API密钥：每秒10次请求，更稳定的服务

8. 获取密钥：参考 NCBI API Keys

9. 配置环境变量 ```bash # 编辑 .env 文件 WOS_API_KEY=your_actual_api_key_here WOS_API_VERSION=v1

# PubMed API密钥（可选，建议配置以获得更好性能） PUBMED_API_KEY=your_ncbi_api_key_here

# Semantic Scholar API密钥（可选，提升请求限制） SEMANTIC_SCHOLAR_API_KEY=your_semantic_scholar_api_key

# Elsevier API密钥（ScienceDirect和Scopus必需） ELSEVIER_API_KEY=your_elsevier_api_key

# Springer Nature API密钥（Springer必需） SPRINGER_API_KEY=your_springer_api_key # Meta v2 API # 可选：OpenAccess API单独密钥（如果与主密钥不同） SPRINGER_OPENACCESS_API_KEY=your_openaccess_api_key

# Wiley TDM令牌（Wiley必需） WILEY_TDM_TOKEN=your_wiley_tdm_token ```

构建和运行

方法1: NPX部署 (推荐用于MCP)

# 使用npx直接运行 (最常见的MCP部署方式)
npx -y paper-search-mcp-nodejs

# 或全局安装
npm install -g paper-search-mcp-nodejs
paper-search-mcp

方法2: 本地开发

# 构建TypeScript代码
npm run build

# 运行服务器
npm start

# 或者在开发模式下运行
npm run dev

MCP服务器配置

在Claude Desktop配置文件中添加以下配置：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

NPX配置 (推荐)

{
  "mcpServers": {
    "paper-search-nodejs": {
      "command": "npx",
      "args": ["-y", "paper-search-mcp-nodejs"],
      "env": {
        "WOS_API_KEY": "your_web_of_science_api_key"
      }
    }
  }
}

本地安装配置

{
  "mcpServers": {
    "paper_search_nodejs": {
      "command": "node",
      "args": ["/path/to/paper-search-mcp-nodejs/dist/server.js"],
      "env": {
        "WOS_API_KEY": "your_web_of_science_api_key"
      }
    }
  }
}

🛠️ MCP工具

search_papers

搜索多个平台的学术论文

// 随机平台选择（默认行为）
search_papers({
  query: "machine learning",
  platform: "all",      // 随机选择一个平台，提供高效聚焦的结果
  maxResults: 10,
  year: "2023",
  sortBy: "date"
})

// 搜索特定平台
search_papers({
  query: "quantum computing",
  platform: "webofscience",  // 指定特定平台
  maxResults: 5
})

平台选择行为： - platform: "crossref" (默认) - 免费API，广泛的学术元数据覆盖 - platform: "all" - 随机选择一个平台进行高效、聚焦的搜索 - 特定平台 - 仅搜索指定平台 - 可用平台: crossref, arxiv, webofscience/wos, pubmed, biorxiv, medrxiv, semantic, iacr, googlescholar/scholar, scihub, sciencedirect, springer, scopus - 注意: wiley仅支持通过DOI下载PDF，不支持关键词搜索

search_crossref

搜索Crossref学术数据库（默认搜索平台）

search_crossref({
  query: "machine learning",
  maxResults: 10,
  year: "2023",
  author: "Smith",
  sortBy: "relevance",  // 或 "date", "citations"
  sortOrder: "desc"
})

search_arxiv

专门搜索arXiv预印本

search_arxiv({
  query: "transformer neural networks",
  maxResults: 10,
  category: "cs.AI",
  author: "Vaswani",
  year: "2023",
  sortBy: "date",      // relevance, date, citations
  sortOrder: "desc"    // asc, desc
})

search_webofscience

专门搜索Web of Science数据库

search_webofscience({
  query: "CRISPR gene editing",
  maxResults: 15,
  year: "2022",
  journal: "Nature"
})

search_pubmed

专门搜索PubMed/MEDLINE生物医学文献数据库

search_pubmed({
  query: "COVID-19 vaccine efficacy",
  maxResults: 20,
  year: "2023",
  author: "Smith",
  journal: "New England Journal of Medicine",
  publicationType: ["Journal Article", "Clinical Trial"],
  sortBy: "date"       // relevance, date
})

search_google_scholar

专门搜索Google Scholar学术数据库

search_google_scholar({
  query: "machine learning",
  maxResults: 10,
  yearLow: 2020,
  yearHigh: 2023,
  author: "Bengio"
})

search_biorxiv / search_medrxiv

搜索生物学和医学预印本

search_biorxiv({
  query: "CRISPR",
  maxResults: 15,
  days: 30,
  category: "genomics"  // neuroscience, genomics等
})

search_medrxiv({
  query: "COVID-19",
  maxResults: 10,
  days: 30,
  category: "infectious_diseases"
})

search_semantic_scholar

搜索Semantic Scholar AI语义数据库

search_semantic_scholar({
  query: "deep learning",
  maxResults: 10,
  fieldsOfStudy: ["Computer Science"],
  year: "2023"
})

search_iacr

搜索IACR ePrint密码学论文档案

search_iacr({
  query: "zero knowledge proof",
  maxResults: 5,
  fetchDetails: true
})

search_scihub

通过DOI搜索并下载Sci-Hub论文

search_scihub({
  doiOrUrl: "10.1038/nature12373",
  downloadPdf: true,
  savePath: "./downloads"
})

search_sciencedirect

搜索爱思唯尔ScienceDirect数据库

search_sciencedirect({
  query: "artificial intelligence",
  maxResults: 10,
  year: "2023",
  author: "Smith",
  openAccess: true  // 仅搜索开放获取论文
})

search_springer

搜索Springer Nature数据库（Metadata API v2 或 OpenAccess API）

search_springer({
  query: "machine learning",
  maxResults: 10,
  year: "2023",
  openAccess: true,  // 使用OpenAccess API获取可下载PDF
  type: "Journal"    // 过滤类型: Journal, Book, Chapter
})

search_wiley (已废弃)

注意: Wiley TDM API不支持关键词搜索。请使用search_crossref搜索Wiley文章，然后使用download_paper通过DOI下载PDF。

// 正确的Wiley使用方式：
// 1. 使用Crossref搜索Wiley文章
search_crossref({
  query: "cancer research",
  maxResults: 10
})

// 2. 使用download_paper通过DOI下载PDF
download_paper({
  paperId: "10.1111/xxx.12345",
  platform: "wiley",
  savePath: "./downloads"
})

search_scopus

搜索Scopus引文数据库

search_scopus({
  query: "renewable energy",
  maxResults: 10,
  affiliation: "MIT",
  documentType: "ar"  // ar=文章, cp=会议论文, re=综述
})

check_scihub_mirrors

检查Sci-Hub镜像站点健康状态

check_scihub_mirrors({
  forceCheck: true  // 强制刷新健康检查
})

download_paper

下载论文PDF文件

download_paper({
  paperId: "2106.12345",
  platform: "arxiv",
  savePath: "./downloads"
})

get_paper_by_doi

通过DOI获取论文信息

get_paper_by_doi({
  doi: "10.1038/s41586-023-12345-6",
  platform: "all"
})

get_platform_status

检查平台状态和API密钥

get_platform_status({})

📊 数据模型

所有平台的论文数据都转换为统一的格式：

interface Paper {
  paperId: string;           // 唯一标识符
  title: string;            // 论文标题
  authors: string[];        // 作者列表
  abstract: string;         // 摘要
  doi: string;             // DOI
  publishedDate: Date;     // 发布日期
  pdfUrl: string;          // PDF链接
  url: string;             // 论文页面URL
  source: string;          // 来源平台
  citationCount?: number;   // 被引次数
  journal?: string;         // 期刊名称
  year?: number;           // 年份
  categories?: string[];    // 学科分类
  keywords?: string[];      // 关键词
  // ... 更多字段
}

🔧 开发

项目结构

src/
├── models/
│   └── Paper.ts              # 论文数据模型
├── platforms/
│   ├── PaperSource.ts        # 抽象基类
│   ├── ArxivSearcher.ts      # arXiv搜索器
│   ├── WebOfScienceSearcher.ts # Web of Science搜索器
│   ├── PubMedSearcher.ts     # PubMed搜索器
│   ├── GoogleScholarSearcher.ts # Google Scholar搜索器
│   ├── BioRxivSearcher.ts    # bioRxiv/medRxiv搜索器
│   ├── SemanticScholarSearcher.ts # Semantic Scholar搜索器
│   ├── IACRSearcher.ts       # IACR ePrint搜索器
│   ├── SciHubSearcher.ts     # Sci-Hub搜索器（带镜像管理）
│   ├── ScienceDirectSearcher.ts # ScienceDirect（爱思唯尔）搜索器
│   ├── SpringerSearcher.ts   # Springer Nature搜索器（Meta v2 & OpenAccess API）
│   ├── WileySearcher.ts      # Wiley TDM API（仅DOI下载）
│   ├── ScopusSearcher.ts     # Scopus引文数据库搜索器
│   └── CrossrefSearcher.ts   # Crossref API搜索器（默认平台）
├── utils/
│   └── RateLimiter.ts        # 令牌桶速率限制器
└── server.ts                 # MCP服务器主文件

添加新平台

1. 创建新的搜索器类继承 PaperSource
2. 实现必需的抽象方法
3. 在 server.ts 中注册新的搜索器
4. 添加相应的MCP工具

安全特性 (v0.2.6)

代码库包含全面的安全和优化工具：

src/utils/
├── SecurityUtils.ts      # 安全工具
│   ├── sanitizeDoi()     # DOI格式验证
│   ├── escapeQueryValue() # 查询注入防护
│   ├── validateQueryComplexity() # DoS防护
│   ├── withTimeout()     # 请求超时保护
│   ├── sanitizeRequest() # 敏感数据移除
│   └── maskSensitiveData() # API密钥脱敏
├── ErrorHandler.ts       # 统一错误处理
│   ├── ApiError class    # 带元数据的自定义错误
│   ├── HTTP error codes  # 400-504错误处理
│   └── Retry logic       # 指数退避重试
├── RateLimiter.ts        # 令牌桶速率限制
├── QuotaManager.ts       # 每日配额追踪 (v0.2.6 新增)
├── RequestCache.ts       # 请求LRU缓存 (v0.2.6 新增)
└── PDFExtractor.ts       # PDF文本提取 (v0.2.6 新增)

src/services/
└── CitationService.ts    # 引文获取服务 (v0.2.6 新增)

安全最佳实践： - 所有DOI在使用前都经过验证 - 查询参数经过转义以防止注入 - 所有日志输出中的API密钥都已脱敏 - 请求超时防止连接挂起 - 查询复杂度限制防止DoS攻击 - 速率限制和配额管理防止API滥用 - 缓存减少外部API调用

测试

测试套件已重组以提高可维护性 (v0.2.6)：

# 运行测试
npm test

# 运行代码检查
npm run lint

# 代码格式化
npm run format

测试覆盖： - 19个测试套件，158个测试用例 - 所有13个平台搜索器已测试 - 安全工具（DOI验证、查询清理） - 错误处理器（错误分类、重试逻辑） - 新测试：速率限制集成、配额管理、请求缓存

测试套件	覆盖状态
平台搜索器	13/13 ✅
SecurityUtils	✅
ErrorHandler	✅
RateLimiter & Integration	✅
QuotaManager	✅
RequestCache	✅

🌟 平台特性

Springer Nature 双API系统

Springer Nature提供两个API：

1. Metadata API v2（主API）
2. 端点：https://api.springernature.com/meta/v2/json
3. 搜索所有Springer内容（订阅 + 开放获取）

4. 需要从http://dev.springernature.com/获取API密钥

5. OpenAccess API（可选）

6. 端点：https://api.springernature.com/openaccess/json
7. 仅搜索开放获取内容
8. 可能需要单独的API密钥或特殊权限
9. 更适合查找可下载的PDF

Web of Science 特性

🎯 WoS Starter API v1/v2 支持: 使用Clarivate的WoS Starter API，完整支持所有字段标签。

API版本配置:

# 在.env文件中配置 (默认: v1)
WOS_API_VERSION=v1   # 稳定版，推荐使用
# WOS_API_VERSION=v2  # 较新版本，相同端点

高级搜索语法

// 多主题搜索
search_webofscience({
  query: 'oriented structure',
  year: '2023-2025',
  sortBy: 'date',
  sortOrder: 'desc',
  maxResults: 10
})

// 年份范围过滤
search_webofscience({
  query: 'machine learning',
  year: '2020-2024',  // 支持范围格式
  sortBy: 'citations',
  sortOrder: 'desc'
})

// 高级查询与过滤器
search_webofscience({
  query: 'blockchain',
  author: 'zhang',
  journal: 'Nature',
  year: '2023',
  sortBy: 'date',
  sortOrder: 'desc'
})

// 带字段标签的传统WOS查询语法
search_webofscience({
  query: 'TS="machine learning" AND PY=2023 AND DT="Article"',
  maxResults: 20
})

🔧 v0.2.6 改进:

• ✅ 性能优化: 实现了 RequestCache 缓存搜索结果和API响应
• ✅ 可靠性: 添加了 RateLimiter 和 QuotaManager 防止API滥用和429错误
• ✅ 新功能: 添加了 CitationService 和 PDFExtractor 用于未来增强
• ✅ 测试: 将测试套件重组为 tests/platforms, tests/utils, 和 tests/integration
• ✅ 18个字段标签: 完整支持所有WoS Starter API字段标签
• ✅ API版本选择: 支持v1和v2端点
• ✅ 增强过滤: ISSN、卷号、页码、期号、文档类型、PMID过滤器
• ✅ 查询验证: 查询复杂度和注入防护的安全检查

支持的搜索选项: - query: 搜索词 (支持多主题) - year: 单个年份"2023"或范围"2020-2023" - author: 作者名过滤 - journal: 期刊/来源过滤 - sortBy: 排序字段 (date, citations, relevance, title, author, journal) - sortOrder: 排序方向 (asc, desc) - maxResults: 最大结果数 (每页1-50)

支持的WOS字段标签 (共18个): | 标签 | 描述 | 标签 | 描述 | |------|------|------|------| | TS | 主题 (标题、摘要、关键词) | TI | 标题 | | AU | 作者 | AI | 作者标识符 | | SO | 来源/期刊 | IS | ISSN/ISBN | | PY | 发表年份 | FPY | 最终发表年份 | | DO | DOI | DOP | 发表日期 | | VL | 卷号 | PG | 页码 | | CS | 期号 | DT | 文档类型 | | PMID | PubMed ID | UT | 入藏号 | | OG | 机构 | SUR | 来源URL |

字段标签示例: ```typescript // 通过PMID搜索 search_webofscience({ query: 'PMID=12345678' })

// 通过DOI搜索 search_webofscience({ query: 'DO="10.1038/nature12373"' })

// 按文档类型过滤 search_webofscience({ query: 'TS=