# Research MCP Server

A FastMCP-based Model Context Protocol (MCP) server for searching and managing academic papers from arXiv. This server demonstrates how to build MCP servers with tools, resources, and prompt templates.

## Features

### Tools
- **search_papers**: Search arXiv for papers on a specific topic and store their metadata locally
- **extract_info**: Retrieve detailed metadata for a specific paper by ID

### Resources
- **papers://folders**: List all available research topic folders
- **papers://{topic}**: Get all papers for a specific research topic

### Prompt Templates
- **generate_search_prompt**: Generate a structured prompt to guide research on a specific topic

## Installation

1. Clone or download this project

2. Install dependencies:
```bash
pip install -r requirements.txt
```

## Running the Server

### Standalone Mode
Run the server directly:
```bash
python research_server.py
```

### With Claude Desktop

Add the server to your Claude Desktop configuration:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Configuration:
```json
{
  "mcpServers": {
    "research": {
      "command": "python",
      "args": [
        "/absolute/path/to/research_server.py"
      ]
    }
  }
}
```

Replace `/absolute/path/to/research_server.py` with the actual path to your file.

## Using the Python Client

### Quick Start

Run the interactive demo:
```bash
python example_usage.py
```

This will show you an interactive menu with various examples.

### Basic Client Usage

```python
from research_client import ResearchClient
import asyncio

async def main():
    client = ResearchClient()

    # Connect to the server
    await client.connect("./research_server.py")

    # Search for papers
    paper_ids = await client.search_papers("machine learning", max_results=5)

    # Get detailed information
    for paper_id in paper_ids:
        await client.extract_info(paper_id)

    # Browse topics
    await client.get_folders()

    # Close connection
    await client.close()

asyncio.run(main())
```

### Available Client Methods

#### Connection
- `connect(server_script_path)` - Connect to the MCP server
- `close()` - Close the connection

#### Tools
- `search_papers(topic, max_results)` - Search for papers on a topic
- `extract_info(paper_id)` - Get detailed information about a paper

#### Resources
- `get_folders()` - List all research topic folders
- `get_topic_papers(topic)` - Get all papers for a specific topic

#### Prompts
- `get_search_prompt(topic, num_papers)` - Generate a search prompt template

#### Discovery
- `list_tools()` - List all available tools
- `list_resources()` - List all available resources
- `list_prompts()` - List all available prompt templates

## Usage Examples

### Example 1: Literature Review
```python
from research_client import ResearchClient
import asyncio

async def literature_review():
    client = ResearchClient()
    await client.connect("./research_server.py")

    # Search for papers
    paper_ids = await client.search_papers("neural networks", max_results=5)

    # Get details for each paper
    for paper_id in paper_ids:
        paper = await client.extract_info(paper_id)
        print(f"Title: {paper['title']}")
        print(f"Authors: {', '.join(paper['authors'])}")

    await client.close()

asyncio.run(literature_review())
```

### Example 2: Compare Topics
```python
async def compare_topics():
    client = ResearchClient()
    await client.connect("./research_server.py")

    topics = ["deep learning", "machine learning", "AI"]
    for topic in topics:
        await client.search_papers(topic, max_results=3)

    # View all collected topics
    folders = await client.get_folders()

    await client.close()

asyncio.run(compare_topics())
```

### Example 3: Interactive Menu (Recommended)
```bash
python example_usage.py
```

Select from:
1. Literature Review - Search and analyze papers on a topic
2. Compare Multiple Topics - Compare papers across different areas
3. Deep Dive - Get comprehensive details on specific papers
4. Browse Resources - Explore stored research data
5. Generate Research Prompts - Create structured research prompts
6. Run All Examples - Execute all examples sequentially

### Using with Claude Desktop

When configured with Claude Desktop, you can use natural language:

1. **Search for papers**:
```
Use the search_papers tool to find papers about "machine learning"
```

2. **Get paper details**:
```
Use the extract_info tool to get details for paper ID "2301.12345"
```

3. **List all topics**:
```
Show me the papers://folders resource
```

4. **View papers for a topic**:
```
Show me papers://machine_learning
```

5. **Use prompt templates**:
```
Use the generate_search_prompt template for "quantum computing" with 10 papers
```

## Project Structure

