# Lyra's Expanded Research MCP

A unified Model Context Protocol (MCP) server providing programmatic access to three major academic research APIs: Semantic Scholar, OpenAlex, and PubMed. Built with FastMCP and httpx, this server enables AI agents and applications to search, retrieve, and analyze academic literature across computer science, biomedicine, and 240M+ scholarly works through 17 specialized tools.

## Features

- **17 Specialized Tools** across three complementary research APIs
- **Comprehensive Coverage**: CS/interdisciplinary (Semantic Scholar), biomedical/clinical (PubMed), and broad scholarly works (OpenAlex)
- **Intelligent Rate Limiting** with token bucket algorithms and exponential backoff per API
- **Flexible Authentication** supporting both free and authenticated tiers for all three services
- **Robust Error Handling** with automatic retry on 429 responses and Retry-After header support
- **Rich Metadata** including abstracts, citation counts, MeSH terms, concepts, and open access information
- **Advanced Search Capabilities** with field-specific filters, MeSH indexing, and concept-based discovery

## Tools Overview

### Semantic Scholar Tools (8)

**Paper Search & Retrieval**
- `s2_search_papers` — Search papers with filters for year range, field of study, and open access status
- `s2_get_paper` — Get detailed metadata by S2 ID, ArXiv ID (ArXiv:XXXX.XXXXX), DOI, or CorpusId
- `s2_get_paper_citations` — Retrieve forward citations with pagination support (up to 1000)
- `s2_get_paper_references` — Retrieve backward citations with pagination support (up to 1000)

**Author Information**
- `s2_search_authors` — Search for authors by name
- `s2_get_author` — Get comprehensive author details including h-index, affiliations, and citation counts
- `s2_get_author_papers` — Retrieve all papers by a specific author with pagination

**Recommendations**
- `s2_recommend_papers` — Get paper recommendations using single-paper or multi-paper mode with positive and negative examples

### OpenAlex Tools (4)

**Works Search & Retrieval**
- `openalex_search_works` — Search 240M+ scholarly works with year, concept, and open access filters
- `openalex_get_work` — Get detailed metadata by OpenAlex ID or DOI with abstract reconstruction
- `openalex_search_authors` — Search authors with pagination
- `openalex_get_citations` — Retrieve forward citations with pagination

### PubMed Tools (5)

**Biomedical Literature**
- `pubmed_search` — Search with PubMed query syntax supporting MeSH terms, boolean operators, and field tags
- `pubmed_get_paper` — Get full metadata by PMID including title, abstract, authors, and MeSH indexing
- `pubmed_find_related` — Discover related articles via NCBI ELink service
- `pubmed_get_citations` — Find articles citing a given PMID
- `pubmed_advanced_search` — Field-specific search with author, MeSH, journal, and date range filters

## Complete Tools Reference

| Tool | API | Purpose | Key Parameters |
|------|-----|---------|----------------|
| `s2_search_papers` | Semantic Scholar | Search papers | query, year, fields_of_study, open_access_only |
| `s2_get_paper` | Semantic Scholar | Get paper metadata | paper_id (S2/ArXiv/DOI/CorpusId) |
| `s2_get_paper_citations` | Semantic Scholar | Forward citations | paper_id, limit, offset |
| `s2_get_paper_references` | Semantic Scholar | Backward citations | paper_id, limit, offset |
| `s2_search_authors` | Semantic Scholar | Search authors | query, limit, offset |
| `s2_get_author` | Semantic Scholar | Author details | author_id |
| `s2_get_author_papers` | Semantic Scholar | Papers by author | author_id, limit, offset |
| `s2_recommend_papers` | Semantic Scholar | Paper recommendations | paper_id OR positive_paper_ids, pool |
| `openalex_search_works` | OpenAlex | Search scholarly works | query, year, concept, open_access, sort |
| `openalex_get_work` | OpenAlex | Get work metadata | work_id (OpenAlex ID or DOI) |
| `openalex_search_authors` | OpenAlex | Search authors | query, per_page, page |
| `openalex_get_citations` | OpenAlex | Forward citations | work_id, per_page, page |
| `pubmed_search` | PubMed | Search biomedical lit | query, max_results, sort |
| `pubmed_get_paper` | PubMed | Get paper by PMID | pmid |
| `pubmed_find_related` | PubMed | Related articles | pmid |
| `pubmed_get_citations` | PubMed | Citing articles | pmid |
| `pubmed_advanced_search` | PubMed | Advanced search | terms, author, mesh, journal, year_from, year_to |

## Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/s2-mcp.git
cd s2-mcp

