MCP 文献检索服务器

🔬 基于FastMCP框架开发的专业文献检索工具，无缝集成AI助手如Claude Desktop和Cherry Studio

🚀 快速开始

0️⃣ 安装UV工具

# 安装 uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

one️⃣ 安装依赖

方法1：直接使用PyPI包（推荐）

# 直接运行，无需安装依赖
uvx article-mcp server

方法2：本地开发环境

# 克隆项目到本地
git clone https://github.com/gqy20/article-mcp.git
cd article-mcp

# 安装项目依赖
uv sync

# 或使用 pip 安装依赖
pip install fastmcp requests python-dateutil aiohttp markdownify

two️⃣ 启动服务器

使用PyPI包（推荐）

# 直接运行 PyPI 包
uvx article-mcp server

本地开发

# 启动 MCP 服务器 (推荐新入口点)
uv run python -m article_mcp server

# 或使用 Python
python -m article_mcp server

# 兼容性入口点 (仍然支持)
uv run main.py server
python main.py server

three️⃣ 配置AI客户端

Claude Desktop 配置

编辑Claude Desktop配置文件并添加：

方法1：使用PyPI包（推荐）

{
  "mcpServers": {
    "article-mcp": {
      "command": "uvx",
      "args": [
        "article-mcp",
        "server"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

方法2：本地开发

{
  "mcpServers": {
    "article-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/article-mcp",
        "main.py",
        "server"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Cherry Studio 配置

{
  "mcpServers": {
    "article-mcp": {
      "command": "uvx",
      "args": [
        "article-mcp",
        "server",
        "--transport",
        "stdio"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

four️⃣ 开始使用

完成配置后，重启您的AI客户端以使用以下功能：

• 🔍 多来源文献检索（search_literature)
• 📄 获取文献详细信息（get_article_details)
• 📚 获取参考文献（get_references)
• 🔗 文献关系分析（get_literature_relations)
• ⭐ 期刊质量评估（get_journal_quality)
• 📊 批量结果导出（export_batch_results)

---

📋 功能列表

🔍 核心搜索工具

工具名称	功能描述	主要参数
search_literature	多来源文献检索工具。搜索学术数据库文献，支持关键词搜索和结果合并。	keyword, sources[], max_results, search_type
get_article_details	获取文献详细信息的工具。通过DOI和PMID等标识符获取文献的详细信息。	identifier, id_type, sources[], include_quality_metrics

📚 参考文献工具

工具名称	功能描述	主要参数
get_references	获取参考文献工具。通过文献标识符获取完整的参考文献列表。	identifier, id_type, sources[], max_results, include_metadata

🔗 文献关系分析工具

工具名称	功能描述	主要参数
get_literature_relations	文献关系分析工具。分析文献之间的引用关系、相似性和合作网络。	identifier/identifiers, id_type, relation_types[], max_results, analysis_type

⭐ 质量评估工具

工具名称	功能描述	主要参数
get_journal_quality	期刊质量评估工具。评估期刊的学术质量和影响指标。	journal_name, operation, evaluation_criteria[], include_metrics[]

📊 批量处理工具

工具名称	功能描述	主要参数
export_batch_results	通用结果导出工具。将批量处理结果导出为JSON或CSV格式文件。	results, format_type, output_path, include_metadata

---

⚡ 性能特点

• 🚀 高性能并行处理 -比传统方法快30-50%
• 💾 智能缓存机制 -24小时本地缓存，避免重复请求
• 🔄 批量处理优化 -支持同时处理最多20个DOI
• 🛡️ 自动重试机制 -网络异常自动重试
• 📊 详细的性能统计 -实时监控API调用

---

🔧 高级配置

环境变量

export PYTHONUNBUFFERED=1     # 禁用Python输出缓冲
export UV_LINK_MODE=copy      # uv链接模式(可选)
export EASYSCHOLAR_SECRET_KEY=your_secret_key  # EasyScholar API密钥(可选)

MCP配置集成（v0.1.1 新特性）

现在支持从MCP客户端配置文件中读取EasyScholar API密钥，而无需通过环境变量传递。

Claude Desktop 配置

编辑 ~/.config/claude-desktop/config.json 文件：

{
  "mcpServers": {
    "article-mcp": {
      "command": "uvx",
      "args": ["article-mcp", "server"],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "EASYSCHOLAR_SECRET_KEY": "your_easyscholar_api_key_here"
      }
    }
  }
}

密钥优先级

1. MCP配置文件中的密钥（最高优先级）
2. 函数参数中的密钥
3. 环境变量中的密钥

支持的工具

• get_journal_quality -获取期刊质量评估信息
• evaluate_articles_quality -批量评估文献的期刊质量

完成配置后，重启MCP客户端以生效。

传输模式

# STDIO 模式 (推荐用于桌面AI客户端)
uv run python -m article_mcp server --transport stdio

# SSE 模式 (用于Web应用)
uv run python -m article_mcp server --transport sse --host 0.0.0.0 --port 9000

# HTTP 模式 (用于API集成)
uv run python -m article_mcp server --transport streamable-http --host 0.0.0.0 --port 9000

API限制与优化

• Crossref API每秒50次请求（建议提供电子邮件地址以获得更高的限制）
• Europe PMC API每秒1次请求（保守策略）
• arXiv API每次请求3秒（官方限制）

---

🛠️ 开发与测试

运行测试

该项目提供了一整套测试来验证功能：

# 核心功能测试（推荐日常使用）
uv run python scripts/test_working_functions.py

# 快速测试（功能验证）
uv run python scripts/quick_test.py

# 完整测试套件
uv run python scripts/run_all_tests.py

# 分类测试
uv run python scripts/test_basic_functionality.py  # 基础功能测试
uv run python scripts/test_cli_functions.py       # CLI功能测试
uv run python scripts/test_service_modules.py     # 服务模块测试
uv run python scripts/test_integration.py         # 集成测试
uv run python scripts/test_performance.py         # 性能测试

项目信息

# 查看项目信息
uv run python -m article_mcp info

# 或使用 PyPI 包
uvx article-mcp info

# 查看帮助
uv run python -m article_mcp --help

故障排除

问题	解决方案
无法导入名为 'hdrs' 的 'aiohttp'	运行 uv sync --upgrade 更新依赖
MCP服务器启动失败	检查路径配置，确保使用绝对路径
API请求失败	提供电子邮件地址并检查网络连接
找不到uv命令	使用完整路径~/.local/bin/uv

项目结构

article-mcp/
├── main.py              # 兼容性入口文件（向后兼容）
├── pyproject.toml       # 项目配置文件
├── README.md            # 项目文档
├── src/                 # 源代码根目录
│   └── article_mcp/     # 主包（标准Python src布局）
│       ├── __init__.py  # 包初始化
│       ├── cli.py       # CLI入口点和MCP服务器创建
│       ├── __main__.py  # Python模块执行入口
│       ├── services/    # 服务层
│       │   ├── europe_pmc.py              # Europe PMC API 集成
│       │   ├── arxiv_search.py            # arXiv 搜索服务
│       │   ├── pubmed_search.py           # PubMed 搜索服务
│       │   ├── reference_service.py       # 参考文献管理
│       │   ├── literature_relation_service.py # 文献关系分析
│       │   ├── crossref_service.py        # Crossref 服务
│       │   ├── openalex_service.py        # OpenAlex 服务
│       │   ├── api_utils.py               # API 工具类
│       │   ├── mcp_config.py              # MCP 配置管理
│       │   ├── error_utils.py             # 错误处理工具
│       │   ├── html_to_markdown.py        # HTML 转换工具
│       │   ├── merged_results.py          # 结果合并工具
│       │   └── similar_articles.py        # 相似文章工具
│       ├── tools/       # 工具层（MCP工具注册）
│       │   ├── core/                      # 核心工具模块
│       │   │   ├── search_tools.py        # 搜索工具注册
│       │   │   ├── article_tools.py       # 文章工具注册
│       │   │   ├── reference_tools.py     # 参考文献工具注册
│       │   │   ├── relation_tools.py      # 关系分析工具注册
│       │   │   ├── quality_tools.py       # 质量评估工具注册
│       │   │   └── batch_tools.py         # 批量处理工具注册
│       │   ├── article_detail_tools.py    # 文章详情工具
│       │   ├── quality_tools.py           # 质量工具
│       │   ├── reference_tools.py         # 参考文献工具
│       │   ├── relation_tools.py          # 关系工具
│       │   └── search_tools.py            # 搜索工具
│       └── legacy/       # 向后兼容模块
│           └── __init__.py
├── src/resource/        # 资源文件目录
│   └── journal_info.json  # 期刊信息缓存
├── tests/               # 测试套件
│   ├── unit/            # 单元测试
│   ├── integration/     # 集成测试
│   └── utils/           # 测试工具
├── scripts/             # 测试脚本
│   ├── test_working_functions.py  # 核心功能测试
│   ├── test_basic_functionality.py # 基础功能测试
│   ├── test_cli_functions.py      # CLI功能测试
│   ├── test_service_modules.py    # 服务模块测试
│   ├── test_integration.py        # 集成测试
│   ├── test_performance.py        # 性能测试
│   ├── run_all_tests.py           # 完整测试套件
│   └── quick_test.py              # 快速测试
└── docs/                # 文档目录

---

📄 返回数据格式

每篇文章包含以下标准字段：

{
  "pmid": "文献ID",
  "title": "文献标题",
  "authors": ["作者1", "作者2"],
  "journal_name": "期刊名称",
  "publication_date": "发表日期",
  "abstract": "摘要",
  "doi": "DOI标识符",
  "pmid_link": "文献链接"
}

---

📦 发布管理

PyPI 包发布

该项目已发布到PyPI，并可通过uvx命令直接运行：

# 从PyPI安装后直接运行（推荐）
uvx article-mcp server

# 或先安装后运行
pip install article-mcp
article-mcp server

# 本地开发测试
uvx --from . article-mcp server

配置说明

有三种推荐配置方式：

🥇 方案1：使用PyPI包（推荐）

这是最简单且推荐的方式，直接使用发布的PyPI包：

{
  "mcpServers": {
    "article-mcp": {
      "command": "uvx",
      "args": [
        "article-mcp",
        "server"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

🥈 方案2：本地开发

如果您想运行本地代码或进行开发：

{
  "mcpServers": {
    "article-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/article-mcp",
        "python",
        "-m",
        "article_mcp",
        "server"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

🥉 方案3：Cherry Studio 配置

针对Cherry Studio的具体配置：

{
  "mcpServers": {
    "article-mcp": {
      "command": "uvx",
      "args": [
        "article-mcp",
        "server",
        "--transport",
        "stdio"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

发布说明

• PyPI 包名：article-mcp
• 版本控制统一使用语义化版本控制
• 自动更新使用 @latest 标签确保获取最新版本

---

📜 许可证

本项目遵循MIT许可证 - 详情见LICENSE文档。

---

🤝 贡献

欢迎提交Issue和Pull Requests！

1. Fork项目
2. 创建一个功能性分支（git checkout -b feature/AmazingFeature)
3. 提交更改（git commit -m 'Add some AmazingFeature')
4. 推送到分支（git push origin feature/AmazingFeature)
5. 打开Pull Request

---

📞 支持

• 📧 提交Issue：GitHub Issues
• 📚 文档：查看README和源码注释
• 💬 讨论：GitHub Discussions

---

📖 使用示例

多来源文献检索

{
  "keyword": "机器学习癌症检测",
  "sources": ["europe_pmc", "pubmed", "arxiv"],
  "max_results": 20,
  "search_type": "comprehensive"
}

获取文献详细信息（通过DOI）

{
  "identifier": "10.1000/xyz123",
  "id_type": "doi",
  "sources": ["europe_pmc", "crossref"],
  "include_quality_metrics": true
}

获取文献详细信息（通过PMID）

{
  "identifier": "12345678",
  "id_type": "pmid",
  "sources": ["europe_pmc"],
  "include_quality_metrics": false
}

获取参考文献

{
  "identifier": "10.1000/xyz123",
  "id_type": "doi",
  "sources": ["europe_pmc", "crossref"],
  "max_results": 50,
  "include_metadata": true
}

文献关系分析（单篇文献）

{
  "identifier": "10.1000/xyz123",
  "id_type": "doi",
  "relation_types": ["references", "similar", "citing"],
  "max_results": 20,
  "analysis_type": "basic"
}

文献关系分析（批量分析）

{
  "identifiers": ["10.1000/xyz123", "10.1000/abc456"],
  "id_type": "doi",
  "relation_types": ["references", "similar"],
  "max_results": 15,
  "analysis_type": "basic"
}

期刊质量评估

{
  "journal_name": "自然",
  "operation": "quality",
  "evaluation_criteria": ["影响因子", "四分位数", "JCI"],
  "include_metrics": ["影响因子",