arxiv-mcp-server

Implements MCP-compliant tool registration that exposes arXiv search functionality with filters for date ranges, categories, and keywords. The search_papers tool routes user queries through the arXiv API client, applies server-side filtering logic, and returns structured metadata (title, authors, abstract, publication date, arXiv ID) formatted as MCP tool outputs. Uses async/await patterns for non-blocking API calls and integrates with the MCP server's tool registry for seamless AI assistant invocation.

Implements a download_paper tool that retrieves PDF files from arXiv, converts them to markdown format using PDF parsing libraries (likely pdfplumber or similar), and stores the converted content in a local cache directory. The tool extracts text, preserves section structure, and handles multi-page documents. Subsequent reads of the same paper are served from the local cache, reducing API calls and improving response latency. Conversion happens server-side, so the AI assistant receives pre-processed markdown rather than raw PDFs.

Implements a testing framework (likely pytest-based) with unit tests for individual tool handlers, integration tests for the full MCP server, and test fixtures for mocking arXiv API responses. Tests cover happy paths (successful paper searches, downloads, reads), error cases (API failures, missing papers), and edge cases (large papers, special characters in titles). Test coverage includes tool registration, prompt invocation, and protocol compliance. Tests use fixtures to mock external dependencies (arXiv API, file I/O) for fast, deterministic execution.

Implements a list_papers tool that scans the local cache directory, extracts metadata from stored papers (title, authors, arXiv ID, download date), and returns a structured inventory. The tool maintains an in-memory or file-based index of downloaded papers, enabling quick lookups without re-scanning the filesystem. Metadata is extracted from paper headers or stored alongside the markdown files. This allows AI assistants to query what papers are available locally before attempting downloads.

Implements a read_paper tool that retrieves previously downloaded papers from the local cache and returns their markdown content. The tool validates that the paper exists in cache, handles missing or corrupted files gracefully, and may support partial reads (e.g., abstract only, first N pages) to manage context window constraints. Content is returned as plain text or structured sections (abstract, introduction, methodology, results, conclusion) to enable targeted analysis by the AI assistant.

Implements a prompt system (specifically the 'deep-paper-analysis' prompt) that provides AI assistants with a structured workflow for analyzing academic papers. The prompt defines a multi-step analysis process: extract key contributions, identify methodology, evaluate results, assess limitations, and synthesize findings. The prompt system is registered with the MCP server and can be invoked by clients to guide the assistant through systematic paper analysis. Prompts may include context injection (e.g., paper content, metadata) and chain-of-thought guidance to improve analysis quality.

Implements the core MCP server that handles protocol compliance, tool registration, prompt registration, and request routing. The server uses the MCP SDK (likely mcp library) to expose tools (search_papers, download_paper, list_papers, read_paper) and prompts (deep-paper-analysis) as MCP resources. The server listens on stdio or network transport, parses incoming MCP requests, invokes the appropriate tool/prompt handler, and returns responses in MCP format. Implements async/await patterns for non-blocking operations and error handling for graceful failure modes.

Implements async/await patterns throughout the server for non-blocking I/O operations (arXiv API calls, PDF downloads, file I/O, markdown conversion). Uses Python's asyncio library to handle multiple concurrent requests without blocking the event loop. Tool handlers are defined as async functions that yield control while waiting for I/O, enabling the server to process other requests in the meantime. This architecture allows a single server instance to handle multiple concurrent AI assistant requests without thread management overhead.

Implements server configuration through environment variables and a settings module that defines cache directory, arXiv API endpoints, PDF conversion parameters, and logging levels. Configuration is loaded at server startup and applied globally to all tool handlers. Supports overrides via environment variables, enabling deployment-specific customization without code changes. Settings may include cache size limits, API rate limiting parameters, and timeout values for long-running operations.

Implements error handling throughout the server that catches exceptions from arXiv API calls, PDF parsing, file I/O, and other operations, then returns MCP-compliant error responses to the client. Errors are categorized (network errors, parsing errors, not found errors) and returned with descriptive messages and error codes. The server continues running after errors, allowing subsequent requests to succeed. Implements timeout handling for long-running operations and graceful degradation when optional features (e.g., markdown conversion) fail.

Implements resource management for the local paper cache, including file creation, deletion, and optional persistence of metadata. The server manages the lifecycle of downloaded papers: creates cache entries when papers are downloaded, maintains metadata indices, and optionally implements cleanup policies (e.g., least-recently-used eviction, age-based deletion). Resources are stored in a configurable cache directory and may be persisted across server restarts via metadata files or a simple database.