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 许可证。