Semanticscholarmcp

🚀 語義學者MCP服務器

語義學者MCP服務器是一個模型上下文協議（MCP）服務器，它提供對語義學者學術圖譜API的訪問。藉助該服務器，你可以搜索學術論文、作者，還能獲取有關引用和參考文獻的詳細信息。

🚀 快速開始

此MCP服務器能讓你輕鬆訪問語義學者學術圖譜API，搜索學術資源並獲取詳細信息。你可按以下步驟進行安裝和配置。

✨ 主要特性

• 論文搜索：使用各種過濾器搜索學術論文。
• 論文詳情：獲取特定論文的詳細信息。
• 批量論文檢索：一次性獲取多篇論文的信息。
• 作者搜索：按姓名查找作者。
• 作者詳情：獲取作者的詳細信息及其發表的論文。
• 引用分析：獲取引用特定論文的其他論文。
• 參考文獻分析：獲取特定論文引用的其他論文。
• 引用上下文：獲取一篇論文引用另一篇論文的上下文。
• 文本片段搜索：在學術論文中搜索文本片段。
• PDF下載：以合適的文件名和元數據下載開放獲取的PDF文件。
• PDF可用性檢查：在下載前檢查PDF文件是否可用。
• 智能命名：以論文標題和年份作為文件名保存PDF文件。
• 元數據支持：在PDF文件屬性中嵌入標題、作者和年份信息。

📦 安裝指南

1. 克隆此倉庫：

git clone <repository-url>
cd SemanticScholarMCP

2. 安裝依賴項：

pip install -r requirements.txt

3. （可選但推薦）設置你的語義學者API密鑰：

export SEMANTIC_SCHOLAR_API_KEY="your-api-key-here"

注意：API密鑰是可選的。即使不設置，服務器也能正常工作，但你將共享公共速率限制（所有未認證用戶每秒最多1000個請求）。

4. （可選）安裝PDF元數據支持：

pip install -e ".[metadata]"

📚 詳細文檔

開發

設置開發環境

# 安裝開發依賴項
pip install -e ".[test,dev]"

運行測試

# 運行所有測試
make test

# 僅運行單元測試（快速，無API調用）
make test-unit

# 運行集成測試（需要API密鑰）
export SEMANTIC_SCHOLAR_API_KEY="your-api-key"
make test-integration

# 運行性能測試
make test-performance

代碼質量

# 運行代碼檢查
make lint

# 格式化代碼
make format

配置

將此服務器添加到你的MCP客戶端配置中：

