Metadata-Version: 2.4
Name: search-citation-mcp
Version: 1.1.0
Summary: Academic paper search and IEEE citation engine — MCP server with 9 tools
Project-URL: Homepage, https://github.com/isaacwars/search-citation-mcp
Project-URL: Repository, https://github.com/isaacwars/search-citation-mcp
Project-URL: Issues, https://github.com/isaacwars/search-citation-mcp/issues
Author-email: isaacwars <isaacwars@users.noreply.github.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: academic,bibtex,citation,crossref,ieee,mcp,openalex,paper-search,semantic-scholar
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing :: Markup :: LaTeX
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: bibtexparser>=2.0.0b7
Requires-Dist: curl-cffi>=0.7.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rapidfuzz>=3.0.0
Requires-Dist: requests>=2.28.0
Description-Content-Type: text/markdown

# Search & Citation MCP

Academic search and IEEE citation engine as an MCP (Model Context Protocol) server. Designed to integrate with AI coding assistants (Claude Desktop, Cursor, opencode) and MCP daemons.

**9 tools** that allow an LLM to search papers across 3 sources (OpenAlex + Crossref + Semantic Scholar), validate metadata, generate `biblatex-ieee` BibTeX citations, download open-access PDFs, and maintain a bibliography.

[![PyPI version](https://img.shields.io/pypi/v/search-citation-mcp)](https://pypi.org/project/search-citation-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/search-citation-mcp)](https://pypi.org/project/search-citation-mcp/)
[![License](https://img.shields.io/pypi/l/search-citation-mcp)](https://github.com/isaacwars/search-citation-mcp/blob/main/LICENSE)

## Quick Start (uvx — zero install)

Add to your MCP client configuration:

### Claude Desktop

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "search-citation": {
      "command": "uvx",
      "args": ["search-citation-mcp"]
    }
  }
}
```

### Cursor / opencode

`opencode.json` or Cursor MCP config:

```json
{
  "mcpServers": {
    "search-citation": {
      "command": "uvx",
      "args": ["search-citation-mcp"]
    }
  }
}
```

### HTTP Mode (multi-client / daemon)

Expose the server on the network for multiple simultaneous clients:

```json
{
  "mcpServers": {
    "search-citation": {
      "command": "uvx",
      "args": ["search-citation-mcp", "--transport", "streamable-http"],
      "env": {
        "MCP_HOST": "0.0.0.0",
        "MCP_PORT": "8000"
      }
    }
  }
}
```

## Configuration (.env)

Create a `.env` file (or set environment variables in your MCP client config):

```bash
# Optional: better rate limits and features
OPENALEX_API_KEY=          # OpenAlex API key
SEMANTIC_SCHOLAR_API_KEY=  # Enables semantic search (third source)
CROSSREF_MAILTO=           # Polite pool email for Crossref
UNPAYWALL_EMAIL=           # Enables Unpaywall PDF downloads

# Optional: bibliography path
BIBLIOGRAPHY_PATH=./bibliografia.bib

# Optional: institutional proxy
EZPROXY_HOST=bibliotecabuap.elogim.com

# Optional: Sci-Hub fallback
SCIHUB_ENABLED=1
```

## MCP Tools

| Tool | Description |
|---|---|
| `search_papers` | Search papers via OpenAlex + Crossref + Semantic Scholar (3 sources in parallel) |
| `add_from_doi` | Add citation by DOI with Crossref → S2 → OpenAlex validation pipeline |
| `cite_paper` | Generate `.bib` entry without writing to file |
| `add_to_bibliography` | Add manual entry to `.bib` (CFE, NOM, IEC, thesis, datasheets) |
| `find_related_papers` | Find related papers via citation graph + semantic similarity |
| `detect_input` | Detect whether text is a DOI, arXiv, PMID, ISBN, or URL |
| `list_cached` | List recent cached searches |
| `fix_bib` | Fix Title Case, protect acronyms (`{IEEE}`, `{CFE}`), add datasheet notes |
| `download_paper` | Download PDF from free sources (OA → S2 → Unpaywall → arXiv) |

## CLI Usage

```bash
# Install with pip
pip install search-citation-mcp

# Search
search-citation search "photovoltaic" -n 5

# Add citation by DOI
search-citation add --doi 10.1016/j.rser.2015.08.042

# Generate citation without writing
search-citation cite --doi 10.1016/j.rser.2015.08.042

# Find related papers
search-citation related 10.1016/j.rser.2015.08.042 -n 5

# Detect input type
search-citation detect "10.1016/j.rser.2015.08.042"

# Fix and validate .bib files
search-citation fix-bib bibliografia.bib --dry-run

# Download PDF
search-citation download 10.1016/j.rser.2015.08.042 -o ./pdfs

# View cached searches
search-citation cache
```

## Supported BibTeX Entry Types

`article` · `inproceedings` · `book` · `techreport` · `mastersthesis` · `phdthesis` · `manual` · `misc` · `online` · `incollection`

Validated against IEEE schema with required and optional fields per type.

## Development

```bash
git clone https://github.com/isaacwars/search-citation-mcp.git
cd search-citation-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v
```

## Security

- **stdio** transport by default — no TCP port, no network exposure
- Path traversal blocked on all file operations
- Credentials via environment variables only, never hardcoded
- Zero personal data in source code
- PDF and `.bib` output confined to project workspace

## License

Apache 2.0 with Commons Clause — see [LICENSE](LICENSE)
