# ResearchMCP

An agentic research assistant that lets an LLM autonomously search arXiv, extract and analyze paper content, and build a personal semantically-searchable research library — built as a custom [MCP](https://modelcontextprotocol.io) server paired with a LangGraph agent.

## What it does

Ask it something like:
> "Search for papers about neighborhood attention transformers, save the top result to my library, then find related papers I've already saved."

The agent autonomously decides which tools to call, in what order, chaining multiple steps together without being told the exact sequence.

An interactive CLI (`agent/cli.py`) lets you have a real multi-turn conversation with the agent — it remembers context within a session, and persists conversation history to SQLite so sessions survive restarts.

## Architecture

```
User query
    ↓
LangGraph ReAct Agent (Gemini 2.5 Flash)
    ↓ (decides which tool to call, loops until done)
ResearchMCP Server (9 tools over MCP protocol)
    ↓
┌─────────────┬──────────────┬─────────────────┐
│  arXiv API  │ PDF extract  │ SQLite + FAISS  │
│  (search)   │ (pymupdf)    │ (personal library)│
└─────────────┴──────────────┴─────────────────┘
    ↓
Synthesized answer, grounded in real tool results
```

The MCP server and the agent are fully decoupled — the server is a standalone, protocol-compliant MCP server that works with **any** MCP client (Claude Desktop, other agents), not just the LangGraph agent built here.

## Memory

The agent has two layers of memory, both backed by SQLite (separate from the research library database):

- **Short-term (in-session)**: the full conversation history is passed to the agent on every turn, so follow-up questions ("what was the title of the paper you just saved?") can be answered directly from context without a redundant tool call.
- **Long-term (persistent)**: every message is saved to `data/conversations.db`. Closing and reopening the CLI resumes the most recent session automatically, with full prior context intact.

The agent is prompted to distinguish between two different kinds of questions: recalling what was *discussed* in the conversation (answered from memory) versus querying the actual state of the saved paper *library* (answered by calling `list_saved_papers`) — these pull from different sources of truth, and the agent correctly picks the right one.

**Error handling**: all tools return structured errors (`{"error": "...", "status": "failed"}`) instead of raising exceptions — so a bad paper ID, empty query, or failed download surfaces as a clear message the agent can reason about, rather than crashing the tool call.

## Tools

| Tool | What it does |

|---|---|
| `search_arxiv` | Search arXiv by keyword, returns titles/authors/abstracts |
| `get_paper` | Full metadata for one paper by arXiv ID |
| `extract_content` | Downloads a paper's PDF, extracts and cleans the text (strips references) |
| `save_to_library` | Saves a paper to a personal SQLite + FAISS-indexed library |
| `search_library` | Semantic search over your saved papers — finds conceptually related work, not just keyword matches |
| `save_note` | Save a research note, optionally linked to a paper |
| `list_saved_papers` | List everything in your library |
| `summarize_paper` | Fetches a paper's content, formatted for the calling LLM to summarize |
| `compare_papers` | Fetches multiple papers' content side by side, formatted for the calling LLM to compare |

**Design note**: `summarize_paper` and `compare_papers` intentionally do **not** call an LLM internally — they return raw, structured data for the client (the LLM asking the question) to reason over. This keeps the server's responsibility scoped to *retrieval*, not *reasoning*, which is the correct separation of concerns for MCP tools and keeps the server reusable across any client.

## Tech stack

- **MCP server**: Python, official `mcp` SDK (FastMCP)
- **Paper search**: `arxiv` package (arXiv API wrapper)
- **PDF extraction**: `pymupdf`
- **Personal library**: SQLite (metadata) + FAISS (semantic search) + `sentence-transformers` (`all-MiniLM-L6-v2` embeddings)
- **Agent**: LangGraph (`create_react_agent`) + `langchain-mcp-adapters` + Gemini 2.5 Flash
- **CLI**: `rich` for formatted terminal output, SQLite for persistent conversation memory

## Setup

```bash
# Clone and enter the repo
git clone https://github.com/Adityay009/ResearchMcp
cd researchmcp

# Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate

# Install MCP server dependencies
pip install -r requirements.txt

# Install agent dependencies
pip install -r agent/requirements.txt

# Add your Gemini API key
echo "GOOGLE_API_KEY=your_key_here" > .env
```

## Testing

22 automated tests across 4 files, covering the core logic layer (text cleaning, database operations, mocked API calls, and vector search):

```bash
pip install -r requirements.txt  # includes pytest
python -m pytest -v
```

| File | What it covers |
|---|---|
| `tests/test_content_tools.py` | PDF text cleaning and reference-section stripping (pure logic, no I/O) |
| `tests/test_db.py` | SQLite operations, using isolated temp databases per test |
| `tests/test_arxiv_tools.py` | arXiv API wrapper, with the network call mocked |
| `tests/test_vector_store.py` | FAISS indexing and semantic search, including a regression test for a duplicate-entry bug found during manual testing |

Database and vector-store tests use `pytest`'s `tmp_path` fixture with `monkeypatch` to redirect storage paths — tests never touch the real `data/` directory.

### Running the MCP server standalone (with the official Inspector)

```bash
PYTHONPATH=. mcp dev mcp_server/server.py
```

Opens a local web UI to test each of the 9 tools individually.


### Running the interactive CLI (recommended)

```bash
python -m agent.cli
```

Commands available inside the CLI:
- `/new` — start a fresh conversation session
- `/sessions` — list all past sessions with message counts
- `/exit` — quit

Tool calls are displayed live as the agent executes them, providing visibility into the agent's actions and research workflow.

### Running a single scripted query

```bash
python agent/graph.py
```

Edit the `test_query` variable in `agent/graph.py` to try your own one-off queries.

## Known limitations

- PDF text extraction is imperfect on figure-heavy papers — captions, author affiliations, and diagram labels can bleed into the extracted body text (a known limitation of plain-text PDF extraction, not something specific to this project)
- Reference-section stripping uses a simple regex match on "References"/"Bibliography" headers — doesn't catch every paper's formatting (e.g. "Works Cited")
- `compare_papers` truncates each paper's content to keep tool responses within a reasonable context size, so very long papers are compared on excerpts (intro + methodology) rather than full text
- FAISS (`IndexFlatL2`) does exact brute-force search — fine at personal-library scale (hundreds of papers), would need a different index type (e.g. HNSW) at much larger scale

## Environment notes

Built and tested on macOS (Apple Silicon/M1). If `mcp dev` fails with `spawn uv ENOENT`, it's because the Inspector shells out to [`uv`](https://github.com/astral-sh/uv) regardless of your project setup — install it with `curl -LsSf https://astral.sh/uv/install.sh | sh` and make sure `~/.local/bin` is on your `PATH`.

If you hit a RESOURCE_EXHAUSTED / limit: 0 error from Gemini even on a fresh API key, try a different model (e.g. gemini-2.5-flash instead of gemini-2.0-flash) — free-tier quota allocation varies by model.