# andybrandt/mcp-simple-arxiv architecture

> Architecture diagram of the GitHub repository andybrandt/mcp-simple-arxiv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andybrandt/mcp-simple-arxiv
- Repository: https://github.com/andybrandt/mcp-simple-arxiv

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Desktop["LLM Client (Stdio)"]:::external
        Browser["Web Client (HTTP)"]:::external
    end

    %% Connector Service
    subgraph "Connector Service"
        subgraph "Stdio Mode"
            Entrypoint["Entrypoint: __main__.py"]:::server
        end
        subgraph "Web Mode"
            HTTPServer["HTTP Server: server.py"]:::server
        end
        ArxivClient["ArXiv Adapter: arxiv_client.py"]:::server
        Categories["Taxonomy Manager: categories.py"]:::server
        UpdateTaxonomy["Taxonomy Updater: update_taxonomy.py"]:::server
        TaxonomyData["taxonomy.json"]:::data
    end

    %% External API
    ExternalAPI["arXiv API"]:::external

    %% Packaging & Deployment
    subgraph "Packaging & Deployment"
        PyProj["pyproject.toml"]:::config
        Smith["smithery.yaml"]:::config
        Manifest["MANIFEST.in"]:::config
        DockerStd["Dockerfile (stdio)"]:::config
        DockerWeb["Dockerfile.web"]:::config
    end

    %% Tests
    subgraph "Tests"
        TestClient["test_client.py"]:::test
        TestWebClient["test_web_client.py"]:::test
    end

    %% Connections
    Desktop -->|stdin/stdout| Entrypoint
    Browser -->|HTTP requests| HTTPServer
    Entrypoint -->|invokes| ArxivClient
    HTTPServer -->|calls| ArxivClient
    ArxivClient -->|fetches data| ExternalAPI
    ArxivClient -->|loads taxonomy| Categories
    Categories -->|reads| TaxonomyData
    UpdateTaxonomy -.->|updates| TaxonomyData
    TestClient -->|tests| Entrypoint
    TestWebClient -->|tests| HTTPServer
    PyProj -->|configures| Entrypoint
    Smith -->|packages| Entrypoint
    Manifest -->|includes| Entrypoint
    DockerStd -->|builds container| Entrypoint
    DockerWeb -->|builds container| HTTPServer

    %% Click Events
    click Entrypoint "https://github.com/andybrandt/mcp-simple-arxiv/blob/master/mcp_simple_arxiv/__main__.py"
    click HTTPServer "https://github.com/andybrandt/mcp-simple-arxiv/blob/master/mcp_simple_arxiv/server.py"
    click ArxivClient "https://github.com/andybrandt/mcp-simple-arxiv/blob/master/mcp_simple_arxiv/arxiv_client.py"
    click Categories "https://github.com/andybrandt/mcp-simple-arxiv/blob/master/mcp_simple_arxiv/categories.py"
    click UpdateTaxonomy "https://github.com/andybrandt/mcp-simple-arxiv/blob/master/mcp_simple_arxiv/update_taxonomy.py"
    click TaxonomyData "https://github.com/andybrandt/mcp-simple-arxiv/blob/master/mcp_simple_arxiv/taxonomy.json"
    click PyProj "https://github.com/andybrandt/mcp-simple-arxiv/blob/master/pyproject.toml"
    click Smith "https://github.com/andybrandt/mcp-simple-arxiv/blob/master/smithery.yaml"
    click Manifest "https://github.com/andybrandt/mcp-simple-arxiv/blob/master/MANIFEST.in"
    click DockerStd "https://github.com/andybrandt/mcp-simple-arxiv/tree/master/Dockerfile"
    click DockerWeb "https://github.com/andybrandt/mcp-simple-arxiv/blob/master/Dockerfile.web"
    click TestClient "https://github.com/andybrandt/mcp-simple-arxiv/blob/master/test_client.py"
    click TestWebClient "https://github.com/andybrandt/mcp-simple-arxiv/blob/master/test_web_client.py"

    %% Styles
    classDef server fill:#e0f7fa,stroke:#0288d1,color:#000
    classDef external fill:#c8e6c9,stroke:#2e7d32,color:#000
    classDef config fill:#eeeeee,stroke:#9e9e9e,color:#000
    classDef data fill:#fff3e0,stroke:#fb8c00,color:#000
    classDef test fill:#f3e5f5,stroke:#8e24aa,color:#000
```
