Research 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:

pip install -r requirements.txt

Running the Server

Standalone Mode

Run the server directly:

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:

{
  "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:

python example_usage.py

This will show you an interactive menu with various examples.

Basic Client Usage

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

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

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)

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
• Model Context Protocol Specification
• arXiv API Documentation