```
MCP_server/
├── research_server.py      # Main MCP server implementation
├── research_client.py      # Python client for the MCP server
├── example_usage.py        # Interactive examples and demos
├── requirements.txt        # Python dependencies
├── README.md              # This file
├── .gitignore             # Git ignore rules
├── .claude_mcp_config.json # Example MCP configuration
└── data/
    └── papers/            # Storage for paper metadata
        ├── topic1/        # Papers organized by topic
        ├── topic2/
        └── ...
```

## How It Works

### Architecture

The project consists of two main components:

1. **MCP Server** (`research_server.py`)
   - Built with FastMCP framework
   - Exposes tools, resources, and prompt templates
   - Handles arXiv API communication
   - Manages local paper storage

2. **Python Client** (`research_client.py`)
   - Connects to the MCP server via stdio
   - Provides async methods to call tools and access resources
   - Handles JSON parsing and formatting
   - Manages connection lifecycle

### Search Papers Tool
1. Takes a topic and searches arXiv's API
2. Parses XML responses to extract paper metadata
3. Stores papers locally in topic-specific folders
4. Returns list of paper IDs found

### Extract Info Tool
1. Searches local storage for a paper by ID
2. Returns complete metadata including:
   - Title and authors
   - Abstract/summary
   - Publication date
   - PDF link

### Resources
Resources provide read-only access to stored data:
- List all research topics you've explored
- View all papers within a specific topic

### Prompt Templates
Reusable prompts that guide the AI to:
- Search for papers on a topic
- Extract and analyze paper details
- Provide structured summaries and recommendations

### Client-Server Communication
1. Client spawns server as subprocess
2. Communication via JSON-RPC over stdio
3. Client sends tool calls, resource requests, and prompt queries
4. Server processes requests and returns structured responses
5. Client parses and presents results

## Data Storage

All paper metadata is stored locally in JSON format:
- Location: `data/papers/{topic}/{paper_id}.json`
- Format: JSON with title, authors, summary, publication date, and PDF link

## API Reference

### search_papers(topic: str, max_results: int = 5) -> List[str]
Search arXiv and store paper metadata.

**Parameters:**
- `topic`: Research topic to search for
- `max_results`: Maximum number of papers to retrieve (default: 5)

**Returns:** List of paper IDs

### extract_info(paper_id: str) -> str
Get metadata for a specific paper.

**Parameters:**
- `paper_id`: arXiv paper ID (e.g., "2301.12345")

**Returns:** JSON string with paper metadata

### Resource: papers://folders
Lists all topic folders with paper counts.

**Returns:** JSON with topics and counts

### Resource: papers://{topic}
Get all papers for a specific topic.

**Parameters:**
- `topic`: Topic name

**Returns:** JSON with all papers in the topic

### generate_search_prompt(topic: str, num_papers: int = 5) -> str
Generate a research prompt.

**Parameters:**
- `topic`: Research topic
- `num_papers`: Number of papers to search for (default: 5)

**Returns:** Formatted prompt string

## Troubleshooting

### Server Issues

**Server won't start**
- Ensure all dependencies are installed: `pip install -r requirements.txt`
- Check Python version (3.8+ required)
- Verify the server script path is correct

**Papers not found**
- Make sure you've searched for papers first using `search_papers`
- Check that the `data/papers` directory exists and has write permissions

**arXiv API errors**
- The arXiv API has rate limits; wait a few seconds between searches
- Check your internet connection
- Verify the arXiv API is accessible (try accessing http://export.arxiv.org/api/query in browser)

### Client Issues

**Connection errors**
- Ensure the server script path in `connect()` is correct and absolute
- Check that Python is in your PATH
- Verify no other process is using the server

**Async runtime errors**
- Make sure you're running client code with `asyncio.run()`
- Don't mix async and sync code without proper await statements

**JSON parsing errors**
- Check that the server is returning valid JSON
- Ensure you're using the latest version of the client
- Try running the server standalone first to verify it works

**Import errors**
- Install all dependencies: `pip install -r requirements.txt`
- Verify you're in the correct directory
- Check Python path and virtual environment

## Contributing

Feel free to extend this server with additional features:
- Support for other academic databases (PubMed, Semantic Scholar)
- Paper similarity analysis
- Citation graph visualization
- Automatic literature review generation

## License

MIT License - feel free to use and modify for your projects.

## Learn More

- [FastMCP Documentation](https://github.com/jlowin/fastmcp)
- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
- [arXiv API Documentation](https://arxiv.org/help/api/)