Metadata-Version: 2.4
Name: crossref-cite-mcp
Version: 0.1.0
Summary: MCP tool for resolving paper citations via Crossref API with multiple format support
Project-URL: Homepage, https://github.com/h-lu/crossref-cite-mcp
Project-URL: Repository, https://github.com/h-lu/crossref-cite-mcp
Project-URL: Issues, https://github.com/h-lu/crossref-cite-mcp/issues
Author-email: Haibo Lu <luhaibo1985@gmail.com>
License-Expression: MIT
Keywords: bibliography,bibtex,citation,crossref,doi,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-vcr>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# crossref-cite-mcp

A Model Context Protocol (MCP) server for resolving paper citations via Crossref API. Supports multiple output formats including CSL-JSON, BibTeX, RIS, and formatted text.

## Features

- 🔍 **Smart Input Parsing**: Automatically detects DOIs, arXiv IDs, PMIDs, or falls back to bibliographic search
- 📚 **Multiple Citation Formats**: CSL-JSON, BibTeX, RIS, and formatted text (APA, Chicago, IEEE, etc.)
- ⚡ **Built-in Caching**: Memory or JSON file cache with configurable TTL (default: 14 days)
- 🔄 **Retry Logic**: Exponential backoff for rate limits (429) and server errors (5xx)
- 🎯 **Polite Pool Support**: Uses `mailto` parameter for higher Crossref rate limits

## Installation

```bash
# Clone the repository
git clone https://github.com/h-lu/crossref-cite-mcp.git
cd crossref-cite-mcp
```

### Using uv (Recommended)

```bash
# Install dependencies
uv sync

# Install with dev dependencies
uv sync --extra dev
```

### Using pip

```bash
# Install from source
pip install .

# Or install in editable mode (for development)
pip install -e ".[dev]"
```

## Configuration

Set environment variables (or create a `.env` file):

```bash
# Required: Your email for Crossref polite pool
export CROSSREF_MAILTO=your-email@example.com

# Optional: Cache configuration
export CROSSREF_CACHE_BACKEND=json        # "memory" or "json"
export CROSSREF_CACHE_PATH=~/.crossref-cite/cache.json
export CROSSREF_CACHE_TTL=1209600         # 14 days in seconds

# Optional: Logging
export LOG_LEVEL=INFO
```

## Usage

### As MCP Server (Claude Desktop / Cursor)

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

#### Using uv

```json
{
  "mcpServers": {
    "crossref-cite": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/crossref-cite-mcp", "python", "-m", "crossref_cite"],
      "env": {
        "CROSSREF_MAILTO": "your-email@example.com"
      }
    }
  }
}
```

#### Using pip (after `pip install .`)

```json
{
  "mcpServers": {
    "crossref-cite": {
      "command": "python",
      "args": ["-m", "crossref_cite"],
      "env": {
        "CROSSREF_MAILTO": "your-email@example.com"
      }
    }
  }
}
```

### Available Tools

#### `resolve_citation`

Resolve a paper and return citations in multiple formats.

**Arguments:**
- `query` (required): Paper title, DOI, arXiv ID, or PMID
- `formats`: List of formats (`["csl-json", "bibtex", "ris", "formatted"]`)
- `style`: CSL style for formatted output (default: `"apa"`)
- `locale`: Locale for formatted output (default: `"en-US"`)
- `rows`: Number of Crossref candidates (default: `5`)

**Example:**
```json
{
  "query": "Attention Is All You Need",
  "formats": ["bibtex", "formatted"],
  "style": "apa"
}
```

#### `search_papers`

Search Crossref for papers (metadata only, no citation fetching).

**Arguments:**
- `query` (required): Search query
- `rows`: Number of results (default: `10`, max: `20`)
- `filter_from_year`: Publication year filter (start)
- `filter_to_year`: Publication year filter (end)
- `filter_type`: Work type filter (e.g., `"journal-article"`)

### Direct CLI Testing

```bash
# Test with JSON-RPC request
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"resolve_citation","arguments":{"query":"10.1038/nature12373","formats":["bibtex"]}}}' | python -m crossref_cite
```

## Development

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

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=crossref_cite

# Lint
ruff check src tests

# Type check
mypy src/crossref_cite
```

### Recording VCR Cassettes

To record new HTTP interaction cassettes for tests:

```bash
# Delete existing cassettes and re-record
rm -rf tests/cassettes/
pytest tests/ -v --vcr-record=new_episodes
```

## Docker

```bash
# Build image
docker build -t crossref-cite-mcp .

# Run
docker run -e CROSSREF_MAILTO=your-email@example.com crossref-cite-mcp
```

## API Reference

### Crossref Best Practices

This implementation follows [Crossref REST API best practices](https://www.crossref.org/documentation/retrieve-metadata/rest-api/):

- ✅ Uses `mailto` parameter for polite pool access
- ✅ Implements exponential backoff for rate limits
- ✅ Caches results to reduce redundant requests
- ✅ Uses `query.bibliographic` for citation-like searches

### Content Negotiation

Citation formats are fetched via [DOI content negotiation](https://www.crossref.org/documentation/retrieve-metadata/content-negotiation/):

| Format | Accept Header |
|--------|--------------|
| CSL-JSON | `application/vnd.citationstyles.csl+json` |
| BibTeX | `application/x-bibtex` |
| RIS | `application/x-research-info-systems` |
| Formatted | `text/x-bibliography; style=apa; locale=en-US` |

## License

MIT
