# AIPaper-assisant User Guide

## 🚀 Quick Start

### Prerequisites
- Node.js ≥ 18.0.0
- npm or yarn package manager
- API keys for premium platforms (optional)

### Installation

1. **Clone the repository**
```bash
git clone https://github.com/yourusername/paper-search-nodejs.git
cd paper-search-nodejs
```

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

3. **Configure environment**
```bash
cp .env.example .env
# Edit .env with your API keys
```

4. **Build the project**
```bash
npm run build
```

5. **Start the MCP server**
```bash
npm start
```

## 🔧 Configuration

### Environment Variables

Create a `.env` file in the project root:

```bash
# Required for Web of Science
WOS_API_KEY=your_wos_api_key_here

# Required for Scopus
SCOPUS_API_KEY=your_scopus_api_key_here

# Required for ScienceDirect
SCIENCEDIRECT_API_KEY=your_elsevier_api_key_here

# Required for Springer
SPRINGER_API_KEY=your_springer_api_key_here

# Required for Wiley TDM
WILEY_API_KEY=your_wiley_api_key_here

# Optional: MCP server configuration
MCP_SERVER_NAME=paper-search-mcp
MCP_SERVER_VERSION=0.2.3
```

### Getting API Keys

#### Web of Science
1. Visit [Clarivate Developer Portal](https://developer.clarivate.com/)
2. Register for an account
3. Subscribe to Web of Science API
4. Copy your API key

#### Scopus
1. Visit [Elsevier Developer Portal](https://dev.elsevier.com/)
2. Create an account
3. Register your application
4. Get your API key

#### ScienceDirect & Scopus
1. Both use the same Elsevier API key
2. Ensure your subscription includes the required APIs

#### Springer
1. Visit [Springer Nature API Portal](https://dev.springernature.com/)
2. Register your application
3. Obtain API credentials

#### Wiley
1. Contact Wiley directly for TDM API access
2. Provide your use case details
3. They will provision API access

## 📖 Basic Usage

### With Claude Desktop

1. **Configure Claude Desktop**
Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "paper-search": {
      "command": "node",
      "args": ["/path/to/paper-search-nodejs/dist/server.js"],
      "env": {
        "WOS_API_KEY": "your_wos_api_key",
        "SCOPUS_API_KEY": "your_scopus_api_key"
      }
    }
  }
}
```

2. **Restart Claude Desktop**
3. **Use natural language to search**

Example queries:
- "Search for papers about machine learning on arXiv"
- "Find recent quantum computing research from 2023"
- "Download the paper with DOI 10.1000/example"

### Programmatic Usage

```javascript
import { McpClient } from '@modelcontextprotocol/sdk';

const client = new McpClient();
await client.connect('paper-search');

// Search for papers
const results = await client.callTool('search_papers', {
  query: 'machine learning transformers',
  platform: 'arxiv',
  maxResults: 10
});

// Download a paper
const download = await client.callTool('download_paper', {
  doi: '10.1000/example',
  platform: 'arxiv'
});
```

## 🔍 Search Examples

### Basic Search

**Search across all platforms:**
```
Search for papers about climate change
```

**Search specific platform:**
```
Search for quantum computing papers on arXiv
```

**Limit results:**
```
Find 5 papers about CRISPR on PubMed
```

### Advanced Search

**Year range filtering:**
```
Search for AI papers from 2020-2024 on Web of Science
```

**Multiple platforms:**
```
Search for COVID-19 papers on both PubMed and bioRxiv
```

**Citation-focused search:**
```
Find highly cited papers about blockchain on Scopus
```

## 📥 Download Examples

### Download by DOI
```
Download the paper with DOI 10.1038/s41586-023-06083-9
```

### Download from specific platform
```
Download a machine learning paper from arXiv
```

### Download with title hint
```
Download the paper titled "Attention Is All You Need" from arXiv
```

## 🛠️ Platform-Specific Features

### arXiv
- **Categories**: Search within specific categories (cs.AI, physics.gen-ph, etc.)
- **Date sorting**: Get newest papers first
- **PDF download**: Direct access to full papers

Example:
```
Search for recent computer vision papers in cs.CV category on arXiv
```

### Web of Science
- **Multi-topic search**: Use boolean operators (AND, OR, NOT)
- **Citation tracking**: Find highly cited papers
- **Research areas**: Filter by field of study

Example:
```
Search for "machine learning" AND "healthcare" on Web of Science, sorted by citations
```

### PubMed
- **MeSH terms**: Medical Subject Headings for precise search
- **Clinical queries**: Specialized search filters
- **Gene/protein search**: Biological entity recognition

Example:
```
Search for papers about BRCA1 gene mutations on PubMed
```

### Google Scholar
- **Comprehensive coverage**: Includes journals, conferences, theses
- **Citation network**: Related papers and citing articles
- **Author profiles**: Researcher publication lists

Example:
```
Find all papers by Geoffrey Hinton on Google Scholar
```

### Sci-Hub
- **Universal access**: Works with any DOI
- **Mirror management**: Automatic healthy mirror selection
- **Legal notice**: Use only for research purposes

Example:
```
Access the paper with DOI 10.1126/science.abc123 through Sci-Hub
```

## ⚠️ Important Notes

### Rate Limiting
- Be respectful of platform resources
- Default limits are conservative
- Higher limits available with API keys
- Automatic retry with exponential backoff

### Legal Compliance
- Respect copyright laws
- Use downloads for research only
- Follow platform terms of service
- Sci-Hub usage may have legal implications

### Data Quality
- Results vary by platform coverage
- Crossref provides most comprehensive metadata
- Preprints (arXiv) are not peer-reviewed
- Always verify publication status

## 🔧 Troubleshooting

### Common Issues

#### "No results found"
- Try broader search terms
- Check spelling
- Try different platforms
- Use English terms for better coverage

#### "API key required"
- Some platforms need API keys
- Check your .env configuration
- Verify key is valid
- Check platform subscription status

#### "Rate limit exceeded"
- Wait a moment before retrying
- Reduce search frequency
- Consider upgrading API plan
- Use multiple platforms alternately

#### "Download failed"
- Verify DOI is correct
- Paper may not be openly available
- Try different download platform
- Check if paper exists in open access

### Debug Mode

Enable debug logging:
```bash
DEBUG=paper-search:* npm start
```

### Platform Status

Check platform health:
```
Show me the status of all platforms
```

## 📚 Best Practices

### Search Tips
1. **Use specific terms**: "convolutional neural networks" vs "neural networks"
2. **Combine concepts**: "machine learning" AND "healthcare"
3. **Use quotes**: "exact phrase search"
4. **Try synonyms**: "COVID-19" OR "coronavirus"
5. **Filter by year**: Focus on recent research

### Download Tips
1. **Use DOI**: Most reliable identifier
2. **Check multiple sources**: Different platforms may have access
3. **Respect rate limits**: Don't overwhelm services
4. **Verify files**: Ensure downloads are complete
5. **Cite properly**: Give credit to authors

### Research Workflow
1. Start broad search on Crossref
2. Refine with platform-specific search
3. Check citations for related work
4. Download relevant papers
5. Organize findings

## 🔗 Integration Examples

### Zotero Integration
Export results and import to Zotero for reference management.

### LaTeX Integration
Generate BibTeX entries from search results.

### Jupyter Notebook
```python
# Example Python integration
import subprocess
import json

result = subprocess.run([
    'node', 'dist/server.js',
    'search_papers',
    '--query', 'machine learning',
    '--platform', 'arxiv'
], capture_output=True, text=True)

papers = json.loads(result.stdout)
```

## 📞 Support

### Getting Help
1. Check this documentation
2. Review error messages carefully
3. Check platform status
4. Search existing issues
5. Create detailed bug reports

### Reporting Issues
Include:
- Platform being used
- Search query
- Error message
- Expected vs actual behavior
- Environment details

### Contributing
1. Read contributing guidelines
2. Fork the repository
3. Create feature branch
4. Add tests for new features
5. Submit pull request

---

*This user guide covers the essential features of AIPaper-assisant. For advanced usage and development, see the [Developer Documentation](./DEVELOPER_GUIDE.md).*