Research Extract Pdf Papers

研究摘录pdf论文

MCP服务器，通过模型上下文协议（MCP）接口在arXiv中搜索研究论文，下载其PDF，提取结构化内容，并用语义嵌入对其进行索引。

______________________________________________________________________

目录

1. 项目概述
2. 特性
3. 技术栈与语言构成
4. 仓库结构
5. 安装和设置
6. 用法
7. 配置
8. 测试
9. 故障排除
10. 贡献
11. 许可证
12. 安全和隐私说明

______________________________________________________________________

1.工程概况

研究摘录pdf论文 是基于Python的 模型上下文协议（MCP） 服务器，使AI助手和LLM管道能够：

• 搜索 arXiv适用于任何主题的研究论文。
• 下载并解析 将PDF转换为干净的Markdown文本。
• 块 将提取的文本分成准备嵌入的部分。
• 嵌入 使用可配置的嵌入模型（Google Gemini、Voyage AI或OpenAI）的块。
• 商店 在Redis中嵌入，以便以后进行语义检索。
• 检索 按纸张ID保存纸张元数据。

主要用例

______________________________________________________________________

2.特点

• 🔍 arXiv搜索 --按主题查询arXiv，结果计数可配置；结果以JSON格式保存在本地。
• 📄 PDF提取 --通过HTTP获取PDF，并使用PyMuPDF/pymupdf4llm将其转换为Markdown。
• ✂️ 分段感知分块 --在以下位置拆分纸张 ##-分级标题以生成有意义的文本块。
• 🧮 可插拔嵌入模型 --支持Gemini(gemini-embedding-001)，航行(voyage-3)，以及OpenAI(text-embedding-3-small)通过LiteLLM。
• 🗄️ Redis兼容密钥方案 --块按以下方式键入 `doc:paper:

:chunk:` 为了便于检索。

• ✅ 索引状态跟踪 --本地JSON元数据跟踪论文是否已完全嵌入。
• 🐳 Docker支持 --包括a Dockerfile 用于集装箱化部署。
• 🧪 测试套件 --基于pytest的测试，对所有网络/文件I/O进行模拟。
• 🛠️ Makefile自动化 --一个命令格式、lint、测试和覆盖工作流。

______________________________________________________________________

3.技术栈和语言组成

⚠️ 注： pyproject.toml 声明 requires-python = ">=3.14" 和 .python-version 针 3.14，但是 Dockerfile 目前使用 python:3.12-slim。要获得完全一致的容器构建，请更新 FROM 排队 Dockerfile 到 python:3.14-slim 一旦稳定的图像可用。 |环境| python-dotenv |

______________________________________________________________________

4.存储库结构

research-extract-pdf-papers/
├── research_server.py   # Main MCP server — all tool definitions live here
├── main.py              # Minimal standalone entrypoint (prints hello message)
├── test_server.py       # pytest test suite for research_server.py
├── pyproject.toml       # Project metadata and dependency declarations (uv/pip)
├── uv.lock              # Locked dependency versions for reproducible installs
├── Makefile             # Dev automation: format / lint / test / coverage / clean
├── Dockerfile           # Container build definition
├── .dockerignore        # Files excluded from Docker build context
├── .gitignore           # Git-ignored paths (envs, caches, PDFs, logs)
├── .python-version      # Pinned Python version (3.14, used by pyenv/uv)
├── LICENSE              # MIT License
└── papers/              # Auto-created at runtime; stores per-topic sub-directories
    └── /
        └── papers_info.json  # Metadata for papers found under that topic

密钥文件： research_server.py

包含五个暴露于任何连接的MCP客户端的MCP工具：

______________________________________________________________________

5.安装与设置

先决条件

逐步本地设置

# 1. Clone the repository
git clone https://github.com/Muhammadyousafrana/research-extract-pdf-papers.git
cd research-extract-pdf-papers

# 2. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. Install project dependencies
uv pip install .

# 4. Copy and configure environment variables
cp .env.example .env          # create .env from the example (see Configuration section)
# Edit .env and fill in at least one embedding API key

# 5. Run the MCP server (stdio transport — suitable for MCP clients)
python research_server.py

Docker设置

