# ArXiv MCP Server

通过 Model Context Protocol (MCP) 为 AI 助手提供与 arXiv 研究库的桥梁，支持搜索论文和访问其内容。

## 致谢

本项目基于 [blazickjp/arxiv-mcp-server](https://github.com/blazickjp/arxiv-mcp-server) 进行修改和优化，感谢原作者的卓越贡献。

## 与原项目的区别

- **下载逻辑优化**：移除了 `paper.md` 中间文件的生成流程，改为直接从源文件读取内容（优先 LaTeX，否则 PDF）
- **双格式下载**：同时下载 LaTeX 源文件和 PDF 文件，而不是只下载一种格式
- **API 重试机制**：添加了针对 arXiv API 速率限制（HTTP 429）的自动重试机制，最多重试 3 次
- **简化功能**：移除了 `list_papers` 工具和 `prompts` 功能，专注于核心的搜索、下载和读取功能

## 功能

- **论文搜索**：查询 arXiv 论文，支持日期范围和分类过滤
- **论文下载**：同时下载 LaTeX 源文件和 PDF 文件
- **智能缓存**：基于 arXiv ID 自动检测是否已下载，避免重复下载
- **论文读取**：直接从源文件读取论文内容（LaTeX 或 PDF）
- **代码检测**：自动检测开源代码仓库（GitHub、GitLab、HuggingFace 等）

## 安装

```bash
# 克隆代码仓库
git clone https://github.com/YOUR_USERNAME/arxiv-mcp-server.git
cd arxiv-mcp-server

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate

# 安装依赖
uv pip install -e .
```

## 配置
**以 claude code 为例**
编辑 `~/.claude.json`，在 `mcpServers` 中添加：

```json
{
  "mcpServers": {
    "arxiv-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/arxiv-mcp-server",
        "run",
        "arxiv-mcp-server"
      ]
    }
  }
}
```

将 `/path/to/arxiv-mcp-server` 替换为实际的项目路径，然后**完全退出并重新启动 Claude Desktop**。

## 可用工具

### search_papers
搜索 arXiv 论文

**参数**（均可修改）：
- `query`: 搜索查询（必需）
- `max_results`: 最大返回结果数，默认 10，最大 50
- `date_from`: 起始日期，格式 YYYY-MM-DD
- `date_to`: 结束日期，格式 YYYY-MM-DD
- `categories`: arXiv 分类数组，如 ["cs.AI", "cs.LG"]
- `sort_by`: 排序方式，"relevance"（相关度）或 "date"（日期）

**返回**：论文列表（id、title、abstract、published、url、code_url）

### download_paper
下载论文到本地

**参数**：
- `paper_id`: arXiv 论文 ID（必需）

**返回**：下载状态、论文目录、是否包含 LaTeX 和 PDF

### read_paper
读取论文内容

**参数**：
- `paper_id`: arXiv 论文 ID（必需）

**特点**：
- 如果论文未下载，会自动调用 `download_paper` 工具下载
- 直接从源文件读取（优先 LaTeX，否则 PDF）
- 不生成中间文件

**返回**：论文完整内容、来源格式（LaTeX 或 PDF）

## 存储路径与命名规则

### 默认路径
论文默认存储在项目根目录下的 `papers/` 文件夹中。

### 目录结构
```
papers/
├── {arXiv_ID}_{sanitized_title}/
│   ├── main.tex
│   ├── references.bib
│   ├── figures/
│   └── paper.pdf
```

### 命名规则
- **论文目录**：`{arXiv_ID}_{sanitized_title}`
  - `arXiv_ID`：论文的 arXiv 标识符（如 `2502.12345`）
  - `sanitized_title`：论文标题的清理版本（小写、空格替换为下划线、移除特殊字符）
- **示例**：`2502.12345_deep_learning_models/`

### 格式说明
- **LaTeX 源文件**：解压后的 `.tex`、`.bib`、`figures/` 等源代码文件
- **PDF 文件**：论文的 PDF 文件，文件名为 `paper.pdf`

## 注意事项

- arXiv API 有速率限制，短时间内大量请求会返回 HTTP 429 错误，服务器会自动重试最多 3 次
- 论文 ID 格式：`2502.12345` 或 `cs.AI/2502.12345`

## 许可证

本项目采用 MIT 许可证。详情请参阅 [LICENSE](LICENSE) 文件。