# adhikasp/mcp-reddit architecture

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

- Interactive diagram: https://gitdiagram.com/adhikasp/mcp-reddit
- Repository: https://github.com/adhikasp/mcp-reddit

## Overview

##### Project type and purpose
- This is a **backend microservice** implementing the Model Context Protocol (MCP).
- It exposes a small set of tool calls (e.g. `fetch_hot_threads`) over HTTP (likely via Uvicorn/Gunicorn) and interacts with the Reddit public API.

##### File structure
- Top level:
- `.env`, `Dockerfile`, `smithery.yaml`, `pyproject.toml` → configuration & deployment
- `src/mcp_reddit/reddit_fetcher.py` → core logic for all Reddit API calls
- No “frontend” or database directories → purely a stateless service.
- The lock files (`uv.lock`) and Python version files indicate use of a virtual environment and dependency management.

##### README for additional insights
- The “Usage” section shows a CLI client (`mcp-client-cli`) invoking the service.
- The service supports commands like `fetch_hot_threads` and returns structured data to the client.
- No persistence layer—each request directly calls Reddit’s public REST API.

##### Main components & interactions
a. **Client Layer**
- mcp-client-cli (or any other MCP-aware LLM client)
b. **MCP Reddit Server**
- HTTP Server (e.g. Uvicorn)
- MCP Protocol Handler
- RedditFetcher module (`reddit_fetcher.py`)
c. **External Service**
- Reddit Public API
d. **Configuration & Deployment**
- `.env` for secrets (e.g. Reddit API keys)
- `smithery.yaml` for Smithery integration
- `Dockerfile` for containerization

##### Relationships & data flow
1. Client sends MCP‐formatted JSON request (e.g. `fetch_hot_threads`) to the server’s HTTP endpoint.
2. HTTP Server receives request and routes it to the MCP Protocol Handler.
3. MCP Handler invokes the `RedditFetcher` with appropriate parameters.
4. `RedditFetcher` calls the Reddit REST API over HTTPS.
5. Reddit responds with JSON containing threads or comments.
6. Server translates API response into an MCP response and returns it to the client.

##### Architectural patterns & design principles
- **Microservice / Single-Responsibility**: Only Reddit fetching.
- **Stateless**: No local database or caching (unless you add one later).
- **12-Factor App**: Configuration in environment variables, containerized deployment.
- **Protocol Abstraction**: MCP handler decouples JSON-RPC style interface from business logic.

## Diagram (Mermaid)

```mermaid
flowchart TB
    Title["MCP Reddit Server Architecture"]
    
    subgraph "Client Layer"
        Client["mcp-client-cli"]:::client
    end

    subgraph "Service Layer"
        HTTPServer["HTTP Server\n(uvicorn main:app)"]:::internal
        MCPHandler["MCP Protocol Handler"]:::internal
        RedditFetcher["RedditFetcher\n(src/mcp_reddit/reddit_fetcher.py)"]:::internal
    end

    subgraph "External Service"
        ExternalAPI["Reddit Public API"]:::external
    end

    subgraph "Configuration & Deployment"
        ENV[".env"]:::config
        Docker["Dockerfile"]:::config
        Smithery["smithery.yaml"]:::config
        Pyproject["pyproject.toml"]:::config
        Lock["uv.lock"]:::config
    end

    Title --> Client
    Client -->|"POST /mcp\nfetch_hot_threads request"| HTTPServer
    HTTPServer -->|"route to MCP Handler"| MCPHandler
    MCPHandler -->|"calls fetch_hot_threads()"| RedditFetcher
    RedditFetcher -->|"REST API call over HTTPS"| ExternalAPI
    ExternalAPI -->|"JSON response"| RedditFetcher
    RedditFetcher -->|"MCP response data"| MCPHandler
    MCPHandler -->|"HTTP response"| HTTPServer
    HTTPServer -->|"returns MCP JSON"| Client

    ENV --> Docker
    ENV --> Smithery
    ENV --> Pyproject
    ENV --> Lock
    Docker --> HTTPServer
    Smithery --> HTTPServer
    Pyproject --> HTTPServer
    Lock --> HTTPServer

    click RedditFetcher "https://github.com/adhikasp/mcp-reddit/blob/master/src/mcp_reddit/reddit_fetcher.py"
    click Docker "https://github.com/adhikasp/mcp-reddit/tree/master/Dockerfile"
    click ENV "https://github.com/adhikasp/mcp-reddit/blob/master/.env"
    click Smithery "https://github.com/adhikasp/mcp-reddit/blob/master/smithery.yaml"
    click Pyproject "https://github.com/adhikasp/mcp-reddit/blob/master/pyproject.toml"
    click Lock "https://github.com/adhikasp/mcp-reddit/blob/master/uv.lock"

    classDef client fill:#ADD8E6,stroke:#000
    classDef internal fill:#90EE90,stroke:#000
    classDef external fill:#FFA500,stroke:#000
    classDef config fill:#D3D3D3,stroke:#000
    classDef title fill:none,stroke:none,font-size:18px,font-weight:bold
```
