# Research MCP Server

A local, rule-based research assistant for searching and analyzing academic papers from [arXiv](https://arxiv.org). No API keys, no LLM calls — just Python standard libraries, the `arxiv` package, [FastMCP](https://gofastmcp.com/) for the MCP server, and keyword-frequency heuristics.

Available as both a **CLI tool** and a **Model Context Protocol (MCP) server** for Cursor, Claude Desktop, and other MCP clients.

---

## Features

| Module | Description |
|--------|-------------|
| **Search** | Fetch top N papers from arXiv by query |
| **Ranking** | Score papers by query-word frequency in title + abstract |
| **Smart Summary** | Pick the 2 most query-relevant sentences (no AI) |
| **Keyword Extraction** | Top 5 unique keywords (length > 6, stopwords removed) |
| **Citation Generator** | `Author1, Author2 (Year). Title.` format |
| **Logging** | INFO-level logging via Python `logging` module |
| **Validation** | Query length and empty-input checks |
| **Empty Results** | Graceful handling when no papers match |

---

## Project Structure

```
mcp_server_paper/
├── research.py       # Core engine (search, rank, summarize, keywords, citations)
├── main.py           # CLI entry point
├── mcp_server.py     # MCP server (stdio transport)
├── requirements.txt  # Python dependencies
├── tests/
│   ├── test_research.py      # Unit tests (mocked, no network)
│   └── test_integration.py   # CLI + MCP tool integration tests
└── README.md
```

---

## Requirements

- Python 3.10+
- Internet connection (for arXiv fetch only)
- Dependencies: `arxiv`, `fastmcp`, `pytest` (see `requirements.txt`)

---

## Installation

```bash
git clone <your-repo-url>
cd mcp_server_paper
pip install -r requirements.txt
```

---

## CLI Usage

Search arXiv and print formatted results:

```bash
python main.py --query "AI agents"
```

Options:

| Flag | Description | Default |
|------|-------------|---------|
| `--query`, `-q` | Search query (required) | — |
| `--max-results`, `-n` | Number of papers to fetch | `5` |

Example:

```bash
python main.py --query "transformer attention" --max-results 3
```

### Example Output

```
🔍 Query: AI agents

📊 Total papers found: 5

━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📄 Paper 1: A cybersecurity AI agent selection and decision support framework

🧠 Summary:
This paper presents a novel, structured decision support framework...

🔑 Keywords:
framework, cybersecurity, learning, standards, industry

📚 Citation:
Masike Malatji (2025). A cybersecurity AI agent selection and decision support framework.

🔗 Link:
http://arxiv.org/abs/2510.01751v1

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## MCP Server Usage

The MCP server exposes paper search and analysis as tools over **stdio transport**, compatible with Cursor and Claude Desktop.

### Start the server manually

```bash
python mcp_server.py
```

The server reads JSON-RPC from stdin and writes responses to stdout. Do not print debug output to stdout when running in MCP mode — logs go to stderr.

### Configure in Cursor

Add to your Cursor MCP settings (`Settings → MCP → Add new global MCP server` or edit `~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "research-papers": {
      "command": "python",
      "args": ["C:/mcp_server_paper/mcp_server.py"]
    }
  }
}
```

Use the absolute path to `mcp_server.py` on your machine.

### Configure in Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "research-papers": {
      "command": "python",
      "args": ["/absolute/path/to/mcp_server_paper/mcp_server.py"]
    }
  }
}
```

### Available MCP Tools

| Tool | Description |
|------|-------------|
| `search_papers` | Full pipeline: search arXiv, rank, summarize, extract keywords, generate citations |
| `summarize_text` | Extract top 2 query-relevant sentences from arbitrary text |
| `get_keywords` | Extract top N keywords from text using rule-based filtering |
| `create_citation` | Generate a bibliographic citation from authors, year, and title |

#### Tool: `search_papers`

```
query: str          — Search terms (e.g. "AI agents")
max_results: int    — Papers to fetch (default 5, max 20)
```

Returns formatted text with all paper details.

#### Tool: `summarize_text`

```
text: str    — Source text (e.g. abstract)
query: str   — Query terms for relevance scoring
```

#### Tool: `get_keywords`

```
text: str     — Source text
top_n: int    — Number of keywords (default 5)
```

#### Tool: `create_citation`

```
authors: list[str]  — Author names
year: str           — Publication year
title: str          — Paper title
```

---

## How It Works

### 1. Search (`search_arxiv`)

Queries the arXiv API via the `arxiv` Python library, fetching title, authors, published year, abstract, and link for each result.

### 2. Ranking (`rank_papers`)

Tokenizes the query into words and counts how often each word appears in `title + summary`. Papers are sorted descending by total score.

### 3. Smart Summary (`smart_summary`)

Splits the abstract into sentences, scores each sentence by query-word presence, and returns the top 2.

### 4. Keyword Extraction (`extract_keywords`)

- Removes punctuation
- Keeps words with length > 6
- Filters a manually defined stopword set
- Returns the top 5 by frequency

### 5. Citation Generator (`generate_citation`)

Formats: `Author1, Author2, and Author3 (2025). Paper Title.`

---

## Testing

Install dependencies, then run the full test suite:

```bash
pip install -r requirements.txt
pytest tests/ -v
```

### Test coverage

| File | What it tests |
|------|---------------|
| `tests/test_research.py` | Unit tests for ranking, summarization, keywords, citations, validation (mocked arXiv — no network) |
| `tests/test_integration.py` | CLI subprocess tests (live arXiv) + MCP tool function tests |

Run only fast unit tests (no network):

```bash
pytest tests/test_research.py -v
```

Run live integration tests (requires network):

```bash
pytest tests/test_integration.py -v
```

---

## Architecture

```mermaid
flowchart TD
    CLI[main.py CLI] --> RE[research.py]
    MCP[mcp_server.py MCP] --> RE
    RE --> ARXIV[arXiv API]
    RE --> RANK[rank_papers]
    RE --> SUM[smart_summary]
    RE --> KW[extract_keywords]
    RE --> CITE[generate_citation]
```

Both entry points share the same `research.py` engine. The CLI prints formatted output to stdout; the MCP server returns the same formatted strings as tool results over stdio JSON-RPC.

---

## Constraints

- No OpenAI or external AI APIs
- No transformers or ML models
- No API keys required
- Everything runs locally except the arXiv network fetch

---

## License

MIT (or your preferred license)