# Paperscraper MCP Server

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-FastMCP-green.svg)](https://github.com/jlowin/fastmcp)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

This is a production-ready **Model Context Protocol (MCP) Server** wrapper for the [`paperscraper`](https://github.com/jannisborn/paperscraper) Python package. It seamlessly bridges AI assistants with academic paper databases, allowing intelligent agents to autonomously search for, retrieve, and synthesize academic literature from multiple renowned repositories.

## 🌟 Features

This server currently exposes two primary tools to the MCP client:

1. **`search_pubmed_papers(query: str, max_results: int = 10)`**
   - Connects to the PubMed API.
   - Essential for retrieving biomedical and life sciences literature.

2. **`search_scholar_papers(title: str)`**
   - Retrieves metadata and citation counts for specific papers via Google Scholar.
   - *Note: Susceptible to rate-limiting; best used for targeted citation lookups rather than broad searches.*

## 🚀 Quick Start

You can run this server seamlessly without manual installation by utilizing `uvx` (part of the `uv` toolchain).

```bash
# Run directly from the source directory
uvx --from /path/to/paperscraper-mcpserver paperscraper-mcpserver
```

### Local Development Setup

If you wish to develop or modify the server:

1. Clone the repository and navigate to the directory:
   ```bash
   cd paperscraper-mcpserver
   ```
2. Sync the dependencies using `uv`:
   ```bash
   uv sync
   ```
3. Run the server:
   ```bash
   uv run paperscraper-mcpserver
   ```

## ⚙️ Configuration (Claude Desktop)

To enable this server in your MCP client (such as Claude Desktop), add the following JSON configuration to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "paperscraper": {
      "command": "uvx",
      "args": [
        "--from",
        "/absolute/path/to/paperscraper-mcpserver",
        "paperscraper-mcpserver"
      ]
    }
  }
}
```

*Be sure to replace `/absolute/path/to/paperscraper-mcpserver` with the actual absolute path to your cloned directory.*

## 🔧 Architecture & Error Handling

The server is built atop the **FastMCP** framework, ensuring low latency and robust execution.
- **Safe Execution Wrapper:** All underlying `paperscraper` API calls are wrapped in a robust `_safe_execute` handler. If an external API is down or returns a malformed response, the server catches the exception and returns a structured JSON error message, preventing the AI agent's workflow from crashing.
- **JSON Serialization:** Pandas DataFrames are automatically converted to standardized JSON records.

## 📄 License

This project is licensed under the MIT License.
