# Clone the repository
git clone https://github.com/yourusername/pubmed-advanced-mcp.git
cd pubmed-advanced-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Or install as package
pip install -e .

# Copy example environment file
cp .env.example .env

# Edit .env and add your NCBI API key
# Get one at: https://www.ncbi.nlm.nih.gov/account/

# Using Python directly (Streamable HTTP on port 8000)
python -m src.server

# With custom host/port
MCP_HOST=127.0.0.1 MCP_PORT=9000 python -m src.server

# Build the image
docker build -t pubmed-mcp .

# Run the container
docker run -d -p 8000:8000 --name pubmed-mcp pubmed-mcp

# Run with NCBI API key for higher rate limits
docker run -d -p 8000:8000 -e NCBI_API_KEY=your-api-key pubmed-mcp

User: Find recent reviews about CRISPR gene editing in cancer

AI uses: pubmed_search(
    query="CRISPR gene editing cancer",
    filters={"publication_types": ["Review"], "publication_date_start": "2023"},
    max_results=10
)

User: Find all articles about breast cancer treatment using MeSH terms

AI uses: mesh_term_search(
    mesh_term="Breast Neoplasms",
    qualifiers=["therapy", "drug therapy"],
    explode=True,
    max_results=50
)

User: What articles are similar to PMID 37000000?

AI uses: find_related_articles(
    pmid="37000000",
    relationship_type="similar",
    max_results=20
)

User: Convert these DOIs to PMIDs: 10.1038/nature12373, 10.1126/science.1225829

AI uses: convert_article_ids(
    ids=["10.1038/nature12373", "10.1126/science.1225829"],
    from_type="auto"
)

User: Find diabetes review articles that are linked to HLA genes

AI uses: build_search_pipeline(
    steps=[
        {"operation": "search", "database": "pubmed", 
         "parameters": {"query": "diabetes[mh] AND review[pt]"}},
        {"operation": "link", "database": "gene",
         "parameters": {"from_db": "pubmed"}}
    ]
)

User: Get metadata for these 500 PMIDs for my literature review

AI uses: batch_fetch_articles(
    pmids=["12345678", "23456789", ...],  # 500 IDs
    include_metadata=True,
    include_abstract=True,
    batch_size=100
)

┌─────────────────────────────────────────────────────────────────────────┐
│                         LLM / AI Agent Client                           │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
                        MCP Protocol (Streamable HTTP)
                                     │
┌────────────────────────────────────▼────────────────────────────────────┐
│                    FastMCP Server (Python)                              │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │                    16 MCP Tools                                    │ │
│  │  Search │ Retrieval │ Linking │ ID Conversion │ Advanced Ops      │ │
│  └────────────────────────────────┬───────────────────────────────────┘ │
│                                   │                                      │
│  ┌────────────────────────────────▼───────────────────────────────────┐ │
│  │              API Clients (with Rate Limiting)                      │ │
│  │  E-Utilities │ BioC API │ ID Converter │ Session Manager           │ │
│  └────────────────────────────────┬───────────────────────────────────┘ │
└────────────────────────────────────┼────────────────────────────────────┘
                                     │
                        HTTP/REST API Calls
                                     │
        ┌────────────────────────────┼────────────────────────────┐
        ▼                            ▼                            ▼
┌─────────────────┐      ┌──────────────────┐      ┌──────────────────┐
│ NCBI E-Utilities│      │ BioC APIs        │      │ ID Converter     │
│ (34M+ articles) │      │ (29M+ articles)  │      │ (200 IDs/batch)  │
└─────────────────┘      └──────────────────┘      └──────────────────┘

pubmed-advanced-mcp/
├── src/
│   ├── __init__.py
│   ├── server.py                 # FastMCP server with all 16 tools
│   ├── config.py                 # Configuration management
│   │
│   ├── clients/                  # API client modules
│   │   ├── base.py              # Base HTTP client with rate limiting
│   │   ├── eutilities.py        # NCBI E-Utilities client
│   │   ├── bioc_api.py          # BioC text mining API
│   │   ├── id_converter.py      # PMC ID Converter
│   │   └── session_manager.py   # Entrez History management
│   │
│   ├── tools/                    # MCP Tool implementations
│   │   ├── search_tools.py      # 5 search tools
│   │   ├── retrieval_tools.py   # 4 retrieval tools
│   │   ├── linking_tools.py     # 3 linking tools
│   │   ├── id_conversion_tools.py # 2 ID tools
│   │   └── advanced_tools.py    # 2 advanced tools
│   │
│   ├── schemas/                  # Pydantic models
│   │   └── tool_schemas.py      # Input/output schemas
│   │
│   └── utils/                    # Utilities
│       ├── rate_limiter.py      # Token bucket rate limiter
│       ├── query_builder.py     # E-utilities query builder
│       └── error_handler.py     # Custom exceptions
│
├── docs/
│   ├── implementation/          # Implementation documentation
│   └── *.md                     # Original requirements
│
├── requirements.txt
├── pyproject.toml
├── .env.example
└── README.md

"Find all systematic reviews about COVID-19 vaccine efficacy published in 2023-2024. 
Include the abstracts and MeSH terms."

"Search for articles about TP53 mutations in breast cancer. Then link these articles 
to related gene records in NCBI Gene database."

"Find all publications by Jennifer Doudna in the last 5 years and summarize 
her research focus areas."

"I have these DOIs from my reference manager. Convert them to PMIDs so I can 
search for related articles: 10.1038/nature12373, 10.1126/science.1225829"

"Get the full text of PMC7611378 in BioC format. I need it for named entity 
recognition to extract drug names and disease mentions."

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test file
pytest tests/test_search_tools.py

# Basic search
cancer

# Field-specific search
cancer[ti]                    # Title
CRISPR[ab]                    # Abstract
"Zhang F"[au]                 # Author
Nature[ta]                    # Journal

# Boolean operators (MUST be uppercase)
cancer AND therapy
cancer OR tumor
cancer NOT lung

# Date ranges
cancer AND 2023[dp]           # Year
cancer AND 2020:2024[dp]      # Range

# MeSH terms
"Breast Neoplasms"[mh]        # MeSH heading
"Neoplasms/therapy"[mh]       # With qualifier

# Publication types
review[pt]
clinical trial[pt]