# paul60209/langchain_with_mcp architecture

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

- Interactive diagram: https://gitdiagram.com/paul60209/langchain_with_mcp
- Repository: https://github.com/paul60209/langchain_with_mcp

## Overview

##### Project Type and Purpose
- This is a microservices-style, full-stack AI application with a Chainlit web UI (“Client”) that embeds a Langchain Agent. The Agent communicates with three independent “tool servers” over the Model Context Protocol (MCP) via Server-Sent Events (SSE). Each tool server provides a specialized function (weather lookup, SQL queries, PPT translation), and they in turn call external services (OpenWeatherMap, MySQL, OpenAI, python-pptx).

##### High-Level Architectural Layers
a. Launch & Management Layer
- run.py, run_server.py, run_client.py – scripts that start/stop all subprocesses (client + servers).
- server_config.txt – persists dynamically chosen ports for each tool server.
b. Application Layer (Client)
- app.py – Chainlit UI + Langchain Agent + MCP Client Adapter.
- chainlit.config.json / chainlit.md – UI configuration.
c. Tool Server Layer
- MCP_Servers/weather_server.py – FastAPI/Starlette/Uvicorn serving the “query_weather” tool.
- MCP_Servers/sql_query_server.py – “query_database” tool backed by MySQL.
- MCP_Servers/ppt_translator_server.py – “translate_ppt” tool using OpenAI and python-pptx.
d. External Services
- OpenWeatherMap API, MySQL Database, OpenAI API

##### Main Components & Interactions
- Chainlit Web UI (browser) ←→ Chainlit Server (app.py)
- Renders chat interface; forwards user messages to the Langchain Agent.
- Langchain Agent (in app.py)
- Discovers and invokes “tools” via the MCP Client Adapter.
- MCP Client Adapter (in app.py)
- Maintains SSE connections to each tool server.
- Sends MCP-formatted JSON requests; listens to event stream responses.
- MCP Tool Servers (on ports 8001–8003)
- Each runs as an independent Python process under Uvicorn.
- Exposes an SSE endpoint (e.g., /sse) that accepts MCP requests and returns streamed events.
- External Dependencies
- Weather Server calls OpenWeatherMap via HTTP.
- SQL Server uses CLEARDB_DATABASE_URL to run SELECT queries against MySQL.
- PPT Server calls OpenAI API to translate and python-pptx to manipulate files.

##### Architectural Patterns & Design Principles
- Microservices / Client-Server: Each tool server is decoupled and independently deployable.
- Adapter Pattern: The MCP Client Adapter bridges Langchain’s tool interface to the standardized MCP protocol.
- Event-Driven Communication: SSE used for real-time, streaming responses.
- Configuration-as-Code: .env for secrets; server_config.txt for dynamic ports.
- Launch Orchestration: run.py offers a unified CLI menu to start/stop sub-processes.

##### Diagramming Conventions
- Related elements within bounded “layers” (e.g., Client Layer, Server Layer, External Services).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Launch & Management Layer
    subgraph "Launch & Management Layer"
        direction TB
        run_py["run.py"]:::launch
        run_server_py["run_server.py"]:::launch
        run_client_py["run_client.py"]:::launch
        server_config_txt["server_config.txt"]:::launch
        env_example[".env_example"]:::launch
        mcp_config["mcp_server_config.py"]:::launch
        sdk_doc["MCP Python SDK.md"]:::launch
        protocol_guide["MCP-guide.txt"]:::launch
    end

    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Browser UI (Chainlit Web UI)"]:::frontend
        ChainlitServer["Chainlit Server<br/>(app.py)"]:::frontend
        chainlit_json["chainlit.config.json"]:::frontend
        chainlit_md["chainlit.md"]:::frontend
    end

    %% Agent Layer
    subgraph "Agent Layer"
        direction TB
        Agent["Langchain Agent"]:::agent
        Adapter["MCP Client Adapter<br/>(SSE Client)"]:::agent
    end

    %% Tool Server Layer
    subgraph "Tool Server Layer"
        direction TB
        WeatherServer["Weather Server<br/>(port 8001)"]:::server
        SQLServer["SQL Query Server<br/>(port 8002)"]:::server
        PPTServer["PPT Translator Server<br/>(port 8003)"]:::server
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenWeather["OpenWeatherMap API"]:::external
        MySQLDB["MySQL Database"]:::external
        OpenAIAPI["OpenAI API"]:::external
    end

    %% Relationships
    run_py --> run_server_py
    run_py --> run_client_py
    run_py --> server_config_txt
    run_py --> env_example
    run_py --> mcp_config
    run_py --> sdk_doc
    run_py --> protocol_guide

    run_client_py --> Browser
    run_server_py --> ChainlitServer
    server_config_txt --> WeatherServer
    server_config_txt --> SQLServer
    server_config_txt --> PPTServer

    Browser <-->|"renders UI / sends messages"| ChainlitServer
    ChainlitServer -->|"forwards user input"| Agent
    Agent -->|"discovers/invokes tools"| Adapter

    Adapter <-->|"MCP JSON over SSE"| WeatherServer
    Adapter <-->|"MCP JSON over SSE"| SQLServer
    Adapter <-->|"MCP JSON over SSE"| PPTServer

    WeatherServer -->|"HTTP Request"| OpenWeather
    SQLServer -->|"SQL Query"| MySQLDB
    PPTServer -->|"OpenAI & python-pptx"| OpenAIAPI

    %% Click Events
    click run_py "https://github.com/paul60209/langchain_with_mcp/blob/main/./run.py"
    click run_server_py "https://github.com/paul60209/langchain_with_mcp/blob/main/./run_server.py"
    click run_client_py "https://github.com/paul60209/langchain_with_mcp/blob/main/./run_client.py"
    click server_config_txt "https://github.com/paul60209/langchain_with_mcp/blob/main/./server_config.txt"
    click env_example "https://github.com/paul60209/langchain_with_mcp/blob/main/./.env_example"
    click mcp_config "https://github.com/paul60209/langchain_with_mcp/blob/main/./mcp_server_config.py"
    click sdk_doc "https://github.com/paul60209/langchain_with_mcp/blob/main/./ref/MCP Python SDK.md"
    click protocol_guide "https://github.com/paul60209/langchain_with_mcp/blob/main/./ref/MCP-guide.txt"
    click ChainlitServer "https://github.com/paul60209/langchain_with_mcp/blob/main/./app.py"
    click chainlit_json "https://github.com/paul60209/langchain_with_mcp/blob/main/./chainlit.config.json"
    click chainlit_md "https://github.com/paul60209/langchain_with_mcp/blob/main/./chainlit.md"
    click WeatherServer "https://github.com/paul60209/langchain_with_mcp/blob/main/./MCP_Servers/weather_server.py"
    click SQLServer "https://github.com/paul60209/langchain_with_mcp/blob/main/./MCP_Servers/sql_query_server.py"
    click PPTServer "https://github.com/paul60209/langchain_with_mcp/blob/main/./MCP_Servers/ppt_translator_server.py"

    %% Styles
    classDef launch fill:#f0f0f0,stroke:#888;
    classDef frontend fill:#e0ffe0,stroke:#2d7;
    classDef agent fill:#e0f0ff,stroke:#27a;
    classDef server fill:#ffe0b3,stroke:#f90;
    classDef external fill:#ffe0e0,stroke:#f33;
```
