pubmed_mcp_server2/README.md

Advanced Model Context Protocol server for PubMed database access with MeSH optimization and citation analysis

# PubMed MCP Server v2 (Version 1.1.3)

A comprehensive Model Context Protocol (MCP) server that provides advanced access to the PubMed database for biomedical literature search, retrieval, and analysis. This server transforms natural language queries into optimized PubMed searches using MeSH terms and provides citation analysis capabilities.

## 🚀 Features

### 🔧 Tools

- **`search_pubmed`**: Search PubMed with pagination, sorting, output modes, and structured filters
- **`get_full_abstract`**: Retrieve complete, untruncated abstracts for specific articles by PMID
- **`get_full_text`**: Extract full text from PMC with section filtering (Methods, Results, etc.)
- **`export_ris`**: Export citations in RIS format for reference management software
- **`get_citation_counts`**: Analyze citation metrics and find citing articles
- **`find_similar_articles`**: Find articles similar to a given PMID with relevance scores
- **`batch_process`**: Process multiple PMIDs with multiple operations efficiently
- **`count_results`**: Get search result count without fetching articles (lightweight)
- **`convert_ids`**: Convert between PMID, PMCID, and DOI identifiers

### 📚 Resources

- **`pubmed://search/{query}`**: Access search results as structured JSON resource

### 💡 Prompts

- **`generate_search_query`**: Interactive assistant for creating effective PubMed search strategies

## 📋 Prerequisites

- Node.js v18.x or higher
- npm or yarn package manager

## 🎯 Usage

### Method 1: NPM Package (Recommended)

**Benefits**: Easy installation, automatic updates, no local build required.


#### Claude Desktop Configuration
Add to your Claude Desktop configuration file:

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

```json
{
  "mcpServers": {
    "pubmed": {
      "command": "npx",
      "args": ["-y", "pubmed_mcp_server2"]
    }
  }
}
```

#### Claude Code Configuration
```bash
claude mcp add pubmed -s project -- cmd /c npx pubmed_mcp_server2
```

### Method 2: Local Development

**Use case**: For development, customization, or when you want to modify the source code.
## 🛠️ Installation

1. Clone this repository:
```bash
git clone https://github.com/YOUR_USERNAME/pubmed_mcp_server2.git
cd pubmed_mcp_server2
```

2. Install dependencies:
```bash
npm install
```

3. Build the server:
```bash
npm run build
```

#### Claude Desktop Integration (Local)

Add to your Claude Desktop configuration file:

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

```json
{
  "mcpServers": {
    "pubmed-server": {
      "command": "node",
      "args": ["C:\\path\\to\\pubmed_mcp_server2\\dist\\index.js"],
      "env": {}
    }
  }
}
```

Replace the path with your actual installation directory.

### Example Usage

#### 1. Search with Pagination and Sorting (NEW in v1.1.0)
```javascript
search_pubmed: {
  query: "COVID-19 vaccine",
  maxResults: 10,
  retstart: 0,           // Start from first result
  sort: "pub_date",      // Sort by Most Recent
  output_mode: "compact" // Minimal output for context savings
}
→ Returns: JSON with total count, compact article list, and next_start for pagination
```

#### 2. Search with Filters (NEW in v1.1.0)
```javascript
search_pubmed: {
  query: "diabetes treatment",
  filters: {
    publication_types: ["Clinical Trial", "Meta-Analysis"],
    date_range: { start: "2020", end: "2024" },
    languages: ["eng"],
    humans_only: true,
    free_full_text: true
  }
}
```

#### 3. Count Results (NEW in v1.1.0)
```javascript
count_results: { query: "CRISPR gene editing" }
→ Returns: { query, queryTranslation, count: 15234 }
// Lightweight - no article details fetched
```

#### 4. ID Conversion
```javascript
convert_ids: { ids: ["33301246"], from_type: "pmid", to_type: "pmcid" }
→ Returns: { conversions: [{ pmid: "33301246", pmcid: "PMC7745181", doi: "10.1056/..." }] }
```

#### 5. Full Text with Section Filter
```javascript
get_full_text: {
  pmcIds: ["PMC7745181"],
  sections: ["methods", "results"]  // Only fetch Methods and Results
}
→ Saves 70-90% context compared to full text
```

