Crossref Cite MCP

🚀 Crossref Cite MCP 服務器

Crossref Cite MCP 服務器是一個基於 模型上下文協議（MCP） 的服務器，它藉助 Crossref API 來解析論文引用。該服務器支持多種輸出格式，包括 CSL-JSON、BibTeX、RIS 和格式化文本，適用於像 Claude Desktop、Cursor 等大語言模型工具。

中文文檔

✨ 主要特性

• 🔍 智能輸入解析：可自動檢測 DOI、arXiv ID、PMID，若未匹配到則進行文獻搜索。
• 📚 多種引用格式：支持 CSL-JSON、BibTeX、RIS 和格式化文本（如 APA、芝加哥、IEEE 等格式）。
• ⚡ 內置緩存：支持內存或 JSON 文件緩存，可配置過期時間（默認 14 天）。
• 🔄 重試邏輯：針對速率限制（429）和服務器錯誤（5xx）採用指數退避策略。
• 🎯 禮貌池支持：使用 mailto 參數以獲取更高的 Crossref 速率限制。

📦 安裝指南

從 PyPI 安裝（推薦）

# 使用 uv（推薦）
uv pip install crossref-cite-mcp

# 或者使用 pip
pip install crossref-cite-mcp

從源碼安裝（用於開發）

# 克隆倉庫
git clone https://github.com/h-lu/crossref-cite-mcp.git
cd crossref-cite-mcp

# 使用 uv 安裝
uv pip install -e .

# 或者使用 pip
pip install -e .

🔧 配置

設置環境變量（或創建 .env 文件）：

# 必需：用於 Crossref 禮貌池的電子郵件
export CROSSREF_MAILTO=your-email@example.com

# 可選：緩存配置
export CROSSREF_CACHE_BACKEND=json        # "memory" 或 "json"
export CROSSREF_CACHE_PATH=~/.crossref-cite/cache.json
export CROSSREF_CACHE_TTL=1209600         # 14 天，以秒為單位

# 可選：日誌記錄
export LOG_LEVEL=INFO

🔧 配置 Claude Desktop

編輯 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

使用 uvx（推薦，無需預先安裝）

{
  "mcpServers": {
    "crossref-cite": {
      "command": "uvx",
      "args": ["crossref-cite-mcp"],
      "env": {
        "CROSSREF_MAILTO": "your-email@example.com"
      }
    }
  }
}

使用 pip 安裝的包

{
  "mcpServers": {
    "crossref-cite": {
      "command": "crossref-cite-mcp",
      "args": [],
      "env": {
        "CROSSREF_MAILTO": "your-email@example.com"
      }
    }
  }
}

開發環境（從源碼使用 uv）

{
  "mcpServers": {
    "crossref-cite": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/crossref-cite-mcp", "python", "-m", "crossref_cite"],
      "env": {
        "CROSSREF_MAILTO": "your-email@example.com"
      }
    }
  }
}

💻 使用示例

可用工具

resolve_citation

解析論文並返回多種格式的引用。

參數：

• query（必需）：論文標題、DOI、arXiv ID 或 PMID。
• formats：格式列表（["csl-json", "bibtex", "ris", "formatted"]）。
• style：格式化輸出的 CSL 樣式（默認："apa"）。
• locale：格式化輸出的語言環境（默認："en-US"）。
• rows：Crossref 候選結果數量（默認：5）。

示例：

{
  "query": "Attention Is All You Need",
  "formats": ["bibtex", "formatted"],
  "style": "apa"
}

search_papers

在 Crossref 中搜索論文（僅獲取元數據，不獲取引用）。

參數：

• query（必需）：搜索查詢。
• rows：結果數量（默認：10，最大：20）。
• filter_from_year：出版年份過濾（開始）。
• filter_to_year：出版年份過濾（結束）。
• filter_type：作品類型過濾（例如，"journal-article"）。

直接 CLI 測試

# 使用 JSON-RPC 請求進行測試
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"resolve_citation","arguments":{"query":"10.1038/nature12373","formats":["bibtex"]}}}' | python -m crossref_cite

🔨 開發

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

# 運行測試
pytest tests/ -v

# 運行測試並統計覆蓋率
pytest tests/ -v --cov=crossref_cite

# 代碼檢查
ruff check src tests

# 類型檢查
mypy src/crossref_cite

錄製 VCR 盒式磁帶

要為測試錄製新的 HTTP 交互盒式磁帶：

# 刪除現有盒式磁帶並重新錄製
rm -rf tests/cassettes/
pytest tests/ -v --vcr-record=new_episodes

🐳 Docker

# 構建鏡像
docker build -t crossref-cite-mcp .

# 運行
docker run -e CROSSREF_MAILTO=your-email@example.com crossref-cite-mcp

📚 詳細文檔

Crossref 最佳實踐

此實現遵循 Crossref REST API 最佳實踐：

• ✅ 使用 mailto 參數進行禮貌池訪問。
• ✅ 針對速率限制實現指數退避策略。
• ✅ 緩存結果以減少冗餘請求。
• ✅ 使用 query.bibliographic 進行類似引用的搜索。

內容協商

通過 DOI 內容協商 獲取引用格式：

📄 許可證

本項目採用 MIT 許可證。