# ARES MCP

Local [Model Context Protocol](https://modelcontextprotocol.io) server for
**academic literature search and writing**. It talks to open catalogs
(OpenAlex, arXiv, Crossref), downloads **open-access** PDFs (PDF files only),
extracts IMRaD sections on demand, and appends BibTeX — designed to run next
to [Cursor](https://cursor.com) or any MCP host.

License: [MIT](LICENSE). Free to use locally. Contributions:
[CONTRIBUTING.md](CONTRIBUTING.md).

> ARES does **not** bypass publisher paywalls. If no OA PDF exists, tools
> return `no_open_pdf` instead of scraping HTML.

This project is a **literature helper**, not a PRISMA screening/audit
workbench. It is also **not** the Czech business-registry MCP
([`ares-mcp-server`](https://pypi.org/project/ares-mcp-server/)).

## Install (PyPI)

Python 3.11+. [uv](https://docs.astral.sh/uv/) is recommended.

Cursor / MCP host (`uvx` downloads the published wheel, no clone):

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

Optional identity for the OpenAlex / Unpaywall polite pool (still no `.env`):

```json
{
  "mcpServers": {
    "ares": {
      "command": "uvx",
      "args": ["ares-mcp", "--mailto", "you@university.edu"]
    }
  }
}
```

Or install into an environment:

```bash
pip install ares-mcp
# or: uv tool install ares-mcp
ares-mcp --mailto you@university.edu
```

A `.env` file is **not required**. Contact email is resolved in this order:

1. `ares-mcp --mailto you@university.edu`
2. `ARES_MAILTO` in the process environment (Cursor `mcp.json` `env` block)
3. Optional cwd `.env` (`ARES_MAILTO=...`) — local checkouts only
4. `git config user.email`
5. Placeholder `ares-mcp@localhost` (server still starts)

After publish, confirm the package at
[pypi.org/project/ares-mcp](https://pypi.org/project/ares-mcp/).

## Tools

| Tool | Purpose |
| --- | --- |
| `search_papers` | Query OpenAlex + arXiv; `sort=cited_by` or `relevance`; optional DOI/arXiv lookup |
| `download_and_parse_paper` | DOI or arXiv id → PDF only in `papers/` |
| `get_bibtex` | Crossref BibTeX → append `references.bib` (no duplicates) |
| `extract_sections` | Heuristic IMRaD headings from a **local** PDF |
| `list_local_papers` | Inventory PDFs under `papers/` (or another dir) |
| `screen_papers_for_rqs` | Heuristic include/maybe/exclude of local PDFs vs research questions + snippets |
| `query_local_papers` | Ranked excerpts from the local corpus for a free-form question |

Typical agent flow: search (`sort=cited_by` for famous papers) → download an OA
hit → extract Abstract/Methods → `get_bibtex`. For RQ screening over downloads:
`list_local_papers` → `screen_papers_for_rqs` (host agent narrates justifications
from the evidence pack; ARES does not call an external LLM).

## Install (development)

```bash
git clone https://github.com/benetche/ares-mcp.git
cd ares-mcp
uv sync
```

Run tests:

```bash
uv run pytest
uv run ruff check src tests
```

Live API checks (optional):

```bash
uv run pytest -m integration
```

## Configure Cursor (local checkout)

Copy [`.cursor/mcp.json`](.cursor/mcp.json) and replace the `--project` path
with your clone. Email is optional; git `user.email` is used when unset.

**Recommended — `uv run`:**

```json
{
  "mcpServers": {
    "ares": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/absolute/path/to/ares-mcp",
        "ares-mcp"
      ]
    }
  }
}
```

**venv Python:**

```json
{
  "mcpServers": {
    "ares": {
      "command": "/absolute/path/to/ares-mcp/.venv/bin/python",
      "args": ["-m", "ares_mcp"]
    }
  }
}
```

On Windows, use `.venv/Scripts/python.exe` instead of `.venv/bin/python`.

**`uvx` from a local checkout** (no PyPI install required):

```json
{
  "mcpServers": {
    "ares": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/ares-mcp", "ares-mcp"]
    }
  }
}
```

Reload MCP servers in Cursor, then ask: “Search open-access papers on graph neural networks since 2022.”

Inspector (outside Cursor):

```bash
uv run fastmcp dev src/ares_mcp/server.py
```

## Environment

| Variable / flag | Default | Meaning |
| --- | --- | --- |
| `--mailto` / `ARES_MAILTO` | git `user.email`, else `ares-mcp@localhost` | Contact in User-Agent / OpenAlex `mailto` / Unpaywall `email` |
| `ARES_METADATA_TIMEOUT_S` | `20` | Metadata HTTP timeout |
| `ARES_PDF_TIMEOUT_S` | `60` | PDF download timeout |
| `ARES_MAX_PDF_BYTES` | `52428800` | Max PDF size (~50 MiB) |

Writes are jailed to the server **current working directory** (the project
Cursor opened). Path traversal is rejected. PDF candidate URLs that point at
loopback or private IPs are rejected.

## API notes

- **OpenAlex:** `GET /works` with `search` + `filter`. Abstracts are stored as
  inverted indexes and reconstructed locally. Download uses **all** `locations`
  with a `pdf_url`, plus arXiv/PMC ids when present.
- **Unpaywall:** `GET /v2/{doi}` for legal OA copies (preprints, accepted
  manuscripts, repositories). This is how many IEEE/Elsevier papers become
  downloadable without touching the paywall HTML.
- **arXiv:** Atom API at `export.arxiv.org`. All hits are OA.
- **Crossref:** DOI content negotiation `Accept: application/x-bibtex`.
- Identify your process with `--mailto` or `ARES_MAILTO` when you can. Do not
  hammer the APIs; each tool call is a handful of requests with one retry on
  429/5xx.

If every OA candidate 403s or returns HTML, the tool reports `download_failed`
or `no_open_pdf`. Pass an **arXiv id** when you know a preprint exists. ARES
will not scrape publisher HTML.

## License alternative

MIT is the project license. Apache-2.0 may be considered later if a patent
grant is required; discuss that in an issue before relicensing.

## Status

`0.2.0`. Releases are built in CI and uploaded to PyPI with
[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC, no
long-lived API tokens). After a GitHub Release tag `v0.2.0` (and matching
publisher config on PyPI), Cursor can run `uvx ares-mcp` with no `.env`.