# blazickjp/arxiv-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/blazickjp/arxiv-mcp-server
- Repository: https://github.com/blazickjp/arxiv-mcp-server

## Overview

##### Main Components

a) External Systems:
- ArXiv API (external service)
- AI Assistants (clients)
- Local File System (for paper storage)

b) Core Server Components:
- MCP Server Interface
- Tool Handlers
- Paper Management System
- Storage Management

##### Component Organization

**Client Layer**
- ↓
**Interface Layer**
- ↓
**Service Layer**
- ↓
**Storage Layer**
- ↓
**External Service Layer**

##### Specific Component Details

a) Interface Layer:
- MCP Server component (server.py)
- Four main tools as sub-components:
- Search Tool (search.py)
- Download Tool (download.py)
- Papers Tool (list_papers.py)
- Read Paper Tool (read_paper.py)

b) Service Layer:
- Paper Resource Manager (papers.py)
- Configuration Management (config.py)

c) Storage Layer:
- Local Paper Storage System
- Storage Path Management

##### Important Elements to Highlight

- MCP Protocol interface
- Paper storage path configuration
- Tool interaction flows
- External API communication patterns
- Local storage management

Create clear boundaries between:
- External interfaces
- Core server logic
- Storage management
- Tool implementations

##### Additional Details

Annotations for:
- Configuration options
- Storage paths
- Supported paper formats
- API endpoints

- The modular nature of the tool system
- Clear separation between interface and implementation
- Storage management strategy
- External service integration

Remember to:
- Keep the main flow clear and easy to follow
- Version information and key dependencies
- Significant configuration requirements

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and classes
    classDef external fill:#D3D3D3,stroke:#333
    classDef core fill:#B3D9FF,stroke:#333
    classDef storage fill:#90EE90,stroke:#333
    classDef tool fill:#FFB366,stroke:#333
    classDef config fill:#DDA0DD,stroke:#333

    %% Client Layer
    subgraph ClientLayer
        AI[AI Assistants]:::external
    end

    %% Interface Layer
    subgraph InterfaceLayer
        MCP[MCP Server Interface]:::core
        click MCP "https://github.com/blazickjp/arxiv-mcp-server/blob/main/src/arxiv_mcp_server/server.py"
        
        subgraph ToolHandlers
            direction TB
            Tools[Tool Handlers]:::tool
            click Tools "https://github.com/blazickjp/arxiv-mcp-server/tree/main/src/arxiv_mcp_server/tools/"
            SearchT[Search Tool]:::tool
            click SearchT "https://github.com/blazickjp/arxiv-mcp-server/blob/main/src/arxiv_mcp_server/tools/search.py"
            DownloadT[Download Tool]:::tool
            click DownloadT "https://github.com/blazickjp/arxiv-mcp-server/blob/main/src/arxiv_mcp_server/tools/download.py"
            ListT[List Papers Tool]:::tool
            click ListT "https://github.com/blazickjp/arxiv-mcp-server/blob/main/src/arxiv_mcp_server/tools/list_papers.py"
            ReadT[Read Paper Tool]:::tool
            click ReadT "https://github.com/blazickjp/arxiv-mcp-server/blob/main/src/arxiv_mcp_server/tools/read_paper.py"
        end
    end

    %% Service Layer
    subgraph ServiceLayer
        PaperMgr[Paper Resource Manager]:::core
        click PaperMgr "https://github.com/blazickjp/arxiv-mcp-server/blob/main/src/arxiv_mcp_server/resources/papers.py"
        Config[Configuration Management]:::config
        click Config "https://github.com/blazickjp/arxiv-mcp-server/blob/main/src/arxiv_mcp_server/config.py"
        Resources[Resource Management]:::core
        click Resources "https://github.com/blazickjp/arxiv-mcp-server/tree/main/src/arxiv_mcp_server/resources/"
    end

    %% Storage Layer
    subgraph StorageLayer
        Storage[Local Paper Storage]:::storage
        StorageMgr[Storage Path Management]:::storage
    end

    %% External Service Layer
    subgraph ExternalLayer
        ArXiv[ArXiv API]:::external
    end

    %% Relationships
    AI --> MCP
    MCP --> Tools
    Tools --> SearchT & DownloadT & ListT & ReadT
    SearchT & DownloadT & ListT & ReadT --> PaperMgr
    PaperMgr --> Resources
    PaperMgr --> Config
    PaperMgr --> StorageMgr
    StorageMgr --> Storage
    PaperMgr -.-> ArXiv
    
    %% Legend
    subgraph Legend
        direction TB
        L1[External Systems]:::external
        L2[Core Components]:::core
        L3[Storage Components]:::storage
        L4[Tool Components]:::tool
        L5[Configuration]:::config
    end
```
