How andybrandt/mcp-simple-arxiv works
Project type and purpose
• This is a lightweight, single-service “MCP” server written in Python that exposes arXiv’s API to LLM clients (e.g., Claude Desktop). It can run either as a stdio-based local connector or as an HTTP-based web server.
File structure
• Top-level scripts and metadata:
• pyproject.toml, MANIFEST.in, LICENSE, smithery.yaml (packaging & publish)
• Dockerfile, Dockerfile.web (container builds for stdio vs. web)
• DEPLOYMENT.md, TODO.md, README.md
• Main Python package “mcp_simple_arxiv/”:
• __main__.py: entrypoint for stdio mode
• server.py: HTTP server implementation
• arxiv_client.py: logic to call arXiv REST API (with rate-limiting & retries)
• categories.py & update_taxonomy.py + taxonomy.json: category management
• __init__.py
• Tests: test_client.py, test_web_client.py
Additional README insights
• Two modes of operation: stdio for desktop client; HTTP for web clients
• Uses arXiv API guidelines: one request per 3 seconds, single connection
• Packaging via Smithery (CLI install for Claude) and pip
Main components
a. Front-end / Client layer
• Claude Desktop or any LLM client
• HTTP browser or web client (when deployed as web server)
b. Connector / Server layer (this repo)
• Entrypoint module (__main__.py) for stdio mode
• HTTP server module (server.py) exposing REST endpoints
• Core business logic (arxiv_client.py)
• Taxonomy subsystem (categories.py, update_taxonomy.py, taxonomy.json)
c. External service
• arXiv public API (external HTTP service)
d. Supporting artifacts
• Configuration & packaging (pyproject.toml, smithery.yaml)
• Container builds (Dockerfile, Dockerfile.web)
• Tests (test_client, test_web_client)
Relationships and interactions
• Client → Connector
• stdio mode: client spawns “python -m mcp_simple_arxiv” and communicates via stdin/stdout
• web mode: client issues HTTP requests to server.py endpoints
• Connector → arXiv API
• arxiv_client enforces rate limits and error-handling
• Connector ↔ Taxonomy JSON
• categories.py loads taxonomy.json
• update_taxonomy.py updates taxonomy.json on demand
• Connector ↔ Tests
• test_client.py invokes __main__ in stdio mode
• test_web_client.py makes HTTP calls to server routes
Architectural patterns & principles
• Single process, modular design (separation of entrypoints vs. core logic)
• Adapter pattern: arxiv_client abstracts external API
• Configuration-first: packaging manifests, Dockerfiles, smithery.yaml
• Two deployment modes without code duplication
Diagramming recommendations
• Blue for server components
• Green for external services
• Gray for configuration/artifacts
Details to capture
• Rate-limiting logic in arxiv_client
• Packaging/deployment flow (Dockerfile vs. Dockerfile.web, Smithery install)
• Test harness invoking each mode