#### 6. Citation Analysis
```
get_citation_counts: "36038128, 30105375"
→ Returns: Citation counts and lists of citing articles for each PMID
```

#### 7. Find Similar Articles
```
find_similar_articles: { pmid: "36038128", maxResults: 10 }
→ Returns: Similar articles ranked by NCBI's similarity algorithm with scores
```

#### 8. Batch Processing
```javascript
batch_process: {
  pmids: ["36038128", "35105375"],
  operations: ["abstract", "citations", "similar"]
}
→ Returns: Comprehensive analysis of multiple articles in one request
```

## 📉 Context Optimization (NEW in v1.1.0)

### Output Modes for search_pubmed

| Mode | Use Case | Token Savings |
|------|----------|---------------|
| `compact` | Standard searches, batch operations | ~70% |
| `full` | Detailed analysis (default) | 0% |

Note: For count-only queries, use the `count_results` tool instead.

### Section Filtering for get_full_text

| Sections | Typical Size | Use Case |
|----------|--------------|----------|
| `["all"]` | 10,000-50,000 tokens | Complete article review |
| `["methods"]` | 1,000-3,000 tokens | Methodology analysis |
| `["results", "discussion"]` | 3,000-8,000 tokens | Findings summary |
| `["abstract"]` | 200-500 tokens | Quick overview |

## 🧠 MeSH Term Optimization

The server includes an extensive database of medical term mappings covering:

- **COVID-19 & Vaccines**: covid, coronavirus, vaccination, immunization
- **Cardiovascular**: heart attack, myocardial infarction, cardiovascular disease
- **Cancer**: cancer, tumor, oncology, carcinoma
- **Mental Health**: depression, anxiety, psychiatric disorders
- **Age Groups**: elderly, children, pediatric, adolescent
- **Study Types**: clinical trial, meta-analysis, systematic review, RCT
- **Treatment Types**: therapy, surgery, medication, drug treatment

## 🔧 Advanced Search Features

### Field Tags Supported
- `[ti]` - Title
- `[ab]` - Abstract
- `[au]` - Author
- `[ta]` - Journal Title
- `[MeSH Terms]` - Medical Subject Headings
- `[tw]` - Text Word
- `[pt]` - Publication Type
- `[pdat]` - Publication Date

### Boolean Operators
- `AND` - All terms must be present
- `OR` - Any of the terms can be present
- `NOT` - Exclude specific terms
- Parentheses for grouping complex queries

## 📊 API Endpoints & Rate Limiting

### NCBI E-utilities APIs Used
- **ESearch**: Search and retrieve primary IDs
- **EFetch**: Retrieve full records and abstracts
- **ESummary**: Retrieve document summaries
- **ELink**: Find related articles and citations
- **Literature Citation Exporter**: RIS format export

### Rate Limiting & Limits
- **Search results**: Maximum 100 articles per query
- **Citation analysis**: Maximum 20 PMIDs per request
- **RIS export**: Maximum 50 PMIDs per batch
- **Full text**: Maximum 10 PMC articles per request
- **Similar articles**: Maximum 50 similar articles per PMID (default: 10)
- **Batch processing**: Maximum 50 PMIDs per batch with up to 5 concurrent operations
- **API delays**: 200-600ms between requests to respect NCBI guidelines

## ⚙️ Configuration

### Customizable Parameters

Edit `src/pubmed-api.ts` to modify:

```typescript
// Email for NCBI API (required by NCBI guidelines)
email: 'your-email@example.com'

// Rate limiting delays
const delayBetweenRequests = 200; // milliseconds

// Result limits
const maxResults = 100; // search results
const maxPmids = 20;    // citation analysis
```

## 🔍 Error Handling

Comprehensive error handling for:
- Network connectivity issues
- Invalid PMIDs or queries
- API rate limiting and timeouts
- XML/JSON parsing errors
- Missing full text content
- Citation data unavailability

## 🚧 Development

### Available Scripts

```bash
npm run build      # Compile TypeScript
npm run dev        # Build and run in development
npm run clean      # Remove compiled files
npm run start      # Start the compiled server
```

