# 3choff/mcp-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/3choff/mcp-chatbot
- Repository: https://github.com/3choff/mcp-chatbot

## Overview

##### Project type and purpose
- This is a CLI‑based chatbot client showcasing integration of the Model Context Protocol (MCP) with any OpenAI‑style LLM.
- It dynamically discovers “tools” (external services or functions) from configured MCP servers, formats them into the system prompt, sends user queries to the LLM, optionally invokes tools, and returns results to the user.

##### File structure
- Top‑level files:
- main.py (entry point, orchestrates the chat session)
- servers_config.json (declarative list of MCP servers and how to launch them)
- requirements.txt / .env.example (dependencies & environment variables)
- No frontend/backend split—this is a single process CLI app.
- The presence of “mcp” and “uvicorn” in dependencies hints at local or remote HTTP‑style servers used as “tool providers.”

##### Extract architecture hints from the README
- Class structure: Configuration, Server, Tool, LLMClient, ChatSession

##### Main components
a. Configuration Loader
- Reads .env and servers_config.json, produces an in‑memory list of server definitions and API keys.
b. MCP Server Manager
- Responsible for launching or connecting to each MCP server (via uvicorn for Python servers or npx for Node.js ones).
- Exposes HTTP/gRPC endpoints for tool metadata and execution.
c. Tool Registry / Discovery
- Queries each MCP server’s “/tools” endpoint, builds a catalog of tool definitions (name, description, parameters).
d. LLM Client
- Wraps OpenAI‑style API calls (requests library).
- Builds a system prompt embedding the discovered tool descriptions.
e. ChatSession Orchestrator
- Reads user input from CLI.
- Delegates to LLM Client.
- Parses LLM response to detect “tool calls” vs. “direct text.”
- If tool call: forwards parameters to the appropriate MCP server, awaits result, then resubmits to LLM.
f. CLI Interface
- Simple REPL loop in main.py that passes input to ChatSession and prints ChatSession’s output.
g. External Entities
- LLM Provider (OpenAI‑compatible API endpoint)
- MCP Servers (one per configured tool provider)

##### Relationships and interactions
- User → CLI Interface → ChatSession
- ChatSession → Configuration Loader (at startup)
- ChatSession → MCP Server Manager (init) → Tool Discovery → Tool Registry
- ChatSession (per user message) → LLM Client (with system prompt + tool metadata) → LLM Provider
- LLM Provider → LLM Client → ChatSession
- ChatSession (on tool call) → MCP Server Manager → MCP Server → Tool Execution → ChatSession
- ChatSession → LLM Client (with tool output) → LLM Provider → ChatSession → CLI → User

##### Architectural patterns & design principles
- Pipeline/flow pattern: initialization → discovery → runtime loop
- Single responsibility per class: Configuration, Server management, Tool abstraction, LLM communication, Session orchestration
- Loose coupling: new MCP servers can be added via JSON without code changes
- Dependency inversion: ChatSession depends on abstracted LLMClient and Server interfaces rather than concrete implementations

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client Application"
        direction TB
        ConfigLoader["Configuration Loader"]:::internal
        MCPManager["MCP Server Manager"]:::internal
        ToolRegistry["Tool Registry / Discovery"]:::internal
        LLMClient["LLM Client"]:::internal
        ChatSession["ChatSession Orchestrator"]:::internal
        CLI["CLI Interface (REPL)"]:::internal
    end

    ServersConfig["servers_config.json"]:::config
    EnvFile[".env.example"]:::config
    Reqs["requirements.txt"]:::config
    Doc["README.MD"]:::config

    subgraph "External Services"
        direction TB
        LLM["LLM Provider (OpenAI API)"]:::external
        MCPServer["MCP Servers"]:::external
    end

    ServersConfig -->|reads| ConfigLoader
    EnvFile -->|reads| ConfigLoader
    ConfigLoader -->|provides server list| MCPManager
    MCPManager -->|HTTP/gRPC| MCPServer
    MCPManager -->|discovers tools| ToolRegistry
    ToolRegistry -->|provides tool metadata| ChatSession
    CLI -->|user input| ChatSession
    ChatSession -->|delegates| LLMClient
    LLMClient -->|REST JSON| LLM
    LLM -->|response| LLMClient
    LLMClient -->|result| ChatSession
    ChatSession -->|output| CLI

    ChatSession -->|tool execution request| MCPManager
    MCPManager -->|HTTP/gRPC| MCPServer
    MCPServer -->|tool result JSON| ChatSession

    click ConfigLoader "https://github.com/3choff/mcp-chatbot/blob/main/main.py"
    click MCPManager "https://github.com/3choff/mcp-chatbot/blob/main/main.py"
    click ToolRegistry "https://github.com/3choff/mcp-chatbot/blob/main/main.py"
    click LLMClient "https://github.com/3choff/mcp-chatbot/blob/main/main.py"
    click ChatSession "https://github.com/3choff/mcp-chatbot/blob/main/main.py"
    click CLI "https://github.com/3choff/mcp-chatbot/blob/main/main.py"
    click ServersConfig "https://github.com/3choff/mcp-chatbot/blob/main/servers_config.json"
    click EnvFile "https://github.com/3choff/mcp-chatbot/blob/main/.env.example"
    click Reqs "https://github.com/3choff/mcp-chatbot/blob/main/requirements.txt"
    click Doc "https://github.com/3choff/mcp-chatbot/blob/main/README.MD"

    classDef internal fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef external fill:#E6FFED,stroke:#28a745,color:#28a745
    classDef config fill:#F3F4F6,stroke:#6B7280,color:#374151
```