# Build the image
docker build -t research-mcp .

# Run (pass env vars at runtime)
docker run --rm -e GEMINI_API_KEY=your_key research-mcp

______________________________________________________________________

6.使用方法

运行MCP服务器

服务器使用 stdio传输 并且被设计为连接到MCP兼容客户端（例如Claude Desktop、LLM管道或任何MCP主机）。

python research_server.py

连接后，MCP客户端可以直接调用这些工具。以下是交互示例：

示例：搜索论文

# Via MCP client call
search_papers(topic="retrieval augmented generation", max_results=5)
# Returns: ["2301.07041", "2305.14283", ...]
# Side effect: saves papers/retrieval_augmented_generation/papers_info.json

示例：检索纸张元数据

extract_info(paper_id="2301.07041")
# Returns JSON:
# {
#   "title": "Precise Zero-Shot Dense Retrieval without Relevance Labels",
#   "authors": ["Luyu Gao", "Xueguang Ma", ...],
#   "summary": "...",
#   "pdf_url": "https://arxiv.org/pdf/2301.07041",
#   "published": "2023-01-17",
#   "indexed": false
# }

示例：提取PDF块（索引的第一步）

extract_chunks(
    paper_id="2301.07041",
    pdf_url="https://arxiv.org/pdf/2301.07041"
)
# Returns JSON:
# {
#   "status": "ok",
#   "paper_id": "2301.07041",
#   "total_chunks": 12,
#   "chunks": [
#     {"index": 0, "redis_key": "doc:paper:2301.07041:chunk:0", "text": "..."},
#     ...
#   ]
# }

示例：嵌入块（索引的第2步）

embed_chunk(text="Retrieval-augmented generation combines parametric...")
# Returns JSON:
# {"status": "ok", "vector": [0.012, -0.034, ..., 0.091]}   # 3072 floats (Gemini)

示例：将纸张标记为索引（索引的第3步）

mark_paper_indexed(paper_id="2301.07041")
# Returns: "Paper '2301.07041' marked as indexed."

完整的索引工作流程

1. search_papers(topic)          → get list of paper IDs
2. extract_info(paper_id)        → get pdf_url from metadata
3. extract_chunks(paper_id, url) → get text chunks + redis_key for each
4. For each chunk:
     embed_chunk(chunk.text)     → get vector
     RedisMCPServer:hset(...)    → store text fields
     RedisMCPServer:set_vector_in_hash(...) → store vector
5. mark_paper_indexed(paper_id)  → flag as done

______________________________________________________________________

7.配置

配置通过环境变量提供（自动加载 python-dotenv 如果a .env 文件存在）。

环境变量

创建一个 .env 项目根目录中的文件：

# .env — fill in whichever embedding provider you use
GEMINI_API_KEY=your_gemini_key_here
# VOYAGE_API_KEY=your_voyage_key_here
# OPENAI_API_KEY=your_openai_key_here

嵌入模型选择

主动模型由以下两个常数控制 research_server.py:

# Gemini (default) — 3072 dimensions
EMBEDDING_MODEL = "gemini/gemini-embedding-001"
EMBEDDING_DIMS  = 3072

# Voyage — uncomment to switch
# EMBEDDING_MODEL = "voyage/voyage-3"
# EMBEDDING_DIMS  = 1024

# OpenAI — uncomment to switch
# EMBEDDING_MODEL = "openai/text-embedding-3-small"
# EMBEDDING_DIMS  = 1536

Redis密钥前缀

按键按模式排列 doc:paper: :chunk:.前缀 doc: 可通过配置 REDIS_PREFIX 恒常 research_server.py.

纸张存储目录

下载的纸张元数据存储在 ./papers/ 默认情况下。这是由控制 PAPER_DIR 恒常 research_server.py.

______________________________________________________________________

8.测试

该项目使用 pytest 单元测试在 test_server.py。所有网络和文件I/O都被模拟，因此测试完全脱机运行。

运行测试套件

# Using make (recommended)
make test

# Or directly with pytest
python -m pytest test_server.py -v --tb=short

带覆盖率运行

make coverage
# Opens a full HTML report at htmlcov/index.html

运行格式和linting检查

