# deepsuthar496/alpha-ventage-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/deepsuthar496/alpha-ventage-mcp
- Repository: https://github.com/deepsuthar496/alpha-ventage-mcp

## Overview

##### Project Type & Purpose
- This is a backend‐only MCP (Model Context Protocol) server, implemented in TypeScript/Node.js.
- Its sole purpose is to act as a protocol adapter: it receives MCP tool‐invocation commands, fetches financial data from the external Alpha Vantage REST API, and returns the results back to the MCP host.

##### Key Components
a. MCP Host Interface
- STDIN/STDOUT (or CLI args) as the communication channel.
b. Alpha Vantage MCP Server (Node.js Process)
- Subcomponents:
- CLI/Command‐Line Handler (index.js entry point)
- Tool Router/Dispatcher (maps tool names like get_stock_price, get_forex_rate, etc., to handler functions)
- HTTP Client Module (e.g., fetch or Axios wrapper)
- Response Formatter (packages JSON for MCP)
- Configuration subcomponent: reads ALPHA_VANTAGE_API_KEY and other env vars.
c. Alpha Vantage External API
- Public REST endpoints for Stocks, Crypto, Forex, Technical Indicators.
- HTTP(S) calls leaving the Node.js process.

##### Relationships & Data Flow
- The MCP Host sends a “tool invocation” command (with JSON args) to the Node process.
- The CLI Handler parses the command, the Router selects the right Tool Handler.
- That Handler calls the HTTP Client with the appropriate Alpha Vantage endpoint + API key.
- Alpha Vantage responds with raw JSON.
- The Response Formatter normalizes that JSON into the MCP reply schema.
- The formatted JSON is written back to STDOUT for the MCP Host.

##### Architectural Patterns & Design Principles
- Single‐process microservice: one Node.js process offering multiple tool‐handlers.
- Separation of concerns: CLI parsing, routing, HTTP access, and formatting each live in distinct modules.
- Environment‐driven configuration: API key passed via env var to avoid hardcoding.
- Build pipeline: TypeScript → JavaScript (src/index.ts → build/index.js via `npm run build`).

## Diagram (Mermaid)

```mermaid
flowchart TD
    MCP["MCP Host Interface"]:::external
    subgraph "Alpha Vantage MCP Server"
        CLICmd["CLI/Command-Line Handler"]:::internal
        Router["Tool Router/Dispatcher"]:::internal
        ToolHandler["Tool Handlers\n(get_stock_price, get_forex_rate, etc.)"]:::internal
        HTTPClient["HTTP Client Module"]:::internal
        Formatter["Response Formatter"]:::internal
        Config["Configuration Reader\n(env ALPHA_VANTAGE_API_KEY)"]:::config
    end
    API["Alpha Vantage REST API"]:::external
    Build["Build Pipeline\n(TypeScript → JavaScript)"]:::config

    MCP -->|"JSON command\n(Stdout/Stdin)"|CLICmd
    CLICmd -->|"parsed args"|Router
    Router -->|"selected handler"|ToolHandler
    ToolHandler -->|"HTTP request"|HTTPClient
    HTTPClient -->|"HTTPS call"|API
    API -->|"HTTP response"|HTTPClient
    HTTPClient -->|"raw JSON"|ToolHandler
    ToolHandler -->|"raw data"|Formatter
    Formatter -->|"MCP reply"|CLICmd
    CLICmd -->|"JSON response\n(Stdout)"|MCP

    Config --> CLICmd
    Build -.-> CLICmd

    click MCP "https://github.com/deepsuthar496/alpha-ventage-mcp/blob/main/README.md"
    click CLICmd "https://github.com/deepsuthar496/alpha-ventage-mcp/blob/main/src/index.ts"
    click Router "https://github.com/deepsuthar496/alpha-ventage-mcp/blob/main/src/index.ts"
    click ToolHandler "https://github.com/deepsuthar496/alpha-ventage-mcp/blob/main/src/index.ts"
    click HTTPClient "https://github.com/deepsuthar496/alpha-ventage-mcp/blob/main/src/index.ts"
    click Formatter "https://github.com/deepsuthar496/alpha-ventage-mcp/blob/main/src/index.ts"
    click Config "https://github.com/deepsuthar496/alpha-ventage-mcp/blob/main/src/index.ts"
    click Config "https://github.com/deepsuthar496/alpha-ventage-mcp/blob/main/package.json"
    click Build "https://github.com/deepsuthar496/alpha-ventage-mcp/blob/main/package.json"
    click Build "https://github.com/deepsuthar496/alpha-ventage-mcp/blob/main/tsconfig.json"

    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px
    classDef config fill:#FFA500,stroke:#000,stroke-width:1px
```
