Paper Search MCP Server

# Paper Search MCP 项目详解 > **适合初学者的 MCP (Model Context Protocol) 学习指南** --- ## 目录 1. [什么是 MCP？](#什么是-mcp) 2. [项目概览](#项目概览) 3. [项目架构](#项目架构) 4. [目录结构](#目录结构) 5. [核心组件](#核心组件) 6. [运行方式](#运行方式) 7. [核心依赖](#核心依赖) 8. [如何扩展新平台](#如何扩展新平台) 9. [学习路线图](#学习路线图) --- ## 什么是 MCP？ **MCP (Model Context Protocol)** 是一种开放标准，用于将 AI 模型（如 Claude）与外部工具和数据源连接起来。 ### 类比理解 想象一下： - **LLM (大语言模型)** = 一个非常聪明但"被关在房间里"的人 - **MCP** = 给这个人开了一扇窗户，让他能看到外面的世界并与之互动 - **MCP Server** = 窗户外面的服务员，帮助 LLM 执行实际操作 ### MCP 的关键概念 | 概念 | 说明 | 本项目例子 | |------|------|-----------| | **Server** | 提供工具和资源的服务程序 | `paper_search_server` | | **Tools** | LLM 可以调用的函数 | `search_arxiv`, `download_arxiv` | | **Resources** | LLM 可以读取的数据 | 论文内容、搜索结果 | --- ## 项目概览 `paper-search-mcp` 是一个 MCP 服务器，让 Claude 等 LLM 能够： 1. 🔍 **搜索论文** - 从 arXiv、PubMed、Semantic Scholar 等平台搜索学术论文 2. 📥 **下载 PDF** - 直接下载论文 PDF 文件 3. 📖 **阅读全文** - 提取 PDF 文本内容供 LLM 分析 --- ## 项目架构 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Claude Desktop (LLM 客户端) │ └─────────────────────────────────────────────────────────────────────┘ │ │ MCP Protocol (stdio) │ JSON-RPC 格式通信 ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ FastMCP Server (server.py) │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 暴露的工具 (Tools): │ │ │ │ • search_arxiv() • download_arxiv() • read_arxiv() │ │ │ │ • search_pubmed() • search_semantic() • ... │ │ │ └─────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ │ │ 调用各平台搜索器 ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ 学术平台搜索器 (academic_platforms/) │ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ │ ArxivSearcher │ │ PubMedSearcher │ │SemanticSearcher│ │CrossRefSearcher│ │ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ │ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ │ arXiv API │ │ PubMed API│ │Semantic API│ │CrossRef API│ │ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ └─────────────────────────────────────────────────────────────────────┘ │ │ 统一返回格式 ▼ ┌─────────────────────────────────────────────────────────────────────┐ │ Paper 数据模型 (paper.py) │ │ 所有平台的论文数据都转换为统一的 Paper 对象 │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 目录结构 ``` paper-search-mcp/ │ ├── paper_search_mcp/ # 📦 核心 Python 包 │ ├── __init__.py # 包初始化文件 │ ├── server.py # ⭐ MCP 服务器核心 (必读!) │ ├── paper.py # ⭐ 统一数据模型 (必读!) │ │ │ └── academic_platforms/ # 🔍 各学术平台搜索器 │ ├── __init__.py │ ├── arxiv.py # arXiv 搜索器 │ ├── pubmed.py # PubMed 搜索器 │ ├── biorxiv.py # bioRxiv 搜索器 │ ├── medrxiv.py # medRxiv 搜索器 │ ├── google_scholar.py # Google Scholar 搜索器 │ ├── iacr.py # IACR ePrint 搜索器 │ ├── semantic.py # Semantic Scholar 搜索器 │ ├── crossref.py # CrossRef 搜索器 │ └── hub.py # Sci-Hub (已禁用) │ ├── tests/ # 🧪 测试文件 │ ├── test_server.py │ ├── test_arxiv.py │ └── ... │ ├── docs/ # 📚 文档 │ └── learning/ # 学习资料 (你正在阅读的文件) │ ├── Dockerfile # 🐳 Docker 部署配置 ├── pyproject.toml # 📋 项目配置 (依赖、元数据) ├── smithery.yaml # Smithery 配置 ├── uv.lock # 依赖锁定文件 └── README.md # 项目说明文档 ``` --- ## 核心组件 ### 1. Paper 数据模型 > 📄 详细文档: [01_paper_model.md](./01_paper_model.md) 统一的论文数据结构，所有平台返回的数据都会转换为此格式。 ### 2. MCP Server > 📄 详细文档: [02_server.md](./02_server.md) 使用 FastMCP 框架实现的 MCP 服务器，定义了所有可用的工具。 ### 3. 学术平台搜索器 > 📄 详细文档: > - [03_arxiv_searcher.md](./03_arxiv_searcher.md) > - [04_pubmed_searcher.md](./04_pubmed_searcher.md) > - [05_semantic_searcher.md](./05_semantic_searcher.md) > - [06_crossref_searcher.md](./06_crossref_searcher.md) --- ## 运行方式 ### 方式一：配置 Claude Desktop 编辑 Claude Desktop 配置文件： - **Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "paper_search_server": { "command": "uv", "args": [ "run", "--directory", "/path/to/paper-search-mcp", "-m", "paper_search_mcp.server" ], "env": { "SEMANTIC_SCHOLAR_API_KEY": "" } } } } ``` ### 方式二：本地开发测试 ```bash # 1. 克隆项目 git clone https://github.com/openags/paper-search-mcp.git cd paper-search-mcp # 2. 创建虚拟环境 (使用 uv) uv venv source .venv/bin/activate # Windows: .venv\Scripts\activate # 3. 安装依赖 uv add -e . # 4. 测试单个模块 python paper_search_mcp/academic_platforms/arxiv.py # 5. 运行完整测试 python -m pytest tests/ ``` --- ## 核心依赖 | 包名 | 版本要求 | 用途 | 学习价值 | |------|---------|------|---------| | `fastmcp` | - | FastMCP 框架 | ⭐⭐⭐ MCP 开发核心 | | `mcp[cli]` | >=1.6.0 | MCP 协议支持 | ⭐⭐⭐ MCP 标准库 | | `requests` | - | 同步 HTTP 请求 | ⭐⭐ 基础网络编程 | | `httpx[socks]` | >=0.28.1 | 异步 HTTP + 代理 | ⭐⭐ 现代 HTTP 客户端 | | `feedparser` | - | 解析 Atom/RSS | ⭐ arXiv API 解析 | | `beautifulsoup4` | >=4.12.0 | HTML 解析 | ⭐⭐ 网页爬虫基础 | | `lxml` | >=4.9.0 | 高效 XML/HTML 解析器 | ⭐ BS4 加速 | | `PyPDF2` | >=3.0.0 | PDF 文本提取 | ⭐ PDF 处理 | --- ## 如何扩展新平台 如果你想添加一个新的学术平台（如 IEEE Xplore），只需 3 步： ### 步骤 1: 创建搜索器类 在 `academic_platforms/` 目录下创建 `ieee.py`： ```python from typing import List from ..paper import Paper class PaperSource: """抽象基类""" def search(self, query: str, **kwargs) -> List[Paper]: raise NotImplementedError def download_pdf(self, paper_id: str, save_path: str) -> str: raise NotImplementedError def read_paper(self, paper_id: str, save_path: str) -> str: raise NotImplementedError class IEEESearcher(PaperSource): def search(self, query: str, max_results: int = 10) -> List[Paper]: # 实现搜索逻辑 pass def download_pdf(self, paper_id: str, save_path: str) -> str: raise NotImplementedError("IEEE 不支持直接下载") def read_paper(self, paper_id: str, save_path: str) -> str: return "IEEE 论文需要订阅才能阅读" ``` ### 步骤 2: 在 server.py 中注册 ```python from .academic_platforms.ieee import IEEESearcher ieee_searcher = IEEESearcher() @mcp.tool() async def search_ieee(query: str, max_results: int = 10) -> List[Dict]: """Search IEEE Xplore for papers.""" papers = ieee_searcher.search(query, max_results=max_results) return [paper.to_dict() for paper in papers] ``` ### 步骤 3: 添加测试 在 `tests/` 目录下创建 `test_ieee.py`。 --- ## 学习路线图 作为初学者，建议按以下顺序学习本项目： ``` 1. 阅读本文档 (00_project_overview.md) ↓ 2. 理解数据模型 (01_paper_model.md) ↓ 3. 学习 MCP 服务器 (02_server.md) ← 最重要！ ↓ 4. 研究一个简单搜索器 (03_arxiv_searcher.md) ↓ 5. 研究一个复杂搜索器 (05_semantic_searcher.md) ↓ 6. 尝试自己添加一个新平台 ``` --- ## 下一步 继续阅读详细的代码分析文档： - 📄 [01_paper_model.md](./01_paper_model.md) - Paper 数据模型详解 - 📄 [02_server.md](./02_server.md) - MCP 服务器详解 - 📄 [03_arxiv_searcher.md](./03_arxiv_searcher.md) - arXiv 搜索器详解