# elkhn/mcp-playground architecture

> Architecture diagram of the GitHub repository elkhn/mcp-playground, 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/elkhn/mcp-playground
- Repository: https://github.com/elkhn/mcp-playground

## Overview

##### Project Type and Purpose
- This is a containerized, micro-service playground combining a Streamlit-based chat UI with multiple FastMCP tool servers.
- Purpose: Let users chat with LLMs (via LangChain/LangGraph) and dynamically invoke external “MCP” tools (Weather, Currency) in a provider-agnostic way.

##### File Structure
- Top level:
- docker-compose.yaml → orchestrates three services (client + two servers)
- client/ → Streamlit front-end application
- servers/ → two FastMCP back-end tool servers (weather + currency)
- client/ breakdown:
- app.py, config.py, servers_config.json → entry point and runtime settings
- services/ → wrappers for AI provider, MCP orchestration, chat logic
- ui_components/ → Streamlit widgets (sidebar, main panel)
- utils/ → prompt definitions, async helpers, schema parser
- servers/ breakdown: each contains a Dockerfile, main.py, requirements.txt hosting FastMCP tools

##### README for Additional Insights
- Confirms architecture:
- Streamlit client ↔ multiple FastMCP servers, all in Docker Compose
- Uses LangChain + LangGraph to create a React agent that auto-discovers tools
- Supports plugging in new MCP servers via servers_config.json
- External dependencies: OpenAI, Amazon Bedrock, Anthropic, Google Gemini

##### Elements
- Green for UI components
- Blue for internal services (agent, chat, ai_service, mcp_service)
- Orange for external systems (LLM providers, MCP servers)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker Compose Orchestrator Boundary
    subgraph "Docker Compose" 
        direction TB
        subgraph "Client Container" 
            direction TB
            UIGroup["Streamlit UI"] 
            subgraph "UI Components"
                direction TB
                Main["Main Panel"]:::ui
                Sidebar["Sidebar"]:::ui
            end
            Config["servers_config.json"]:::config
            subgraph "Agent & Services"
                direction TB
                ReactAgent["React Agent (LangGraph)"]:::service
                ChatService["Chat Service"]:::service
                AIService["AI Service (LangChain)"]:::service
                MCPService["MCP Service"]:::service
            end
        end

        subgraph "MCP Tool Cluster"
            direction TB
            WeatherServer["Weather Service\n(port 8000)"]:::tool
            CurrencyServer["Currency Service\n(port 8001)"]:::tool
        end
    end

    %% External LLM Providers
    subgraph "External LLM Providers"
        direction TB
        OpenAI["OpenAI"]:::external
        Bedrock["Amazon Bedrock"]:::external
        Anthropic["Anthropic"]:::external
        Gemini["Google Gemini"]:::external
    end

    %% User Interaction
    User["User"] 
    User -->|"HTTP"| Main
    User -->|"HTTP"| Sidebar

    %% UI to Agent & Services
    Main -->|"UI Event"| ReactAgent
    Sidebar -->|"UI Event"| ReactAgent

    ReactAgent -->|"invoke chat"| ChatService
    ChatService -->|"LLM API"| AIService
    AIService -->|"API Request"| OpenAI
    AIService -->|"API Request"| Bedrock
    AIService -->|"API Request"| Anthropic
    AIService -->|"API Request"| Gemini
    ReactAgent -->|"tool call"| MCPService
    Config -->|"reads at startup"| MCPService

    MCPService -->|"HTTP /tool"| WeatherServer
    MCPService -->|"HTTP /tool"| CurrencyServer
    WeatherServer -->|"response"| MCPService
    CurrencyServer -->|"response"| MCPService
    MCPService -->|"results"| Main

    %% Click Events for Component Mapping
    click docker-compose.yaml "https://github.com/elkhn/mcp-playground/blob/main/docker-compose.yaml"
    click ClientContainer "https://github.com/elkhn/mcp-playground/tree/main/client/Dockerfile"
    click Main "https://github.com/elkhn/mcp-playground/blob/main/client/app.py"
    click Config "https://github.com/elkhn/mcp-playground/blob/main/client/servers_config.json"
    click AIService "https://github.com/elkhn/mcp-playground/blob/main/client/services/ai_service.py"
    click ChatService "https://github.com/elkhn/mcp-playground/blob/main/client/services/chat_service.py"
    click MCPService "https://github.com/elkhn/mcp-playground/blob/main/client/services/mcp_service.py"
    click Main "https://github.com/elkhn/mcp-playground/blob/main/client/ui_components/main_components.py"
    click Sidebar "https://github.com/elkhn/mcp-playground/blob/main/client/ui_components/sidebar_components.py"
    click AIPrompts "https://github.com/elkhn/mcp-playground/blob/main/client/utils/ai_prompts.py"
    click AsyncHelpers "https://github.com/elkhn/mcp-playground/blob/main/client/utils/async_helpers.py"
    click SchemaParser "https://github.com/elkhn/mcp-playground/blob/main/client/utils/tool_schema_parser.py"
    click WeatherServer "https://github.com/elkhn/mcp-playground/tree/main/servers/server1/Dockerfile"
    click WeatherServer "https://github.com/elkhn/mcp-playground/blob/main/servers/server1/main.py"
    click WeatherServer "https://github.com/elkhn/mcp-playground/blob/main/servers/server1/requirements.txt"
    click CurrencyServer "https://github.com/elkhn/mcp-playground/tree/main/servers/server2/Dockerfile"
    click CurrencyServer "https://github.com/elkhn/mcp-playground/blob/main/servers/server2/main.py"
    click CurrencyServer "https://github.com/elkhn/mcp-playground/blob/main/servers/server2/requirements.txt"

    %% Styling
    classDef ui fill:#a8e6cf,stroke:#379683,color:#05386b;
    classDef service fill:#d0e1f9,stroke:#4d648d,color:#1f2833;
    classDef tool fill:#ffd3b6,stroke:#ff8b94,color:#6b2737;
    classDef external fill:#f0e5d8,stroke:#c38d9e,color:#6e0303;
    classDef config fill:#ffeead,stroke:#ddc88e,color:#6e4923;
```
