# mouhsineguet/mcp_rag_agent architecture

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

- Interactive diagram: https://gitdiagram.com/mouhsineguet/mcp_rag_agent
- Repository: https://github.com/mouhsineguet/mcp_rag_agent

## Overview

##### Project Type and Purpose
- This is a full-stack document-centric conversational AI application (RAG pipeline)
- Purpose: let end users upload documents (PDF, DOCX, TXT), index them semantically, and chat with them via a large language model (Llama 3.2)

##### File Structure and Architectural Patterns
- Top-level files:
– app.py: Streamlit frontend (UI)
– mcp_server.py: Document processing microservice (MCP = “multi-chain processing”)
– mcp_client.py: Client library for talking to the MCP server
– ollama_client.py: Client for interacting with the Ollama LLM server
– requirements.txt: Python dependencies
- Pattern: separation of concerns into three main components (frontend, processing backend, LLM backend)
- Uses a microservice-style RPC between app.py and mcp_server.py via mcp_client.py

##### Key Components
A. Streamlit Frontend
- Upload UI
- Controls “Process Document” and chat interface
B. MCP Server (mcp_server.py)
- Document ingestion and parsing (PDF/DOCX/TXT)
- Chunking logic (DocumentProcessor.chunk_text)
- Embedding service (sentence-transformers model)
- FAISS index creation and search
C. Ollama LLM Server
- Hosted locally via “ollama run llama3.2:3b”
- Exposes REST or socket API for inference
D. Clients
- mcp_client.py calls MCP server endpoints (e.g., /chunk, /embed, /search)
- ollama_client.py issues chat completion requests to Ollama
E. Orchestration / RAG Pipeline (in app.py)
- On user query:
– Call MCP server to retrieve top-k relevant chunks
– Merge chunks + question into prompt
– Call Ollama client for generation
– Display response

##### Relationships and Data Flow
1. User → Streamlit UI (app.py)
2. Streamlit UI → MCP Server via mcp_client
- Document upload → /process endpoint
- Search query → /search endpoint
3. MCP Server
- Parses document → chunks → embeddings → FAISS index
- Returns chunk IDs and text snippets on search
4. Streamlit UI → Ollama LLM via ollama_client
- Sends prompt (question + context chunks)
- Receives generated answer
5. UI displays answer to user

##### Architectural Patterns and Design Principles
- Single-Page Web App (Streamlit) + Backend microservices
- RAG pattern: separation of retrieval (FAISS) and generation (LLM)
- External services isolated by client wrappers (mcp_client, ollama_client)

##### Essential Elements to Capture
- Clear labels for each component (UI, MCP server, Embedding, FAISS, Ollama)
- Annotations for technologies/frameworks (Streamlit, Python, FAISS, sentence-transformers, Ollama)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Frontend
    User["User"]:::external
    subgraph "Frontend Layer"
        UI["Streamlit App"]:::frontend
    end

    %% Client Wrappers
    subgraph "Client Libraries"
        MC["mcp_client.py"]:::backend
        OC["ollama_client.py"]:::backend
    end

    %% Backend Services
    subgraph "Backend Services"
        MS["MCP Server"]:::backend
        subgraph "MCP Internal"
            Parser["Document Parser & Chunker"]:::backend
            Embed["Embedding Service<br/>(sentence-transformers)"]:::backend
            FAISS["FAISS Index"]:::db
        end
    end

    %% LLM Service
    LLM["Ollama LLM Server"]:::external

    %% Other
    Requirements["requirements.txt"]:::external
    ExampleDoc["Example PDF<br/>(2503.23278v2.pdf)"]:::db

    %% Connections: Upload & Processing
    User -->|"uploads doc"| UI
    UI -->|"POST /process with file"| MC
    MC -->|"RPC: /process"| MS
    MS --> Parser
    Parser -->|"chunks text"| Embed
    Embed -->|"embeddings"| FAISS
    FAISS -->|"index stored"| FAISS

    %% Connections: Search & Retrieval
    UI -->|"GET /search?q=..."| MC
    MC -->|"RPC: /search"| MS
    MS --> FAISS
    FAISS -->|"chunk IDs + snippets"| MS
    MS --> MC
    MC --> UI

    %% Connections: Generation
    UI -->|"generate(prompt)"| OC
    OC -->|"API call: /chat"| LLM
    LLM -->|"response"| OC
    OC --> UI
    UI -->|"displays answer"| User

    %% Click Events
    click UI "https://github.com/mouhsineguet/mcp_rag_agent/blob/main/app.py"
    click MC "https://github.com/mouhsineguet/mcp_rag_agent/blob/main/mcp_client.py"
    click MS "https://github.com/mouhsineguet/mcp_rag_agent/blob/main/mcp_server.py"
    click OC "https://github.com/mouhsineguet/mcp_rag_agent/blob/main/ollama_client.py"
    click Requirements "https://github.com/mouhsineguet/mcp_rag_agent/blob/main/requirements.txt"
    click ExampleDoc "https://github.com/mouhsineguet/mcp_rag_agent/blob/main/2503.23278v2.pdf"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:2px
    classDef backend fill:#D5F5E3,stroke:#237804,stroke-width:2px
    classDef external fill:#FFE5B4,stroke:#d48806,stroke-width:2px
    classDef db fill:#FFF2CC,stroke:#d4b106,stroke-width:2px
```