### Project Structure

```
pubmed_mcp_server2/
├── src/
│   ├── index.ts           # Main MCP server setup and tool registration
│   └── pubmed-api.ts      # PubMed API integration and utilities
├── dist/                  # Compiled JavaScript output
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
└── README.md             # This file
```

### Adding New Features

1. **New MeSH mappings**: Add to `MESH_MAPPINGS` object in `pubmed-api.ts`
2. **New tools**: Register in `index.ts` using `server.registerTool()`
3. **Field tags**: Add to `FIELD_TAGS` object for query optimization

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes and test thoroughly
4. Commit with descriptive messages: `git commit -m "Add feature description"`
5. Push to your branch: `git push origin feature-name`
6. Submit a pull request

## 📖 Documentation

### PubMed Search Tips

1. **Use MeSH terms** for standardized medical vocabulary
2. **Combine multiple concepts** with AND/OR operators
3. **Use field tags** to target specific parts of articles
4. **Add date ranges** to focus on recent research
5. **Filter by publication type** for specific study designs

### Reference Management Integration

The RIS export feature supports:
- **Zotero**: File → Import
- **Mendeley**: File → Import → RIS
- **EndNote**: File → Import → File
- **Papers**: Import → From File
- **RefWorks**: Import → References

## 🛡️ Privacy & Ethics

- No user data is stored or logged
- All queries are sent directly to NCBI APIs
- Complies with NCBI usage guidelines
- Respects API rate limits and terms of service

## 📄 License

MIT License - see LICENSE file for details

## 🙋‍♂️ Support

For issues, questions, or contributions:
1. Check existing issues on GitHub
2. Create a new issue with detailed description
3. Include error messages and steps to reproduce

## 📦 Installation Options

### Quick Start (NPM)
```bash
npm install -g pubmed_mcp_server2
```

### Update to Latest Version
```bash
npm update -g pubmed_mcp_server2
```

## 📝 Version History

### v1.1.3 (Latest)
- 🔧 **Removed**: `lookup_mesh` tool (unstable API)
- 🧹 **Cleanup**: Streamlined codebase

### v1.1.1
- 🔧 **Removed**: `optimize_search_query` tool (redundant)
- 🔧 **Removed**: `minimal` output mode from search_pubmed (use `count_results` instead)
- 🧹 **Cleanup**: Removed unnecessary emojis and decorative separators from output

### v1.1.0
- 🆕 **Pagination & Sorting**: `retstart` for accessing 101+ results, `sort` for relevance/pub_date/first_author
- 🆕 **Output Modes**: `compact`, `full` - reduce context consumption by ~70%
- 🆕 **Structured Filters**: Filter by publication_types, date_range, languages, has_abstract, free_full_text, humans_only
- 🆕 **count_results Tool**: Lightweight result counting without fetching articles
- 🆕 **convert_ids Tool**: PMID ⇔ PMCID ⇔ DOI conversion via NCBI ID Converter API
- 🆕 **Section Filtering**: `get_full_text` now supports extracting specific sections (methods, results, etc.)

### v1.0.2
- 🆕 **Batch Processing**: Process multiple PMIDs with multiple operations efficiently
- 🔧 **Flexible Input**: Support for array, space-separated, and comma-separated PMID input
- 📊 **Enhanced Analytics**: Improved citation analysis and error reporting
- ⚡ **Performance**: Optimized API rate limiting and concurrent processing

### v1.0.1
- 🆕 **Similar Articles**: Find articles similar to a given PMID using NCBI's algorithm
- 🎯 **Improved Relevance**: Similarity scores and ranking
- 🔧 **Bug Fixes**: Enhanced error handling and API stability

### v1.0.0
- 🚀 **Initial Release**: Core PubMed search and analysis functionality
- 📖 **Full Features**: Search, abstracts, citations, RIS export, query optimization

## 🔗 Related Resources

- [NCBI E-utilities Documentation](https://www.ncbi.nlm.nih.gov/books/NBK25497/)
- [PubMed Search Tips](https://pubmed.ncbi.nlm.nih.gov/help/)
- [MeSH Database](https://www.ncbi.nlm.nih.gov/mesh/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/download)