AGENT_INSTRUCTIONS.md•2.37 kB
# arXiv CLI - Agent Quick Reference
## Commands
Always run with `uv`. E.g., `uv run arxiv search ...`.
Commands:
download Download PDF for a paper by arXiv ID.
get Get a specific arXiv paper by ID.
list-downloads List all downloaded PDFs.
search Search arXiv papers.
### Search
```bash
arxiv search "<query>" [--max-results N] [--json]
```
### Get Paper
```bash
arxiv get <arxiv_id> [--no-download] [--force] [--json]
```
### Download PDF
```bash
arxiv download <arxiv_id> [--force]
```
### List Downloads
```bash
arxiv list-downloads
```
## Query Syntax
**Field Prefixes:**
- `ti:` - Title
- `au:` - Author
- `abs:` - Abstract
- `cat:` - Category (cs.AI, cs.LG, etc.)
- `all:` - All fields (default)
**Boolean Operators:** `AND`, `OR`, `ANDNOT`
**Examples:**
```bash
arxiv search "ti:transformer"
arxiv search "au:Hinton AND cat:cs.AI"
arxiv search "abs:neural networks OR abs:deep learning"
```
## MCP Server
The arXiv CLI includes a Model Context Protocol (MCP) server for LLM assistants.
### Running the MCP Server
```bash
# Option 1: Using the script entry point
uv run arxiv-mcp
# Option 2: Using the module
uv run python -m arxiv.mcp
```
### MCP Tools (4 tools)
- `search_papers` - Search arXiv with advanced query syntax
- `get_paper` - Get detailed paper information and optionally download PDF
- `download_paper` - Download PDF for a specific paper
- `list_downloaded_papers` - List all locally downloaded PDFs
### MCP Resources (2 resources)
- `paper://{arxiv_id}` - Get formatted paper metadata
- `downloads://list` - Get markdown list of downloaded papers
### MCP Prompts (2 prompts)
- `search_arxiv_prompt` - Guide for searching arXiv
- `download_paper_prompt` - Guide for downloading papers
### Example MCP Configuration (Claude Desktop)
```json
{
"mcpServers": {
"arxiv": {
"command": "uv",
"args": ["run", "arxiv-mcp"],
"cwd": "/path/to/arxiv_cli"
}
}
}
```
Or with the full path to avoid needing the `cwd`:
```json
{
"mcpServers": {
"arxiv": {
"command": "uv",
"args": ["--directory", "/path/to/arxiv_cli", "run", "arxiv-mcp"]
}
}
}
```
## Notes
- PDFs saved to `./.arxiv` by default
- Rate limited to 3s between requests
- Use `--json` for machine-readable output
- All IDs accept formats: `1706.03762`, `arXiv:1706.03762`, `1706.03762v1`