[![Python Version](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

# ArXiv Sync MCP Server

> 🔍 Enable AI assistants to search and access arXiv papers through a simple MCP interface.

## 📌 About This Fork

This is a fork of the original [arxiv-mcp-server](https://github.com/blazickjp/arxiv-mcp-server) by [Joseph Blazick](https://github.com/blazickjp).

### Why This Fork?

This fork simplifies the architecture and fixes issues found in the original:

| Feature | Original | This Fork |
|---------|----------|-----------|
| Download method | Async background conversion | Synchronous download & conversion |
| API calls | Multiple (download → poll status → read) | Single call returns content |
| Status tracking | Required | Not needed |
| PDF cleanup | Manual | Automatic after conversion |
| Date filtering | Buggy | Fixed |
| Complexity | Higher | Simpler |

**Key improvements:**
- The `get_paper_content` tool now downloads, converts PDF to markdown, and returns the content in a single call
- Date filtering in `search_papers` now works correctly:
  - Uses direct HTTP requests to arXiv API to bypass encoding issues with the Python arxiv library
  - Properly formats date ranges in arXiv's `submittedDate:[YYYYMMDD0000+TO+YYYYMMDD2359]` format
  - Correctly combines date filters with category and query filters using AND operators

The ArXiv Sync MCP Server provides a bridge between AI assistants and arXiv's research repository through the Model Context Protocol (MCP). It allows AI models to search for papers and access their content programmatically.

## ✨ Core Features

- 🔎 **Paper Search**: Query arXiv papers with filters for date ranges and categories
- 📄 **Paper Access**: Download and read paper content
- 📋 **Paper Listing**: View all downloaded papers
- 🗃️ **Local Storage**: Papers are saved locally for faster access
- 📝 **Prompts**: A Set of Research Prompts

## 🚀 Quick Start

> This fork is distributed via GitHub and is not published to PyPI.

### Installing Manually

Install using uv:

```bash
uv tool install git+https://github.com/marfago/arxiv-sync-mcp-server.git
```

For development:

```bash
# Clone and set up development environment
git clone https://github.com/marfago/arxiv-sync-mcp-server.git
cd arxiv-sync-mcp-server

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install with test dependencies
uv pip install -e ".[test]"
```

### 🔌 MCP Integration

Add this configuration to your MCP client config file:

```json
{
    "mcpServers": {
        "arxiv-sync-mcp-server": {
            "command": "uv",
            "args": [
                "tool",
                "run",
                "--from",
                "git+https://github.com/marfago/arxiv-sync-mcp-server.git",
                "arxiv-sync-mcp-server",
                "--storage-path", "/path/to/paper/storage"
            ]
        }
    }
}
```

For Development:

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

## 💡 Available Tools

The server provides **three simple tools**:

### 1. Paper Search
Search for papers with optional filters:

```python
result = await call_tool("search_papers", {
    "query": "transformer architecture",
    "max_results": 10,
    "date_from": "2023-01-01",
    "categories": ["cs.AI", "cs.LG"]
})
```

### 2. Get Paper Content
Get the full content of a paper, downloading and converting it if necessary:

```python
result = await call_tool("get_paper_content", {
    "paper_id": "2401.12345"
})
```

### 3. List Papers
View all downloaded papers:

```python
result = await call_tool("list_papers", {})
```

## 📝 Research Prompts

The server offers specialized prompts to help analyze academic papers:

### Paper Analysis Prompt
A comprehensive workflow for analyzing academic papers that only requires a paper ID:

```python
result = await call_prompt("deep-paper-analysis", {
    "paper_id": "2401.12345"
})
```

This prompt includes:
- Detailed instructions for using available tools (get_paper_content, search_papers, list_papers)
- A systematic workflow for paper analysis
- Comprehensive analysis structure covering:
  - Executive summary
  - Research context
  - Methodology analysis
  - Results evaluation
  - Practical and theoretical implications
  - Future research directions
  - Broader impacts

## ⚙️ Configuration

Configure through environment variables:

| Variable | Purpose | Default |
|----------|---------|---------|
| `ARXIV_STORAGE_PATH` | Paper storage location | ~/.arxiv-sync-mcp-server/papers |

## 🧪 Testing

Run the test suite:

```bash
python -m pytest
```

## 📄 License

Released under the Apache 2.0 License. See the LICENSE file for details.

---

<div align="center">

Fork of [arxiv-mcp-server](https://github.com/blazickjp/arxiv-mcp-server) by [Joseph Blazick](https://github.com/blazickjp)

Originally made with ❤️

</div>