Unpaywall MCP

🚀 Unpaywall MCP 服務器

Unpaywall MCP 服務器通過 MCP（模型上下文協議）暴露 Unpaywall 工具，使 AI 客戶端能夠：

• 通過 DOI 獲取元數據
• 搜索文章標題
• 獲取最佳的開放獲取全文鏈接
• 下載開放獲取的 PDF 並提取文本

🚀 快速開始

使用 npx 快速啟動

將以下內容添加到你的 MCP 客戶端配置中（以 Claude Desktop 為例）：

{
  "mcpServers": {
    "unpaywall": {
      "command": "npx",
      "args": ["-y", "unpaywall-mcp"],
      "env": { "UNPAYWALL_EMAIL": "you@example.com" }
    }
  }
}

然後嘗試使用這些工具：unpaywall_search_titles、unpaywall_get_fulltext_links、unpaywall_fetch_pdf_text。

📦 安裝指南

系統要求

• Node.js 18 及以上版本
• 一個用於 Unpaywall 請求的電子郵件地址（Unpaywall 要求提供該地址以確保禮貌使用）

安裝步驟

# 安裝依賴
npm install

# 構建項目
npm run build

# 運行項目（使用 stdio 傳輸，這是 MCP 客戶端所要求的）
UNPAYWALL_EMAIL=you@example.com npm start

如果你想在開發環境中使用熱加載（無需構建步驟），可以運行以下命令：

UNPAYWALL_EMAIL=you@example.com npm run dev

💻 使用示例

工具調用示例

根據你的 MCP 客戶端不同，結構可能會有所不同，但核心負載如下：

// 搜索標題
{
  "name": "unpaywall_search_titles",
  "arguments": {
    "query": "graph neural networks survey",
    "is_oa": true,
    "page": 1
  }
}

// 獲取 DOI 的最佳開放獲取鏈接
{
  "name": "unpaywall_get_fulltext_links",
  "arguments": {
    "doi": "10.48550/arXiv.1812.08434"
  }
}

// 獲取並提取 PDF 文本（通過 DOI）
{
  "name": "unpaywall_fetch_pdf_text",
  "arguments": {
    "doi": "10.48550/arXiv.1812.08434",
    "truncate_chars": 20000
  }
}

在 MCP 客戶端中配置

推薦配置（無需構建）

使用 npm/npx 為 Claude Desktop 進行配置：

{
  "mcpServers": {
    "unpaywall": {
      "command": "npx",
      "args": ["-y", "unpaywall-mcp"],
      "env": {
        "UNPAYWALL_EMAIL": "you@example.com"
      }
    }
  }
}

替代配置（本地倉庫）

使用編譯後的 dist 文件進行配置：

{
  "mcpServers": {
    "unpaywall": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "UNPAYWALL_EMAIL": "you@example.com"
      }
    }
  }
}

添加配置後，讓你的客戶端列出工具並嘗試以下操作：

• 使用 query 參數調用 unpaywall_search_titles
• 使用 doi 參數調用 unpaywall_get_fulltext_links
• 使用 doi（或 pdf_url）參數調用 unpaywall_fetch_pdf_text

📚 詳細文檔

工具說明

unpaywall_get_by_doi

• 描述：通過 DOI 獲取 Unpaywall 元數據
• 輸入參數：
  • doi（字符串，必填）：例如 10.1038/nphys1170
  • email（字符串，可選）：如果提供，將覆蓋 UNPAYWALL_EMAIL 環境變量
• 輸出：來自 Unpaywall 的 JSON 響應

unpaywall_search_titles

• 描述：在 Unpaywall 中搜索與查詢匹配的文章標題（每頁 50 條結果）
• 輸入參數：
  • query（字符串，必填）：標題查詢字符串
  • is_oa（布爾值，可選）：如果為 true，僅返回開放獲取的結果；如果為 false，僅返回封閉訪問的結果；不提供則返回所有結果
  • page（整數，大於等於 1，可選）：頁碼
  • email（字符串，可選）：覆蓋 UNPAYWALL_EMAIL 環境變量
• 輸出：來自 GET https://api.unpaywall.org/v2/search 的 JSON 搜索結果

unpaywall_get_fulltext_links

• 描述：返回 DOI 的最佳開放獲取 PDF URL 和開放 URL，以及所有開放獲取的位置
• 輸入參數：
  • doi（字符串，必填）
  • email（字符串，可選）：覆蓋 UNPAYWALL_EMAIL 環境變量
• 輸出：包含以下字段的 JSON：best_pdf_url、best_open_url、best_oa_location、oa_locations 以及部分元數據

unpaywall_fetch_pdf_text

• 描述：下載並提取 DOI 的最佳開放獲取 PDF 文本，或從提供的 pdf_url 中提取文本
• 輸入參數：
  • pdf_url（字符串，可選）：直接的 PDF URL（優先使用）
  • doi（字符串，可選）：如果未提供 pdf_url，則用於解析最佳開放獲取 PDF
  • email（字符串，可選）：如果使用 doi 且未設置 UNPAYWALL_EMAIL 環境變量，則為必填項
  • truncate_chars（整數，大於等於 1000，可選）：返回的提取文本的最大字符數（默認 20000）
• 輸出：包含 text（可能被截斷）、length_chars、truncated、pdf_url 以及 PDF 元數據的 JSON

LLM 提示技巧（MCP）

當從支持 MCP 的 LLM 客戶端使用此服務器時，建議向模型提出以下要求：

• 先搜索再獲取：使用 unpaywall_search_titles 輸入簡潔的標題短語進行搜索；選擇一個結果；然後對所選的 DOI 調用 unpaywall_get_fulltext_links 或 unpaywall_fetch_pdf_text。
• 優先選擇開放獲取：當你只需要開放獲取的資源時，在搜索中傳遞 is_oa: true。
• 控制文本大小：在 unpaywall_fetch_pdf_text 中設置 truncate_chars（默認 20000），並在處理長文本之前進行總結。
• 保持彈性：如果最佳 PDF URL 缺失，可以回退到 best_open_url 並從著陸頁提取內容（此操作在本服務器之外）。
• 遵守速率限制：如果進行多次調用，請合理安排請求時間；重用之前的響應，而不是重複相同的調用。

以下是一些給 LLM 的良好用戶指令示例：

• "查找 3 篇關於 '生物醫學基礎模型' 的開放獲取論文，然後提取並總結其中最佳論文的引言部分。"
• "搜索 '2024 年圖神經網絡綜述'，儘可能篩選出開放獲取的結果，然後獲取 PDF 文本並生成一個 10 點的總結。"

🔧 技術細節

維護者發佈到 npm 的步驟

# 1) 構建項目（發佈時也會自動運行）
npm run build

# 2) 提升版本號（選擇 patch/minor/major）
npm version patch

# 3) 發佈（確保你已登錄：npm login）
npm publish --access public

# 4) 在 GitHub 上標記發佈版本（可選，推薦）

用戶可以按照上述方式使用 npx -y unpaywall-mcp 配置他們的 MCP 客戶端，無需克隆或構建項目。

📄 許可證

請參考項目中的 LICENSE 文件獲取詳細的許可證信息。

⚠️ 重要提示

• 請遵守 Unpaywall 的速率限制和使用指南：https://unpaywall.org/products/api
• 本服務器使用 stdio 傳輸和 @modelcontextprotocol/sdk。
• 請設置 UNPAYWALL_EMAIL 環境變量或在每次調用時傳遞 email 參數，以便 Unpaywall 可以就使用情況與你聯繫。