# vernardciti/mcp_server_in_python architecture

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

- Interactive diagram: https://gitdiagram.com/vernardciti/mcp_server_in_python
- Repository: https://github.com/vernardciti/mcp_server_in_python

## Overview

##### Project type and purpose
- This is a backend service project (“MCP in 10 Minutes”) that demonstrates how to build a minimal “MCP Server” for streaming/inspecting market-ticker data (e.g., Yahoo Finance).
- There are two primary Python processes:
- `server.py`: the MCP server (the core inspector service)
- `agent.py`: the agent/client that fetches or processes data and communicates with the MCP server
- A local on-disk database (`ticker_db/`) stores binary blobs and metadata for ticker data.
- An optional UI component (Langflow) and an LLM runtime (Ollama) can hook into this pipeline for visualization and decision logic.

##### File structure
- Top-level scripts:
- `server.py` – bootstraps the MCP server in “dev” mode
- `agent.py` – runs the agent process that pushes data into the MCP server
- Configuration:
- `pyproject.toml` / `.python-version` for Python tooling and dependencies
- `uv.lock` for pinned dependencies via “uv” commands
- Persistent storage:
- `ticker_db/` contains subfolders keyed by UUID, each storing `.bin` and `.pickle` files for data, headers, indexes, etc.
- README outlines the startup steps and external requirements (Langflow, Ollama).

##### README for additional insights
- Notes that you need Ollama running as the LLM backend.
- Describes using `uv run mcp dev server.py` and `uv run agent.py`.
- Mentions Langflow installation and execution for a GUI front end.

a. Main components
1. MCP Server (server.py) – the central service that ingests, stores, and exposes ticker data streams
2. Agent (agent.py) – producer that fetches data (e.g., via Yahoo Finance API) and pushes it to the MCP server
3. Database (ticker_db/) – on-disk storage for raw data chunks, headers, indexes
4. External Data Source – the upstream market data provider (Yahoo Finance, etc.)
5. LLM Engine (Ollama) – optional model runtime for enriched analytics or natural-language interfaces
6. UI / Workflow Editor (Langflow) – optional frontend for visual pipeline construction and real-time inspection
b. Relationships & data flows
- Agent → MCP Server: streams new tick data via MCP protocol (e.g., WebSocket or gRPC)
- MCP Server ↔ Database: writes incoming blobs, reads history for client queries
- MCP Server → Langflow UI: serves APIs or WebSocket endpoints for live dashboards
- Langflow UI → Ollama: sends prompts/workflow requests to the LLM engine
- Ollama → MCP Server or Agent: (if used) returns analysis or instructions back through the pipeline
- Agent → External Data Source: polls or subscribes to market data
c. Architectural patterns & design principles
- Separation of concerns: data ingestion (agent), data serving (server), storage (DB), and UI/LLM layers are decoupled
- Streaming/messaging pattern between agent and server (MCP protocol)
d. Key technologies & frameworks
- Python 3.x with `pyproject.toml` (probably using Hatch or Poetry)
- “uv” CLI (a thin wrapper for virtualenv, installs, task runner)
- MCP protocol (custom or third-party library for messaging)
- SQLite (for small-scale storage) + custom binary blobs
- Langflow (Visual workflow editor)
- Ollama (Local LLM runtime)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Data Source
    DataSource["External Data Source\n(Yahoo Finance)"]:::external

    %% Core Services
    Agent["Agent\n(agent.py)"]:::service
    Server["MCP Server\n(server.py)"]:::service

    %% Storage
    DB["On-disk Database\n(ticker_db/)"]:::db

    %% Optional Extensions
    Langflow["Langflow UI"]:::ui
    Ollama["Ollama LLM Engine"]:::external

    %% Project Config
    subgraph "Project Configuration"
        Config1["pyproject.toml"]:::config
        Config2["uv.lock"]:::config
        README["README.md"]:::config
    end

    %% Data Flows
    DataSource -->|"poll API"| Agent
    Agent -->|"MCP Stream"| Server
    Server -->|"SQL I/O"| DB
    Server -->|"REST/gRPC"| Langflow
    Langflow -->|"Langflow API"| Ollama
    Ollama -->|"analysis/commands"| Server

    %% Bidirectional
    Server <-->|"read/write"| DB

    %% Click Events
    click Server "https://github.com/vernardciti/mcp_server_in_python/blob/main/server.py"
    click Agent "https://github.com/vernardciti/mcp_server_in_python/blob/main/agent.py"
    click DB "https://github.com/vernardciti/mcp_server_in_python/tree/main/ticker_db/"
    click Config1 "https://github.com/vernardciti/mcp_server_in_python/blob/main/pyproject.toml"
    click Config2 "https://github.com/vernardciti/mcp_server_in_python/blob/main/uv.lock"
    click README "https://github.com/vernardciti/mcp_server_in_python/blob/main/README.md"

    %% Styling
    classDef service fill:#D6EFFF,stroke:#0366d6,color:#000
    classDef db fill:#DAF7A6,stroke:#228B22,color:#000
    classDef external fill:#FADBD8,stroke:#d35400,color:#000
    classDef ui fill:#E8DAEF,stroke:#8e44ad,color:#000
    classDef config fill:#F9E79F,stroke:#b7950b,color:#000
```
