# tdtheautomator/mcp architecture

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

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

## Overview

##### Project Type and Purpose
- This is a demo “full-stack” prototype combining a Python back end (MCP clients, servers, LLM agent) with a Gradio-based web UI, integrating external services (Azure OpenAI, web search, stock APIs).
- Its purpose is to showcase MCP tooling: custom MCP server, GitHub MCP server, and custom tools (news search, stock price, historical stock).

##### File Structure
- Top-level scripts/files:
- llm_agent.py – orchestrates calls between UI, clients, and servers.
- web_host.py – launches the Gradio interface.
- prompt_template.md – LLM prompt blueprint.
- requirements.txt, .gitignore, README.md – meta/config.
- clients/
- custom_mcp_client.py – tool wrappers implementing the MCP client interface.
- github_mcp_client.py – alternate client talking to the GitHub-hosted MCP server.
- servers/
- custom_mcp_server.py – lightweight local MCP server exposing endpoints for tool execution.
- No database layer; external dependencies are Azure OpenAI, web search API, stock APIs.

##### README Insights
- Confirms use of Azure OpenAI for LLM calls.
- Mentions both a “GitHub MCP Server (on Docker)” and a custom server.
- Shows that the Web UI is Gradio, driven by web_host.py.
- .env holds secrets: GITHUB_TOKEN, AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT.

a. Client-side:
- Web Browser — accesses the Gradio UI.
- web_host.py (Gradio server) — receives user input (queries), forwards to llm_agent.
b. Orchestration:
- llm_agent.py — constructs LLM prompts (prompt_template.md), chooses appropriate tools (clients), communicates via MCP.
c. Tooling Layer (Clients):
- custom_mcp_client — invokes local MCP server endpoints.
- github_mcp_client — invokes GitHub-hosted MCP server endpoints (requires GITHUB_TOKEN).
d. MCP Servers:
- custom_mcp_server.py — local HTTP endpoint for executing “tools.”
- GitHub MCP Server — external Docker container (separate process).
e. External Services:
- Azure OpenAI (LLM inference).
- Web search API (news).
- Stock price API (latest/historical).

##### Relationships & Data Flow
- Browser → HTTP → Gradio (web_host.py).
- Gradio → Python call → llm_agent.py.
- llm_agent → HTTP (MCP protocol) → MCP Server (custom or GitHub).
- MCP Server → tool implementation → External APIs.
- External API → MCP Server → llm_agent → Gradio → Browser.
- LLM calls: llm_agent → Azure OpenAI REST API → llm_agent.

##### Architectural Patterns & Principles
- Separation of concerns: UI layer (Gradio) vs. orchestration (llm_agent) vs. tool execution (clients/servers).
- Plugin pattern: each tool is a client plugin; MCP server provides a uniform interface.
- Protocol-driven design: MCP defines a standard request/response for context-heavy operations.
- Microservice-like boundary between orchestrator and tool execution.

- [ ] Annotate key protocols (HTTP/REST for MCP, HTTP for Azure OpenAI).
- [ ] Group clients and servers to reflect the “clients/” and “servers/” directories.
- [ ] Show environment variable dependencies (.env).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        Browser["Web Browser"]:::external
        Gradio["Gradio UI<br/>(web_host.py)"]:::ui
    end

    %% Orchestration
    subgraph "Orchestration"
        direction TB
        Agent["LLM Agent<br/>(llm_agent.py)"]:::orchestrator
        Prompt["Prompt Template<br/>(prompt_template.md)"]:::orchestrator
    end

    %% Clients Layer
    subgraph "Clients Directory"
        direction TB
        CustomClient["Custom MCP Client<br/>(custom_mcp_client.py)"]:::client
        GitHubClient["GitHub MCP Client<br/>(github_mcp_client.py)"]:::client
    end

    %% Servers Layer
    subgraph "Servers Directory"
        direction TB
        CustomServer["Custom MCP Server<br/>(custom_mcp_server.py)"]:::server
        GitHubServer["GitHub MCP Server<br/>(Docker External)"]:::server
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Azure["Azure OpenAI"]:::external
        NewsAPI["News Search API"]:::external
        StockAPI["Stock Price API"]:::external
        HistStockAPI["Historical Stock API"]:::external
    end

    %% Flows
    Browser -->|HTTP Request| Gradio
    Gradio -->|User Input Call| Agent
    Prompt -->|Template| Agent
    Agent -->|MCP Request| CustomClient
    Agent -->|MCP Request| GitHubClient
    Agent -->|LLM Prompt| Azure
    CustomClient -->|HTTP/MCP| CustomServer
    GitHubClient -->|HTTP/MCP| GitHubServer
    CustomServer -->|Exec Tool| NewsAPI
    CustomServer -->|Exec Tool| StockAPI
    CustomServer -->|Exec Tool| HistStockAPI
    NewsAPI -->|Response| CustomServer
    StockAPI -->|Response| CustomServer
    HistStockAPI -->|Response| CustomServer
    CustomServer -->|MCP Response| CustomClient
    GitHubServer -->|MCP Response| GitHubClient
    CustomClient -->|Response| Agent
    GitHubClient -->|Response| Agent
    Azure -->|Inference| Agent
    Agent -->|Result| Gradio
    Gradio -->|Render| Browser

    %% Click Events
    click Gradio "https://github.com/tdtheautomator/mcp/blob/main/web_host.py"
    click Agent "https://github.com/tdtheautomator/mcp/blob/main/llm_agent.py"
    click Prompt "https://github.com/tdtheautomator/mcp/blob/main/prompt_template.md"
    click CustomClient "https://github.com/tdtheautomator/mcp/blob/main/clients/custom_mcp_client.py"
    click GitHubClient "https://github.com/tdtheautomator/mcp/blob/main/clients/github_mcp_client.py"
    click CustomServer "https://github.com/tdtheautomator/mcp/blob/main/servers/custom_mcp_server.py"

    %% Styles
    classDef ui fill:#D0E6FF,stroke:#4A90E2,stroke-width:2px
    classDef orchestrator fill:#E2F0D9,stroke:#3C8D0D,stroke-width:2px
    classDef client fill:#FFE6CC,stroke:#FF8C00,stroke-width:2px
    classDef server fill:#FFE6CC,stroke:#FF8C00,stroke-width:2px
    classDef external fill:#F0F0F0,stroke:#666666,stroke-width:1px,stroke-dasharray: 2 2
```
