# gomezzz299/mcp architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack, multi-agent question-routing system (“MCP”) with:
- A backend (FastAPI) that hosts core logic, agent orchestration and a SQLite database
- A frontend GUI (Streamlit) that sends user requests to the backend
- Modular “agents” that can call LLMs or each other to answer queries

##### File structure
─ Top-level containers and orchestration
- Dockerfile.frontend, Dockerfile.backend, docker-compose.yml
─ Frontend
- gui/app.py (Streamlit GUI)
- .streamlit/secrets.toml (backend URL)
─ Backend
- server/api.py (FastAPI endpoints)
- server/mcp_server.py (agent registry, message dispatch)
─ Core logic
- core/router_llm.py (smart router that picks an agent)
- core/context_loader.py (loads contextual data from DB)
- core/ollama_wrapper.py (calls Ollama LLM)
─ Agents
- agentes/*.py (fecha_hora, ubicacion, clima, estado_servidor) all inheriting from utils/agente_base.py
─ Utilities & DB
- utils/db_utils.py, json_parser.py
- database/context.db (SQLite), create_db.py, comprobar_db.py
─ Configuration
- config.py (central flags, paths, model names)

##### README for additional insights
- Features: modular agents, LLM wrapper, containerized frontend+backend
- Deployment: docker-compose elevates two containers (frontend:8501, backend:8000)
- Agent collaboration: e.g. clima agent calls ubicacion agent for geo-coordinates

a. Main components
- Frontend Container (Streamlit GUI)
- Backend Container (FastAPI App)
- Core Services within backend:
– API Layer (server/api.py)
– Dispatcher/Server (server/mcp_server.py)
– Router (core/router_llm.py)
– Context Loader (core/context_loader.py)
– LLM Wrapper (core/ollama_wrapper.py)
- Agent Module (agentes/*.py)
- Database (SQLite context.db)
- External Services:
– Ollama LLM endpoint
– (Optionally) third-party weather or geolocation APIs

b. Relationships and data flow
1. User interacts with Streamlit GUI → sends HTTP POST to FastAPI /process
2. API Layer receives request → forwards to mcp_server dispatch
3. mcp_server registers available agents → delegates to router_llm
4. router_llm analyzes user query → picks appropriate agent(s)
5. Chosen agent:
- (Optionally) calls other agents (e.g. clima → ubicacion)
- Queries context Loader → may hit SQLite via db_utils
- Calls LLM via ollama_wrapper if natural language generation is needed
6. Agent returns structured response → mcp_server wraps it → API returns to GUI

c. Architectural patterns and principles
- Modular plugin pattern for agents (inherit from AgenteBase)
- Layered architecture: GUI → API → Dispatcher → Router → Agents → DB/LLM
- Hexagonal/adapters for external integrations (DB, LLM service)
- Containerized micro-services style separation (frontend vs backend)

d. Key technologies and frameworks
- Python 3.x
- FastAPI (server/api.py)
- Streamlit (gui/app.py)
- SQLite (database/context.db)
- Docker & Docker Compose
- Ollama LLM via core/ollama_wrapper.py

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Container
    subgraph "Frontend Container"
        direction TB
        GUI["Streamlit GUI<br>gui/app.py"]:::frontend
        Secrets[".streamlit/secrets.toml"]:::frontend
        DockerFE["Dockerfile.frontend"]:::infra
    end

    %% Backend Container
    subgraph "Backend Container"
        direction TB
        DockerBE["Dockerfile.backend"]:::infra
        Compose["docker-compose.yml"]:::infra
        Main["main.py"]:::backend
        Config["config.py"]:::backend

        subgraph "API Layer"
            API["FastAPI API<br>server/api.py"]:::backend
        end

        subgraph "Dispatcher"
            MCP["Dispatcher<br>server/mcp_server.py"]:::backend
        end

        subgraph "Core Services"
            Router["Router (smart selector)<br>core/router_llm.py"]:::core
            Context["Context Loader<br>core/context_loader.py"]:::core
            LLM["LLM Wrapper<br>core/ollama_wrapper.py"]:::core
        end

        subgraph "Agents Module"
            Base["AgenteBase<br>utils/agente_base.py"]:::agents
            FH["fecha_hora.py"]:::agents
            UB["ubicacion.py"]:::agents
            CL["clima.py"]:::agents
            ES["estado_servidor.py"]:::agents
        end

        subgraph "Database & Utilities"
            DB["SQLite DB<br>database/context.db"]:::database
            CreateDB["create_db.py"]:::database
            CheckDB["comprobar_db.py"]:::database
            DBUtils["db_utils.py"]:::database
            JSONP["json_parser.py"]:::backend
        end
    end

    %% External Services
    subgraph "External Services"
        Ollama["Ollama LLM Service"]:::external
        ThirdParty["Weather/Geo APIs"]:::external
    end

    %% Data Flow
    GUI -->|"1. POST /process"| API
    API -->|"2. dispatch_request()"| MCP
    MCP -->|"3. select_agent()"| Router
    Router -->|"4. invoke"| FH
    Router -->|"4. invoke"| UB
    Router -->|"4. invoke"| CL
    Router -->|"4. invoke"| ES
    CL -->|"calls"| UB
    FH -->|"load context"| Context
    UB -->|"load context"| Context
    CL -->|"load context"| Context
    ES -->|"load context"| Context
    Context -->|"query"| DB
    Context -->|"DB operations"| DBUtils
    Context -->|"init/check"| CreateDB
    Context -->|"init/check"| CheckDB
    CL -->|"generate text"| LLM
    FH -->|"generate text"| LLM
    UB -->|"generate text"| LLM
    ES -->|"generate text"| LLM
    LLM -->|"HTTP"| Ollama
    CL -->|"HTTP"| ThirdParty
    UB -->|"HTTP"| ThirdParty
    MCP -->|"wrap response"| API
    API -->|"5. return response"| GUI

    %% Click Events
    click GUI "https://github.com/gomezzz299/mcp/blob/main/gui/app.py"
    click Secrets "https://github.com/gomezzz299/mcp/blob/main/.streamlit/secrets.toml"
    click DockerFE "https://github.com/gomezzz299/mcp/blob/main/Dockerfile.frontend"
    click DockerBE "https://github.com/gomezzz299/mcp/blob/main/Dockerfile.backend"
    click Compose "https://github.com/gomezzz299/mcp/blob/main/docker-compose.yml"
    click Main "https://github.com/gomezzz299/mcp/blob/main/main.py"
    click Config "https://github.com/gomezzz299/mcp/blob/main/config.py"
    click API "https://github.com/gomezzz299/mcp/blob/main/server/api.py"
    click MCP "https://github.com/gomezzz299/mcp/blob/main/server/mcp_server.py"
    click Router "https://github.com/gomezzz299/mcp/blob/main/core/router_llm.py"
    click Context "https://github.com/gomezzz299/mcp/blob/main/core/context_loader.py"
    click LLM "https://github.com/gomezzz299/mcp/blob/main/core/ollama_wrapper.py"
    click Base "https://github.com/gomezzz299/mcp/blob/main/utils/agente_base.py"
    click FH "https://github.com/gomezzz299/mcp/blob/main/agentes/fecha_hora.py"
    click UB "https://github.com/gomezzz299/mcp/blob/main/agentes/ubicacion.py"
    click CL "https://github.com/gomezzz299/mcp/blob/main/agentes/clima.py"
    click ES "https://github.com/gomezzz299/mcp/blob/main/agentes/estado_servidor.py"
    click DB "https://github.com/gomezzz299/mcp/blob/main/database/context.db"
    click CreateDB "https://github.com/gomezzz299/mcp/blob/main/database/create_db.py"
    click CheckDB "https://github.com/gomezzz299/mcp/blob/main/database/comprobar_db.py"
    click DBUtils "https://github.com/gomezzz299/mcp/blob/main/database/db_utils.py"
    click JSONP "https://github.com/gomezzz299/mcp/blob/main/utils/json_parser.py"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064
    classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef core fill:#C8E6C9,stroke:#2E7D32,color:#2E7D32
    classDef agents fill:#FFF9C4,stroke:#F9A825,color:#F9A825
    classDef database fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef external fill:#E1BEE7,stroke:#6A1B9A,color:#6A1B9A
    classDef infra fill:#CFD8DC,stroke:#37474F,color:#37474F
    class GUI,Secrets frontend
    class API,MCP backend
    class Router,Context,LLM core
    class Base,FH,UB,CL,ES agents
    class DB,CreateDB,CheckDB,DBUtils database
    class Ollama,ThirdParty external
    class DockerFE,DockerBE,Compose infra
```
