# Research Buddy MCP Server

A powerful literature review assistant for AI agents, powered by the Semantic Scholar Graph API. Gives your AI agent the ability to search, explore, and cite academic papers through 15 specialized tools.

## Features

- **Advanced Search**: Find papers by keyword with filters for discipline, venue, document type, citation count, date range, and open access availability. Includes pagination.
- **Bulk Search**: Boolean query syntax (`+"LLM" +hallucination -survey`) with sorting by citation count or recency, and token-based pagination through up to 10 million results.
- **Full-Text Snippet Search**: Search *inside* paper content, not just metadata. Returns ~500-word excerpts with section labels (Introduction, Methods, etc.).
- **Title Matching**: Resolve plain-text references like "Attention Is All You Need" to a paper ID with a confidence score.
- **Smart Recommendations**: AI-driven paper discovery using multiple seed papers and negative examples to steer results.
- **Rich Paper Details**: Full metadata including external IDs (DOI, arXiv, PubMed), fields of study, publication venue, open access status, and more.
- **Citation Graph with Context**: Explore who cited a paper and what it references, with the actual citation sentence, intent classification (methodology, background, result comparison), and influence scoring.
- **Author Discovery**: Search for authors by name, view h-index, paper count, citation count, affiliations, and publication list.
- **Multi-Format Citations**: Generate citations in APA, MLA, Chicago, IEEE, and BibTeX formats.
- **Citation Intersection**: Find papers that appear in the citation graph of multiple papers, revealing bridging work between research threads.
- **PDF Extraction**: Extract plain text from Open Access PDFs for immediate reading.
- **Batch Processing**: Efficiently fetch metadata for multiple papers at once.

## Installation

### Option A: Install from GitHub (recommended)

```bash
pip install git+https://github.com/Usama1002/research-buddy-mcp.git
```

### Option B: Install from source (for development)

```bash
git clone https://github.com/Usama1002/research-buddy-mcp.git
cd research-buddy-mcp
pip install -e .
```

### Configuration

Create a `.env` file or set the environment variable:

```env
SEMANTIC_SCHOLAR_API_KEY=your_api_key_here
```

