# beatnyk77/alphavantage architecture

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

- Interactive diagram: https://gitdiagram.com/beatnyk77/alphavantage
- Repository: https://github.com/beatnyk77/alphavantage

## Overview

##### Project type and purpose
- This is a Python-based microservice (“MCP server”) whose sole job is to fetch stock-market data from the external Alpha Vantage REST API and expose it in the “MCP” protocol for use by clients such as Claude Desktop.
- There is no GUI or database of its own—just a small HTTP/command‐line server that proxies requests out to Alpha Vantage.

##### File structure
- Top level:
- Dockerfile, smithery.yaml – deployment/orchestration configs
- pyproject.toml, pytest.ini – build/test configurations
- src/alphavantage_mcp_server/ – Python package
- Inside the package:
- server.py – entry point / CLI wrapper that spins up the MCP server (likely using “uv” command)
- api.py – implements the routes or handlers that call out to the Alpha Vantage REST endpoints
- tests/test_api.py – unit tests for the API layer

##### Key README insights
- The server uses an environment variable `ALPHAVANTAGE_API_KEY` to authenticate to the Alpha Vantage API.
- It runs via the `uv` command (UVicorn wrapper) and is glued into Claude Desktop by adding a section to `claude_desktop_config.json`.

##### Main components & their interactions
a. Components:
1. Client (e.g., Claude Desktop)
2. MCP Server process
– Entrypoint/CLI (`server.py`)
– API handlers (`api.py`)
3. External service: Alpha Vantage REST API
4. Supporting config/deployment artifacts (Docker, smithery)
b. Data flows & relationships:
– Client issues an MCP request → MCP server entrypoint listens on a socket/port → routes to the handler in `api.py` → handler reads `ALPHAVANTAGE_API_KEY` → issues HTTP request to Alpha Vantage → response flows back through handler → MCP server sends response back to client.
c. Architectural patterns & principles:
– Single‐responsibility microservice—“one API, one job.”
– 12-factor style config via environment variables.
– Clear separation: CLI/transport layer vs. business logic layer.
d. Technologies & frameworks:
– Python (pyproject.toml for packaging)
– UVicorn (invoked via `uv` CLI)
– HTTP client (requests or httpx inside `api.py`)
– Pytest for testing
– Docker & smithery for containerization/hosting

##### Final advice
- Docker/smithery as a deployment wrapper around the MCP Server.
- This level of detail will give your colleagues a clear, accurate view of how this tiny, focused microservice is wired up end-to-end.

## Diagram (Mermaid)

```mermaid
flowchart TB
    Client["Client (Claude Desktop)"]:::external

    subgraph "MCP Server"
        direction TB
        CLI["CLI Layer"]:::internal
        API["API Layer"]:::internal
    end

    AlphaVantage["Alpha Vantage REST API"]:::external

    subgraph "Supporting Artifacts"
        direction TB
        Docker["Dockerfile"]:::config
        Smithery["smithery.yaml"]:::config
        Build["pyproject.toml"]:::config
        PytestCfg["pytest.ini"]:::config
        Init["__init__.py"]:::internal
    end

    Tests["tests/test_api.py"]:::test

    Client -->|"MCP Request"| CLI
    CLI -->|"route to handler"| API
    API -->|"HTTP GET\n?apikey=$ALPHAVANTAGE_API_KEY"| AlphaVantage
    AlphaVantage -->|"HTTP Response"| API
    API -->|"MCP Response"| CLI
    CLI -->|"MCP Response"| Client

    classDef internal fill:#b3cde3,stroke:#000,stroke-width:1px
    classDef external fill:#ccebc5,stroke:#000,stroke-width:1px
    classDef config   fill:#fddbc7,stroke:#000,stroke-width:1px
    classDef test     fill:#fed9a6,stroke:#000,stroke-width:1px

    click CLI "https://github.com/beatnyk77/alphavantage/blob/main/src/alphavantage_mcp_server/server.py"
    click API "https://github.com/beatnyk77/alphavantage/blob/main/src/alphavantage_mcp_server/api.py"
    click Tests "https://github.com/beatnyk77/alphavantage/blob/main/tests/test_api.py"
    click Docker "https://github.com/beatnyk77/alphavantage/tree/main/Dockerfile"
    click Smithery "https://github.com/beatnyk77/alphavantage/blob/main/smithery.yaml"
    click Build "https://github.com/beatnyk77/alphavantage/blob/main/pyproject.toml"
    click PytestCfg "https://github.com/beatnyk77/alphavantage/blob/main/pytest.ini"
    click Init "https://github.com/beatnyk77/alphavantage/blob/main/src/alphavantage_mcp_server/__init__.py"
```
