# ChinaRxiv MCP Server

FastMCP server for the ChinaRxiv API.

## Tools

- `search_papers`
- `get_paper_detail`
- `get_paper_full_text`
- `get_paper_figures`
- `download_paper_pdf`
- `list_subjects`
- `list_publications`
- `get_api_stats`
- `list_bulk_exports`
- `health_check`

## Agent-friendly behavior

- `list_subjects(q, limit, offset, cache_bust, api_email)` filters and paginates locally. Upstream is cached for 1 hour.
- `list_publications(q, limit, offset, cache_bust, api_email)` lists journal keys accepted by the `publication` search filter. Upstream is cached for 1 hour.
- `download_paper_pdf(paper_id, include_base64, api_email)` returns metadata by default: URL, content type, byte size, SHA-256 checksum, and a future resource URI. It only includes base64 when `include_base64=true`.
- `search_papers(...)` supports the official field, date, availability, source, language, and publication filters. Pagination uses `cursor`.
- Most tools accept optional `api_email` to override `CHINARXIV_EMAIL` for the upstream `X-API-Email` header.
- API rate-limit headers are returned as `rate_limit` metadata when provided upstream.
- Cache TTLs: subjects/publications 1h, stats 10min, bulk exports 6h, paper detail/text/figures/pdf 24h.

## Tests

```powershell
uv run pytest
```

## Configuration

Create your local environment file from the provided example:

```powershell
Copy-Item .env.example .env
```

Then edit `.env` with the values for your environment. The server loads this
file automatically on startup. Variables already defined in the process
environment take precedence over `.env`.

## Local stdio

```powershell
uv run python server.py
```

## Docker

```powershell
docker build -t mcp-chinarxiv .
docker run --rm -i --env-file .env mcp-chinarxiv
```

## Hermes

If Hermes supports MCP over HTTP, run the container as a local service:

```powershell
docker run -d --name mcp-chinarxiv -p 8765:8765 --env-file .env mcp-chinarxiv uv run fastmcp run server.py:mcp --transport http --host 0.0.0.0 --port 8765
```

Then add this server URL in Hermes:

```json
{
  "mcpServers": {
    "chinarxiv": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}
```

If Hermes expects stdio MCP servers, let Hermes launch Docker directly:

```json
{
  "mcpServers": {
    "chinarxiv": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file",
        ".env",
        "mcp-chinarxiv"
      ]
    }
  }
}
```

## Environment

- `CHINARXIV_BASE_URL`: defaults to `https://chinarxiv.org`
- `CHINARXIV_EMAIL`: email sent in the upstream `X-API-Email` header
- `CHINARXIV_TIMEOUT`: defaults to `30`
- `CHINARXIV_USER_AGENT`: defaults to `mcp-chinarxiv/0.1`