# arXiv Research Paper Analyzer MCP Server

[![CI](https://github.com/arman1o1/mcp-arxiv-analyzer/actions/workflows/ci.yml/badge.svg)](https://github.com/arman1o1/mcp-arxiv-analyzer/actions/workflows/ci.yml)

An MCP (Model Context Protocol) server that enables LLM agents to search arXiv, download papers, parse PDFs into structured sections, and extract key findings using client-side LLMs. It features persistent local caching and layout-aware PDF extraction to optimize token usage and processing speed.

## Architecture

The following diagram illustrates the workflow and architecture of the arXiv Analyzer server:

```mermaid
graph TD
    Agent([LLM Agent]) -->|Call Tool / Read Resource| Server[arXiv Analyzer MCP Server]
    Server -->|Query Meta / Download PDF| ArxivAPI[arXiv API]
    Server -->|Read Cached Files| Cache[Local File Cache]
    Server -->|Parse PDF Layout| MuPDF[PyMuPDF Parser]
    MuPDF -->|Segment Text| Sections[Parsed Sections]
    Server -.->|Request LLM completion| Sampling[Client LLM Sampling]
    Sampling -.->|Return Summary| Server
```

## Project Structure

```
mcp-arxiv-analyzer/
├── .github/workflows/
│   └── ci.yml               # GitHub Actions CI pipeline
├── mcp_arxiv_analyzer/
│   ├── __init__.py
│   ├── arxiv_client.py      # arXiv API integration and downloader
│   ├── cache.py             # File caching layer for PDFs, sections, and summaries
│   ├── llm.py               # Client sampling interfaces and fallback logic
│   ├── pdf_parser.py        # PyMuPDF parser for layout-aware section segmentation
│   └── server.py            # MCP server endpoint and tool handlers
├── tests/                   # Unit and integration test suite
├── pyproject.toml           # Package configuration and dependencies
└── README.md                # Documentation
```

## Tools Exposed

- **`search_arxiv`**: Search arXiv for research papers matching a query.
- **`download_paper`**: Download a paper by ID, parse its PDF into layout sections, and cache it.
- **`get_paper_sections`**: Get cached section names and outlines.
- **`get_section_text`**: Retrieve the raw text content of a specific section of a paper.
- **`get_paper_context`**: Retrieve a token-efficient pre-assembled overview context of the paper (Abstract, Intro, Conclusion, Outline, and focus-related sections) for summarization.
- **`extract_key_findings`**: Generate a structured summary of contributions, methods, experiments, and limitations. Falls back to providing context for client-side summarization if client-side sampling (`CreateMessage`) is unsupported.

## Setup and Installation

### Prerequisites
- Python 3.10 or higher
- `uv` package manager (recommended) or `pip`

### 1. Clone the Repository
```bash
git clone https://github.com/arman1o1/mcp-arxiv-analyzer.git
cd mcp-arxiv-analyzer
```

### 2. Setup Virtual Environment and Install
Using `uv`:
```bash
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .
```

Using standard `pip`:
```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .
```

## Running the Server

To run the MCP server on stdio (the standard protocol for MCP integrations):
```bash
python -m mcp_arxiv_analyzer.server
```

### Configuration with MCP Hosts

To configure the server with your MCP host (like Claude Desktop or Antigravity), add the following server configuration to your `mcp_config.json`:

```json
{
  "mcpServers": {
    "mcp-arxiv-analyzer": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-arxiv-analyzer",
        "run",
        "python",
        "-m",
        "mcp_arxiv_analyzer.server"
      ]
    }
  }
}
```

## Running Tests

To run the unit and integration tests locally, install development dependencies and run `pytest`:

```bash
pip install -e .[dev]
pytest
```