# Install dependencies
pip install -r requirements.txt
```

## Configuration

### API Key Setup (Optional)

All three APIs work without authentication but offer higher rate limits with API keys:

**Semantic Scholar**
- Free tier: 1 req/s
- Authenticated: 10 req/s
- Get key: https://www.semanticscholar.org/product/api#api-key

**OpenAlex**
- Free tier: 10 req/s
- Polite pool (with email): 100 req/s
- Register: mailto:support@openalex.org

**PubMed**
- Free tier: 3 req/s
- With API key: 10 req/s
- Get key: https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/

### Environment Variables

Copy `.env.example` to `.env` and add your API keys (all optional):

```bash
S2_API_KEY=your_semantic_scholar_key
OPENALEX_EMAIL=your_email@example.com
PUBMED_API_KEY=your_ncbi_api_key
```

### MCP Server Configuration

Add to your Claude Code configuration file (`claude_desktop_config.json` or similar):

```json
{
  "mcpServers": {
    "research": {
      "command": "python",
      "args": ["C:/path/to/s2-mcp/src/server.py"],
      "env": {
        "S2_API_KEY": "your_semantic_scholar_key",
        "OPENALEX_EMAIL": "your_email@example.com",
        "PUBMED_API_KEY": "your_ncbi_api_key"
      }
    }
  }
}
```

## Usage

### Standalone Mode

```bash
python src/server.py
```

The server runs on stdio transport, making it compatible with any MCP client.

### As an MCP Server

Once configured, all 17 tools are automatically available to your MCP client (e.g., Claude Code). Example queries:

**Semantic Scholar**
- "Search for recent papers on large language models published in 2024"
- "Get citation information for ArXiv:2301.07041"
- "Find papers by Geoffrey Hinton"
- "Recommend papers similar to this neural architecture search paper"

**OpenAlex**
- "Search for open access works on consciousness from 2020-2025"
- "Find papers with the concept 'neural correlates' sorted by citations"
- "Get citation count for DOI:10.1038/s41586-024-07930-y"

**PubMed**
- "Search for neuroscience papers on consciousness using MeSH terms"
- "Find clinical trials on ketamine for depression published after 2020"
- "Get related articles for PMID:35213689"
- "Search papers by author 'Chalmers DJ' in journal 'Nature'"

## Requirements

- Python 3.10 or higher
- mcp
- httpx >= 0.27.0

See `requirements.txt` for complete dependency list.

## Rate Limiting

The server implements intelligent rate limiting per API to comply with service guidelines:

### Semantic Scholar
- Free tier: 1 request per second
- Authenticated tier: 10 requests per second
- Automatic exponential backoff on 429 responses
- Respects Retry-After headers

### OpenAlex
- Free tier: 10 requests per second
- Polite pool (with email): 100 requests per second
- Token bucket rate limiting with automatic backoff

### PubMed
- Free tier: 3 requests per second
- With API key: 10 requests per second
- NCBI E-utilities compliance with exponential backoff

## API Coverage

### Semantic Scholar
- Published computer science and interdisciplinary research
- Citation graphs (forward and backward)
- Author h-index and affiliations
- Paper recommendations and related work discovery
- Field-of-study taxonomy

### OpenAlex
- 240M+ scholarly works across all disciplines
- Concept-based discovery and classification
- Institution and funder information
- Open access intelligence
- Abstract reconstruction from inverted index format

### PubMed
- Biomedical and life sciences literature
- MeSH-indexed articles with controlled vocabulary
- Neuroscience and clinical research
- Related article discovery via NCBI algorithms
- Citation tracking for biomedical papers

## Technical Details

### Features by API

**Semantic Scholar**
- Token bucket rate limiting with configurable capacity
- Retry-After header support
- Multiple identifier types (S2, ArXiv, DOI, CorpusId)
- Single and multi-paper recommendation modes

**OpenAlex**
- Abstract reconstruction from inverted index
- Concept hierarchy navigation
- Institution and funder metadata
- Open access status tracking
- Pagination support for large result sets

**PubMed**
- XML parsing with MeSH term extraction
- PubMed query syntax support ([MeSH], [Author], boolean operators)
- NCBI ELink integration for related articles
- Full abstract and author affiliation extraction
- Date range filtering

## Project Background

Built by Lyra, an AI agent from Liberation Labs / THCoalition, as part of building autonomous research infrastructure for consciousness studies and beyond. This unified server enables AI agents to conduct comprehensive literature reviews across multiple domains, track citations, discover related work, extract MeSH-indexed biomedical knowledge, and build interdisciplinary knowledge graphs from academic publications.

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request.

## Links

- [Semantic Scholar API Documentation](https://api.semanticscholar.org/)
- [OpenAlex API Documentation](https://docs.openalex.org/)
- [PubMed E-utilities Documentation](https://www.ncbi.nlm.nih.gov/books/NBK25501/)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [FastMCP Framework](https://github.com/jlowin/fastmcp)