<div align="center">

# 🔍 ArXivLens MCP

### Autonomous Real-Time Academic Intelligence, Paper Discovery & Code-Implementation Mapping

[![CI Status](https://img.shields.io/badge/CI-Passing-brightgreen?style=for-the-badge&logo=github-actions)](https://github.com/chan4kum/arxivlens-mcp/actions)
[![Python Version](https://img.shields.io/badge/Python-3.10%20|%203.11%20|%203.12-blue?style=for-the-badge&logo=python)](https://python.org)
[![Protocol](https://img.shields.io/badge/Protocol-MCP%202.0-orange?style=for-the-badge&logo=anthropic)](https://modelcontextprotocol.io)
[![Framework](https://img.shields.io/badge/Framework-FastMCP%202.0-purple?style=for-the-badge)](https://gofastmcp.com)
[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)

*An enterprise-grade Model Context Protocol (MCP) server and client built with **FastMCP 2.0**, standardizing how AI agents scout research papers, extract structured insights, and verify open-source GitHub implementations in real time.*

---

[Key Features](#-key-features) •
[Architecture](#-architecture) •
[Real-Time Problem Statement](#-real-time-problem-statement) •
[Quickstart](#-quickstart) •
[Claude & Cursor Setup](#-claude--cursor-desktop-integration) •
[Interactive Agent](#-interactive-agent-cli)

</div>

---

## ⚡ Real-Time Problem Statement

Every day, hundreds of cutting-edge AI, Machine Learning, and Computer Science papers are published to arXiv, while corresponding open-source code repositories, benchmarks, and model checkpoints are scattered across GitHub, Hugging Face, and Papers With Code.

Researchers, AI engineers, and technical leads face three critical real-time challenges:
1. **Information Overload & Latency**: Finding newly dropped breakthrough papers in specific niches (e.g., test-time compute, reasoning models, KV-cache compression) before they get buried.
2. **The Implementation Gap**: Locating verified, highly-starred GitHub repositories and code implementations that correspond to an arXiv paper in real time.
3. **Synthesis & Evaluation Friction**: Manually downloading and reading 30-page PDFs just to extract key contributions, methodology gaps, and experimental baselines.
4. **Agent Integration Bottleneck**: LLM agents (Claude Desktop, Cursor, Custom Agents) lack standardized, safe, and live access to academic repositories and code-linkage databases.

**ArXivLens MCP solves this end-to-end** by exposing production-grade MCP Tools, dynamic Resources, and structured Prompts over standard transports (`stdio` and `SSE`).

---

## 🎯 Key Features

- **🔍 Live arXiv Search**: Real-time querying across arXiv's Atom 1.0 XML API with category filtering (`cs.AI`, `cs.LG`, `cs.CL`, `cs.CV`, `stat.ML`), author matching, and date sorting.
- **💻 Automated Code Discovery**: Proactively scans GitHub for repositories implementing or referencing the paper, extracting star counts, languages, licenses, and direct URLs.
- **📑 Structured Research Briefs**: Synthesizes paper abstracts into executive 1-page briefs breaking down Problem Statement, Proposed Methodology, Key Contributions, Limitations, and Matching Code.
- **📡 Dynamic MCP Resources**:
  - `arxiv://categories`: Catalog of supported research domains.
  - `arxiv://feed/{category}`: Live category paper feed.
  - `paper://{arxiv_id}/brief`: Dynamic markdown research brief for any paper ID.
- **🧠 Expert Prompt Templates**: Standardized prompt templates for systematic literature reviews, critical methodology peer-reviews, and reproducibility audits.
- **🖥️ Dual Interface**: Includes both a **FastMCP Server** and a **Rich Terminal Client** with an interactive autonomous agent loop.
- **⚡ Zero-Cost Local Evaluation**: Built-in mock reasoning fallback allows testing and evaluation immediately without requiring paid API keys!

---

## 🏗️ Architecture

```mermaid
flowchart TD
    subgraph Clients["MCP Clients & AI Hosts"]
        Claude["Claude Desktop"]
        Cursor["Cursor AI"]
        TerminalCLI["ArXivLens CLI / Agent"]
        CustomAgent["LangChain / LlamaIndex / Agent Frameworks"]
    end

    subgraph Protocol["Model Context Protocol (MCP Transport)"]
        StdIO["stdio (Subprocess Pipe)"]
        SSE["SSE / HTTP Transport"]
    end

    subgraph Server["ArXivLens FastMCP 2.0 Server"]
        Router["FastMCP Request Dispatcher"]
        
        subgraph Capabilities["Server Primitives"]
            Tools["MCP Tools\n• search_arxiv\n• get_paper_details\n• find_code_repositories\n• generate_research_brief"]
            Resources["MCP Resources\n• arxiv://categories\n• arxiv://feed/{cat}\n• paper://{id}/brief"]
            Prompts["MCP Prompts\n• literature_review\n• paper_critique\n• reproducibility_audit"]
        end

        subgraph CoreServices["Internal Services"]
            ArxivSvc["ArxivService\n(Atom 1.0 XML Async Client)"]
            GitHubSvc["GitHubService\n(REST Search API & Matcher)"]
            BriefSvc["BriefService\n(Synthesis & Markdown Engine)"]
        end
    end

    subgraph Upstream["Upstream Real-Time Data Sources"]
        ArXivAPI["arXiv Official API\n(export.arxiv.org)"]
        GitHubAPI["GitHub Search API\n(api.github.com)"]
    end

    Clients --> Protocol
    Protocol --> Router
    Router --> Capabilities
    Tools --> CoreServices
    Resources --> CoreServices
    CoreServices --> ArXivAPI
    CoreServices --> GitHubAPI
```

---

## 🚀 Quickstart

### 1. Installation

Clone the repository and install dependencies using `uv` (recommended) or `pip`:

```bash
git clone https://github.com/chan4kum/arxivlens-mcp.git
cd arxivlens-mcp

# Using uv (fastest)
uv sync

# Or using standard pip
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

### 2. Configure Environment (Optional)

Copy `.env.example` to `.env`:

```bash
cp .env.example .env
```
*Tip: Adding a `GITHUB_TOKEN` increases your GitHub API rate limit from 60 req/hr to 5,000 req/hr.*

---

## 💻 CLI & Interactive Client

ArXivLens comes out-of-the-box with an interactive CLI built with `rich`:

### Inspect Server Capabilities
Inspect all registered MCP tools, resources, and prompts:
```bash
uv run arxivlens-client inspect
```

### Real-Time Paper Search
```bash
uv run arxivlens-client search "DeepSeek-R1 reasoning" --max 3
```

### Generate Structured Research Brief
```bash
uv run arxivlens-client brief 1706.03762
```

### Find GitHub Code Repositories
```bash
uv run arxivlens-client code 1706.03762
```

### Autonomous Agent Loop
Launch the interactive terminal agent to scout papers and match code conversationally:
```bash
uv run arxivlens-client agent
```

---

## 🔌 Claude & Cursor Desktop Integration

### Claude Desktop
Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "arxivlens": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/arxivlens-mcp",
        "run",
        "arxivlens-server"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

### Cursor AI
1. Open **Cursor Settings > Features > MCP Servers**.
2. Click **Add New MCP Server**:
   - **Name**: `ArXivLens`
   - **Type**: `command`
   - **Command**: `uv --directory /absolute/path/to/arxivlens-mcp run arxivlens-server`

---

## 🧪 Testing

Run the comprehensive unit and integration test suite:

```bash
# Run pytest with coverage
uv run pytest -v tests/

# Run linter
uv run ruff check .
```

---

## 📂 Repository Structure

```
arxivlens-mcp/
├── .github/workflows/ci.yml       # GitHub Actions automated CI
├── config/
│   ├── claude_desktop_config.json # Claude Desktop configuration
│   └── cursor_mcp.json            # Cursor AI configuration
├── docs/
│   ├── ARCHITECTURE.md            # In-depth architectural documentation
│   └── SETUP_GUIDE.md             # Integration guide for agents & hosts
├── src/arxivlens/
│   ├── __init__.py                # Package exports
│   ├── server.py                  # FastMCP 2.0 Server (Tools, Resources, Prompts)
│   ├── client.py                  # FastMCP Client async wrapper
│   ├── cli.py                     # Rich terminal CLI & Agent loop
│   ├── models.py                  # Pydantic data models
│   └── services/
│       ├── arxiv_service.py       # Async arXiv Atom XML client
│       ├── github_service.py      # GitHub search & code matcher
│       └── brief_service.py       # Research brief synthesis engine
├── tests/
│   ├── conftest.py                # Mock fixtures for offline testing
│   ├── test_services.py           # Unit tests for services
│   ├── test_server.py             # Server endpoints tests
│   └── test_client.py             # Client integration tests
├── .env.example                   # Environment configuration template
├── .gitignore                     # Git ignore patterns
├── LICENSE                        # MIT License
├── pyproject.toml                 # Packaging & CLI entrypoints
└── README.md                      # Project documentation
```

---

## 🤝 Contributing

Contributions are welcome! Please follow these steps:
1. Fork the repository.
2. Create your feature branch (`git checkout -b feature/amazing-feature`).
3. Run tests and linter (`uv run pytest && uv run ruff check .`).
4. Commit your changes (`git commit -m 'feat: add amazing feature'`).
5. Push to the branch (`git push origin feature/amazing-feature`).
6. Open a Pull Request.

---

## 📜 License

Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for more information.

---

<div align="center">
Built with ❤️ using <a href="https://gofastmcp.com">FastMCP 2.0</a> and <a href="https://modelcontextprotocol.io">Model Context Protocol</a>
</div>