# kapoorashish474/mcp-agent architecture

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

- Interactive diagram: https://gitdiagram.com/kapoorashish474/mcp-agent
- Repository: https://github.com/kapoorashish474/mcp-agent

## Overview

##### Project Type & Purpose
- It’s a modular, backend-centric AI assistant with a CLI (and optional Web UI) that fetches live weather, news, and stock data via distinct “tool servers,” then synthesizes results through Google’s Gemini LLM using the MCP protocol.

##### File Structure
- Top-level:
- src/main.py – CLI/Web UI entrypoint and command router
- src/mcp_client/ – handles Gemini LLM integration and MCP protocol orchestration
- src/mcp_servers/ – three micro-service modules: weather_server, news_server, stock_server
- src/tools/ – implementations of external API adapters (OpenWeatherMap, NewsAPI.org, yfinance)
- docs/design.md and docs/TODO.md contain requirements and high-level design notes.
- requirements.txt lists key frameworks: google-generativeai, httpx, yfinance, python-dotenv, pydantic.

##### README for Architectural Insights
- The README outlines a layered architecture (Presentation, Business Logic, Data Access) and a microservices view (Weather/News/Finance services behind an MCP Gateway).
- Emphasized: asynchronous API calls, modularity, error-handling, extensibility.

##### Main Components & Interactions
a. User Interface (Presentation Layer)
– CLI App (src/main.py) +/- optional Web UI or HTTP API endpoints.
b. Business Logic Layer
– MCP Client:
- gemini_client.py: wraps Google Gemini LLM calls
- mcp_handler.py: implements the Model Context Protocol, orchestrates concurrent tool requests
c. Tool Servers (Microservices)
– weather_server.py → WeatherTool (src/tools/weather_tool.py) → OpenWeatherMap API
– news_server.py   → NewsTool   (src/tools/news_tool.py)   → NewsAPI.org
– stock_server.py  → StockTool  (src/tools/stock_tool.py)   → Yahoo Finance (yfinance)
d. External Services (Data Access Layer)
– OpenWeatherMap, NewsAPI.org, Yahoo Finance endpoints (REST/HTTP)

##### Architectural Patterns & Principles
- Layered Architecture: clear separation between Presentation, Business Logic, Data Access
- Microservices: each data source encapsulated as an independent MCP server
- Async Processing: use of httpx for concurrent calls to external APIs
- Protocol-Oriented Design: MCP handler abstracts interaction pattern between LLM and data sources
- Extensibility: adding a new data source requires adding a new tool + server module

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["CLI Application"]:::presentation
    end

    %% Documentation and Dependencies
    docsDesign["Design Documentation"]:::docs
    docsTODO["High-Level Requirements/TODOs"]:::docs
    requirements["Dependency Definitions"]:::docs

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        MCPHandler["MCP Protocol Handler"]:::business
        GeminiClient["Gemini LLM Integration"]:::business
        LLMService["Google Gemini LLM"]:::llm
    end

    %% Microservices Layer
    subgraph "Microservices (MCP Servers)"
        WeatherServer["Weather Tool Server"]:::service
        NewsServer["News Tool Server"]:::service
        StockServer["Stock Tool Server"]:::service
    end

    %% Tool Adapters
    subgraph "Tool Adapters"
        WeatherTool["WeatherTool Adapter"]:::adapter
        NewsTool["NewsTool Adapter"]:::adapter
        StockTool["StockTool Adapter"]:::adapter
    end

    %% External Services
    subgraph "External Services"
        OpenWeatherMap["OpenWeatherMap API"]:::external
        NewsAPI["NewsAPI.org"]:::external
        YahooFinance["Yahoo Finance (yfinance)"]:::external
    end

    %% Data Flow
    CLI -->|"invoke command"| MCPHandler
    MCPHandler -->|"process prompt"| GeminiClient
    GeminiClient -->|"calls LLM"| LLMService
    MCPHandler -->|"dispatch async calls"| WeatherServer
    MCPHandler -->|"dispatch async calls"| NewsServer
    MCPHandler -->|"dispatch async calls"| StockServer

    WeatherServer -->|"uses adapter"| WeatherTool
    NewsServer -->|"uses adapter"| NewsTool
    StockServer -->|"uses adapter"| StockTool

    WeatherTool -->|"HTTP async call"| OpenWeatherMap
    NewsTool -->|"HTTP async call"| NewsAPI
    StockTool -->|"HTTP async call"| YahooFinance

    LLMService -->|"response"| MCPHandler
    MCPHandler -->|"aggregate results"| CLI

    %% Click Events
    click CLI "https://github.com/kapoorashish474/mcp-agent/blob/main/src/main.py"
    click MCPHandler "https://github.com/kapoorashish474/mcp-agent/blob/main/src/mcp_client/mcp_handler.py"
    click GeminiClient "https://github.com/kapoorashish474/mcp-agent/blob/main/src/mcp_client/gemini_client.py"
    click WeatherServer "https://github.com/kapoorashish474/mcp-agent/blob/main/src/mcp_servers/weather_server.py"
    click NewsServer "https://github.com/kapoorashish474/mcp-agent/blob/main/src/mcp_servers/news_server.py"
    click StockServer "https://github.com/kapoorashish474/mcp-agent/blob/main/src/mcp_servers/stock_server.py"
    click WeatherTool "https://github.com/kapoorashish474/mcp-agent/blob/main/src/tools/weather_tool.py"
    click NewsTool "https://github.com/kapoorashish474/mcp-agent/blob/main/src/tools/news_tool.py"
    click StockTool "https://github.com/kapoorashish474/mcp-agent/blob/main/src/tools/stock_tool.py"
    click docsDesign "https://github.com/kapoorashish474/mcp-agent/blob/main/docs/design.md"
    click docsTODO "https://github.com/kapoorashish474/mcp-agent/blob/main/docs/TODO.md"
    click requirements "https://github.com/kapoorashish474/mcp-agent/blob/main/requirements.txt"

    %% Styles
    classDef presentation fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef docs fill:#f9f9f9,stroke:#999,stroke-dasharray: 5 5
    classDef business fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef service fill:#c5cae9,stroke:#3949ab,stroke-width:1px
    classDef adapter fill:#d1c4e9,stroke:#7e57c2,stroke-width:1px
    classDef llm fill:#c8e6c9,stroke:#388e3c,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#f57c00,stroke-width:1px
```