> The server works without an API key but with lower rate limits. Get a free key at [semanticscholar.org/product/api](https://www.semanticscholar.org/product/api#api-key-form).

## Usage

### Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "research-buddy": {
      "command": "research-buddy-mcp",
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Claude Code

Add this to your `.claude/settings.json` or project's `.mcp.json`:

```json
{
  "mcpServers": {
    "research-buddy": {
      "command": "research-buddy-mcp",
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Antigravity (Gemini)

Add the following to `~/.gemini/antigravity/mcp_config.json`:

```json
{
  "mcpServers": {
    "research-buddy": {
      "command": "research-buddy-mcp",
      "args": [],
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### VS Code

#### Native (Windows, macOS, Linux)

Create a `.vscode/mcp.json` in your project root:

```json
{
  "servers": {
    "research-buddy": {
      "command": "research-buddy-mcp",
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Alternatively, add it globally in your VS Code `settings.json`:

```json
{
  "mcp": {
    "servers": {
      "research-buddy": {
        "command": "research-buddy-mcp",
        "env": {
          "SEMANTIC_SCHOLAR_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}
```

#### WSL (Windows Subsystem for Linux)

VS Code's extension host runs in the Windows process space and cannot directly resolve WSL binaries. You must explicitly delegate the command to WSL using the full path to the installed binary.

First, find the binary path inside WSL:

```bash
which research-buddy-mcp
# Example output: /home/<your-username>/.local/bin/research-buddy-mcp
```

Then add the following to your VS Code `settings.json` (or `.vscode/mcp.json`):

```json
{
  "mcp": {
    "servers": {
      "research-buddy": {
        "command": "wsl",
        "args": [
          "--",
          "/home/<your-username>/.local/bin/research-buddy-mcp"
        ],
        "env": {
          "SEMANTIC_SCHOLAR_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}
```

Replace `/home/<your-username>` with your actual WSL username.

## Tools

### Search & Discovery

| Tool | Description |
| :--- | :--- |
| `search_papers` | Search for papers by keyword with advanced filters: fields of study, publication type, venue, citation count, date range, open access, and pagination. |
| `bulk_search_papers` | Boolean query search (`+`, `\|`, `-`, `"phrases"`, wildcards) with sorting by citation count or date. Paginate through up to 10M results via continuation tokens. |
| `search_paper_snippets` | Full-text search *inside* papers. Returns ~500-word text excerpts with the section where the match was found (e.g. Introduction, Methods). |
| `match_paper_by_title` | Resolve a plain-text title (e.g. "Attention Is All You Need") to a paper ID with a confidence score. |
| `search_authors` | Find researchers by name. Returns author profiles with h-index, paper count, citation count, and affiliations. |

### Paper Details & Metadata

| Tool | Description |
| :--- | :--- |
| `get_paper_details` | Full metadata for a paper: abstract, TLDR, external IDs (DOI, arXiv, PubMed), fields of study, publication venue, open access status, citation/reference counts, and more. Accepts Semantic Scholar IDs, DOIs (`DOI:...`), and arXiv IDs (`ARXIV:...`). |
| `batch_get_papers` | Retrieve details for multiple papers in a single request. |
| `read_pdf_text` | Download and extract plain text from an open-access PDF URL. |

### Citation Graph

| Tool | Description |
| :--- | :--- |
| `get_citations` | Papers that cited a given work, with citation context (the actual sentence), intent classification (methodology, background, result comparison), influence flag, and pagination. Filter to influential citations only. |
| `get_references` | Papers referenced by a given work, with the same context, intent, and influence data. |
| `find_common_citations` | Find papers at the intersection of multiple citation graphs. Given 2+ papers, discover which papers cite all of them (or are referenced by all of them). |

### Recommendations

| Tool | Description |
| :--- | :--- |
| `get_related_papers` | AI-driven recommendations from Semantic Scholar's recommendation engine. Accepts multiple seed papers and optional negative examples to steer results away from unwanted directions. |

### Authors

| Tool | Description |
| :--- | :--- |
| `get_author_details` | Author profile: name, affiliations, h-index, paper count, citation count, and publication list. |

### Citations & Export

| Tool | Description |
| :--- | :--- |
| `get_paper_bibtex` | Ready-to-use BibTeX citation string. |
| `get_paper_citation` | Formatted citation in APA, MLA, Chicago, IEEE, or BibTeX style. |

## Example Workflows

### Systematic Literature Review

```
1. bulk_search_papers('"large language model" +hallucination', sort='citationCount:desc')
2. Filter to top-cited results, then get_paper_details for each
3. get_references with influential_only=True to find foundational work
4. get_paper_citation for each in your preferred format
```

### "Find papers like X but not like Y"

```
1. match_paper_by_title('Attention Is All You Need') -> get paper ID
2. get_related_papers(paper_ids=[attention_id], negative_paper_ids=[bert_id])
```

### Find bridging work between two research areas

```
1. find_common_citations([paper_A_id, paper_B_id], direction='citations')
   -> papers that cite BOTH A and B
2. find_common_citations([paper_A_id, paper_B_id], direction='references')
   -> papers referenced BY BOTH A and B
```

### Find a specific claim in the literature

```
1. search_paper_snippets('chain-of-thought prompting improves reasoning on math')
   -> returns exact text excerpts with section labels
```

## Troubleshooting

### `spawn research-buddy-mcp ENOENT` in VS Code

This error means VS Code cannot find the `research-buddy-mcp` executable. This is common when using **WSL on Windows**, because VS Code's extension host runs in Windows and does not have access to WSL's PATH.

**Fix:** Use the WSL-specific configuration above, pointing to the full binary path returned by `which research-buddy-mcp` inside your WSL terminal.

### Rate Limiting

Without an API key, requests share a global rate limit across all unauthenticated users. If you see `429 Too Many Requests` errors, [get a free API key](https://www.semanticscholar.org/product/api#api-key-form) and set it in your configuration. The server retries rate-limited requests automatically with exponential backoff.

## License
MIT