# 📚 Literature MCP

[![MCP Version](https://img.shields.io/badge/MCP-1.0.0-blue)](https://modelcontextprotocol.io)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-green)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A specialized **Model Context Protocol (MCP)** server for biological and clinical evidence retrieval. This server provides a structured, agent-friendly interface to the **Europe PMC** database, enabling LLMs to gather, rank, and synthesize published research.

Built for the **Agent4Target** ecosystem, it focuses on high-confidence evidence collection for therapeutic targets and disease associations.

---

## 🏗️ Architecture & Workflow

The server performs semantic and keyword-based retrieval, transforming raw XML/JSON responses from Europe PMC into clean, machine-readable evidence models.

```mermaid
graph LR
    User([User / LLM Client]) <-->|MCP Protocol| Server[Literature MCP Server]
    
    subgraph "Internal Processing"
        Server --> Router{Tool Router}
        Router --> T1[collect_target_evidence]
        Router --> T2[search_articles]
        Router --> T3[get_article_by_pmid]
        
        T1 & T2 & T3 --> Client[EuropePMCClient]
        Client --> EPMC_API[[Europe PMC REST API]]
    end
    
    subgraph "Ranking Logic"
        Client --> Ranker[Citation & Recency Weighted Ranking]
        Ranker --> Pydantic[Pydantic Result Models]
        Pydantic --> Server
    end
```

---

## 🚀 Quick Start

### 1. Installation
```bash
pip install literature-mcp
```

### 2. Running the Server
The server is highly flexible and supports both **stdio** (standard for Claude Desktop) and **HTTP SSE** transport.

```bash
# Run over stdio (Standard)
literature-mcp --transport stdio

# Run as local HTTP server (SSE)
literature-mcp --port 8002
```

---

## 🛠️ Tools Documentation

### `collect_literature_target_evidence`
The primary tool for the Agent4Target workflow. It performs a multi-strategy search for a gene and disease context, returning the most cited and relevant evidence records.
- **Inputs**: 
  - `gene_symbol` (required, e.g., "BRAF")
  - `disease_id` (optional, e.g., "EFO_0000311")
  - `limit` (max records, default: 15)

### `search_literature_articles`
A flexible search tool that accepts raw Europe PMC query strings (e.g., `AUTHOR:"Vogelstein B" AND GENE:"KRAS"`).
- **Inputs**: `query` (string)

### `get_literature_article_by_pmid`
Retrieves full structured metadata for a specific article.
- **Inputs**: `pmid` (string)

### `get_literature_service_metadata`
Returns information about the underlying Europe PMC client, API rate limits, and health status.

---

## ⚙️ Configuration

| Variable | Default | Description |
| :--- | :--- | :--- |
| `LITERATURE_MCP_EUROPE_PMC_SEARCH_URL` | `https://www.ebi.ac.uk/...` | REST API endpoint. |
| `LITERATURE_MCP_HTTP_PORT` | `8002` | Port for SSE transport. |
| `LITERATURE_MCP_REQUEST_TIMEOUT_S` | `30` | Network timeout for API calls. |
| `LITERATURE_MCP_LOG_LEVEL` | `INFO` | Verbosity of server logs. |

---

## 🖥️ Usage in Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "literature-mcp": {
      "command": "literature-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "LITERATURE_MCP_LOG_LEVEL": "DEBUG"
      }
    }
  }
}
```

---

## 🧪 Development

The project uses `uv` for modern, fast dependency management.

```bash
# Clone and setup
git clone https://github.com/your-org/literature-mcp
cd literature-mcp
uv sync

# Run tests
uv run pytest
```

---

## 📄 License
MIT © 2026 Literature MCP Contributors. Part of the **Agent4Target** ecosystem.