make format        # auto-format with black
make format-check  # check formatting without changes (suitable for CI)
make lint          # run pylint (fails if score ` 并检查HTTP 200。
- 一些arXiv论文的访问权限受到限制。使用 `/pdf/` URL的变体，而不是抽象页面。

### 下载PDF时出现HTTP错误

**症状：** `{"status": "error", "error": "connection refused"}` 或 `httpx.HTTPStatusError`

**修复：**

- 检查您的互联网连接/公司代理设置。
- arXiv有时会限制快速下载。在通话之间添加一个短暂的延迟。
- 这 `httpx.get` 呼叫使用30秒超时。增加它 `research_server.py` 如果需要： `timeout=60`.

### 嵌入API关键错误

**症状：** `litellm.AuthenticationError` 或类似

**修复：**

- 确保设置了正确的环境变量(`GEMINI_API_KEY`, `VOYAGE_API_KEY`，或 `OPENAI_API_KEY`).
- 确认密钥已加载--添加 `from dotenv import load_dotenv; load_dotenv()` 在...的顶部 `research_server.py` 如果还没有。
- 验证密钥是否有足够的配额/信用。

### `papers_info.json` 未找到

**症状：** `extract_info` 总是回来 `"There's no saved information related to paper ."`

**修复：** 跑 `search_papers` 首先是相关话题。JSON文件是在第一次成功的搜索调用时创建的。

### Python版本不匹配

**症状：** Python\<3.14上的语法错误或导入失败

**修复：** 该项目需要Python 3.14+。使用 `pyenv install 3.14` 或者切换到使用Python 3.12的Docker镜像（调整 `pyproject.toml` `requires-python` 如果你需要以3.12为目标）。

### `uv` 命令未找到

**修复：** 安装 `uv` 与：

curl -LsSf https://astral.sh/uv/install.sh | sh

______________________________________________________________________

## 10.贡献

欢迎投稿！请遵循以下工作流程：

1. **分叉** GitHub上的存储库。
1. **创建分支** 对于您的更改：

git checkout -b feat/my-new-feature

1. **进行更改**，然后运行完整的质量套件：

make # format + lint + test

1. **提交** 带有清晰、描述性的信息：

git commit -m "feat: add support for Semantic Scholar API"

1. **推** 你的分支机构和打开一个 **拉取请求** 反对 `main`.

### 指南

- 保持函数的焦点，并添加/更新文档字符串以匹配。
- 新工具应遵循现有的MCP `@mcp.tool()` 装饰图案。
- 所有新代码都必须包含在测试中 `test_server.py`.
- 跑 `make format-check` 和 `make lint` 在提交之前，CI将强制执行这两项。

______________________________________________________________________

## 11.许可证

该项目根据 **MIT许可证**.\
看 [许可证](LICENSE) 文件全文。

______________________________________________________________________

## 12.安全和隐私说明

### 安全处理PDF

- PDF通过HTTPS获取，并使用PyMuPDF在内存中完全解析——没有临时PDF文件写入磁盘。
- 恶意PDF可以利用PDF解析器漏洞。保持 `pymupdf` / `fitz` 更新到最新版本。
- 不要将不受信任的用户提供的URL直接传递给 `extract_chunks` 未经验证；攻击者可以使服务器向内部网络资源（SSRF）发出请求。添加URL分配（例如限制为 `arxiv.org`)如果服务器暴露于不可信的输入。

### API密钥和秘密

- 永不承诺 `.env` 文件或版本控制的API密钥。 `.env` 已在中列出 `.gitignore`.
- 旋转任何意外暴露的按键。
- 使用特定于环境的机密管理（例如Docker机密、GitHub Actions机密），而不是简单的 `.env` 生产中的文件。

### 论文中的敏感数据

- 下载的纸质文本可能包括姓名、机构隶属关系和其他个人身份信息。如果您的用例再次暴露了这些数据，请根据适用的数据保护法规（GDPR等）处理提取的内容。
- 在生产部署中，应使用身份验证和TLS保护存储在Redis中的嵌入向量。

### 依赖安全

- 依赖关系已锁定 `uv.lock` 为了可重复性。
- 定期审核依赖关系 `uv pip check` 或工具，例如 `pip-audit`.