{
  "mcpServers": {
    "SemanticScholarMCP": {
      "command": "/Users/your-username/Desktop/SemanticScholarMCP/venv/bin/python",
      "args": ["/Users/your-username/Desktop/SemanticScholarMCP/src/semantic_scholar_mcp/server.py"],
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}

無API密鑰的配置（共享公共速率限制）：

{
  "mcpServers": {
    "SemanticScholarMCP": {
      "command": "/Users/your-username/Desktop/SemanticScholarMCP/venv/bin/python",
      "args": ["/Users/your-username/Desktop/SemanticScholarMCP/src/semantic_scholar_mcp/server.py"]
    }
  }
}

重要提示：

• 請將 your-username 替換為你實際的用戶名。
• API密鑰是可選的，但推薦使用以獲得更高的速率限制。
• 無API密鑰：所有用戶共享公共速率限制（每秒1000個請求）。
• 使用免費API密鑰：你將擁有更高的專屬速率限制。

可用工具

論文工具

search_papers

使用各種過濾器搜索學術論文。

參數：

• query（必需）：搜索查詢字符串。
• limit：最大結果數（默認：10，最大：100）。
• offset：跳過的結果數（默認：0）。
• fields：要返回的字段列表，以逗號分隔。
• publication_types：按出版類型過濾。
• open_access_pdf：過濾具有開放獲取PDF的論文。
• min_citation_count：最小引用次數。
• year：出版年份或年份範圍（例如，"2020 - 2023"）。
• venue：出版場所。

get_paper

獲取特定論文的詳細信息。

參數：

• paper_id（必需）：論文ID（語義學者ID、DOI、arXiv ID等）。
• fields：要返回的字段列表，以逗號分隔。

get_paper_batch

在單個請求中獲取多篇論文的信息。

參數：

• paper_ids（必需）：論文ID列表，以逗號分隔。
• fields：要返回的字段列表，以逗號分隔。

作者工具

search_authors

按姓名搜索作者。

參數：

• query（必需）：作者姓名或搜索查詢。
• limit：最大結果數（默認：10，最大：1000）。
• offset：跳過的結果數（默認：0）。
• fields：要返回的字段列表，以逗號分隔。

get_author

獲取特定作者的詳細信息。

參數：

• author_id（必需）：作者ID。
• fields：要返回的字段列表，以逗號分隔。

引用和參考文獻工具

get_paper_citations

獲取引用特定論文的其他論文。

參數：

• paper_id（必需）：要獲取引用的論文ID。
• limit：最大結果數（默認：10，最大：1000）。
• offset：跳過的結果數（默認：0）。
• fields：要返回的字段列表，以逗號分隔。

get_paper_references

獲取特定論文引用的其他論文。

參數：

• paper_id（必需）：要獲取參考文獻的論文ID。
• limit：最大結果數（默認：10，最大：1000）。
• offset：跳過的結果數（默認：0）。
• fields：要返回的字段列表，以逗號分隔。

get_citation_context

獲取一篇論文引用另一篇論文的上下文。

參數：

• paper_id（必需）：被引用論文的ID。
• citing_paper_id（必需）：引用論文的ID。

文本搜索工具

search_snippets

在學術論文中搜索文本片段。

參數：

• query（必需）：文本片段搜索查詢。
• limit：最大結果數（默認：10，最大：100）。
• offset：跳過的結果數（默認：0）。

PDF工具

get_paper_pdf_info

檢查論文的PDF可用性。

參數：

• paper_id（必需）：要檢查PDF可用性的論文ID。

download_paper_pdf

如果論文的PDF可用，則下載該PDF，使用論文標題作為文件名並設置元數據。

參數：

• paper_id（必需）：要下載PDF的論文ID。
• download_path：保存PDF的目錄（默認：~/Downloads/semantic_scholar_papers）。

特性：

• 使用論文標題作為文件名（例如，"Machine Learning in Healthcare (2023).pdf"）。
• 在PDF元數據中設置標題、作者和出版年份。
• 自動處理重複文件名。
• 創建有組織的文件夾結構。

💻 使用示例

搜索機器學習相關論文

search_papers("machine learning", limit=5, year="2023")

獲取特定論文的詳細信息

get_paper("10.1038/nature14539")

查找引用特定論文的其他論文

get_paper_citations("10.1038/nature14539", limit=10)

搜索作者

search_authors("Geoffrey Hinton")

獲取引用上下文

get_citation_context("paper-id-1", "paper-id-2")

檢查PDF可用性

get_paper_pdf_info("10.1038/nature14539")

下載論文PDF

download_paper_pdf("10.1038/nature14539")

這將保存PDF文件，文件名類似：

"Deep learning (2015).pdf"

文件中嵌入了包括標題、作者（LeCun, Y., Bengio, Y., Hinton, G.）和年份（2015）的元數據。

API速率限制

語義學者API有以下速率限制：

• 無API密鑰：所有未認證用戶共享每秒1000個請求的速率限制（在高流量時可能會受到限制）。
• 使用免費API密鑰：你將擁有更高的專屬速率限制。

為確保性能穩定，建議獲取免費API密鑰。

🔧 技術細節

故障排除

速率限制錯誤

如果你看到以下錯誤：

Error: Rate limit exceeded. Please wait a moment and try again, or get an API key for higher limits.

這意味著你已達到共享公共速率限制，或者由於高流量API受到限制。

即時解決方案：

1. 獲取免費API密鑰（推薦）：

   • 訪問 https://www.semanticscholar.org/product/api 。
   • 註冊免費賬戶。
   • 獲取你的API密鑰。
   • 將其添加到你的Claude桌面配置中：

   "env": {
     "SEMANTIC_SCHOLAR_API_KEY": "your-actual-api-key-here"
   }
   

   • 重啟Claude桌面應用。

2. 等待並重試：共享公共速率限制可能只是暫時超出。

3. 使用較小的結果限制：減少查詢中的 limit 參數。

4. 分散請求：避免連續快速發出多個請求。

配置問題

• 確保配置中的Python路徑指向正確的虛擬環境。
• 驗證服務器腳本路徑是否正確。
• 檢查虛擬環境中是否安裝了所有依賴項。

測試連接

你可以通過讓Claude以較小的限制搜索單篇論文來測試服務器是否正常工作：

search_papers("machine learning", limit=1)

錯誤處理

所有工具都包含全面的錯誤處理，如果請求失敗或API返回錯誤，將返回詳細的錯誤消息。

📄 許可證

本項目採用MIT許可證 - 詳情請參閱 LICENSE 文件。

🤝 貢獻

歡迎貢獻代碼！請隨時提交拉取請求。