# straydragon/exp-llm-mcp-rag architecture

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

- Interactive diagram: https://gitdiagram.com/straydragon/exp-llm-mcp-rag
- Repository: https://github.com/straydragon/exp-llm-mcp-rag

## Overview

##### Project Type and Purpose
- This project is an experimental AI assistant system that leverages Large Language Models (LLM), the Model Context Protocol (MCP), and Retrieval-Augmented Generation (RAG). Its purpose is to demonstrate interactions between a language model and external tools (through MCP) as well as how the system uses vector retrieval to augment responses with contextual data.

##### File Structure
- Notice the primary source folder is “src/augmented/” which contains the core modules:
- agent.py – the central coordinator.
- chat_openai.py – handles LLM invocation through OpenAI.
- mcp_client.py & mcp_tools.py – manage the MCP interactions.
- embedding_retriever.py and vector_store.py – implement the RAG (with retrieval and vector search).
- Additional util functions in “utils/”.
- Configuration files and examples (e.g., .env.example, justfile, and rag_example.py) indicate how to run and test the system.
- The “output” directory holds some result logs and knowledge documents, hinting at how the system might process and present retrieved information.

##### README for Additional Insights
- The README gives a full overview, including key functionality like LLM API calls, MCP integration, and the RAG system.
- This provides excellent guidance on how components interact and which dependencies (such as OpenAI API, vector store, and MCP) are critical.

##### Main Components and Their Interactions
a. Major Components:
- User: the external client making queries.
- Agent: the central coordinator that interacts with LLM and tools.
- LLM (via AsyncChatOpenAI): for language model interaction.
- MCP Client: manages the invocation of external tools based on MCP.
- MCP Server (implied): performs file system operations or web content retrieval.
- EmbeddingRetriever & VectorStore: power the RAG functionality by embedding queries and retrieving knowledge.
- Logger (ALogger): records interactions and actions.
b. Relationships and Interactions:
- The user sends a query to the Agent.
- The Agent logs the operation, calls the EmbeddingRetriever to look up relevant context from the VectorStore, then combines the context with the query and sends it to the LLM.
- The LLM produces a response and may trigger a tool call via the MCP Client.
- The MCP Client interacts with the external MCP Server (which handles things like file system operations or web fetches) and returns the output.
- Results from MCP are fed back into the LLM for refining the final answer that is sent back to the user.
c. Patterns & Design Principles:
- The architecture follows a modular design where the Agent orchestrates many independent modules (LLM, MCP, RAG components).
- Interaction flows are based on request-response patterns, with clear separation of concerns (communication, logging, retrieval, and external tool invocation).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    U["User"]:::frontend
    Agent["Agent"]:::core
    Logger["ALogger"]:::utility
    LLM["AsyncChatOpenAI"]:::processing
    Embedding["EmbeddingRetriever"]:::processing
    Vector["VectorStore"]:::database
    MCPClient["MCP Client"]:::external
    MCPTools["MCP Tools"]:::external
    MCPServer["MCP Server (External)"]:::external
    Util["Utility Functions"]:::utility

    %% Data Flow
    U -->|"sends query"| Agent
    Agent -->|"logs operation"| Logger
    Agent -->|"retrieves context"| Embedding
    Embedding -->|"queries vector data"| Vector
    Vector -->|"returns context"| Embedding
    Embedding -->|"provides data"| Agent
    Agent -->|"processes query"| LLM
    LLM -->|"invokes tool"| MCPClient
    MCPClient -->|"calls MCP tools"| MCPTools
    MCPTools -->|"fetches data from"| MCPServer
    MCPServer -->|"returns tool result"| MCPTools
    MCPTools -->|"sends result"| MCPClient
    MCPClient -->|"returns to"| LLM
    LLM -->|"finalizes response"| Agent
    Agent -->|"responds to"| U

    %% Click Events
    click Agent "https://github.com/straydragon/exp-llm-mcp-rag/blob/main/src/augmented/agent.py"
    click LLM "https://github.com/straydragon/exp-llm-mcp-rag/blob/main/src/augmented/chat_openai.py"
    click MCPClient "https://github.com/straydragon/exp-llm-mcp-rag/blob/main/src/augmented/mcp_client.py"
    click MCPTools "https://github.com/straydragon/exp-llm-mcp-rag/blob/main/src/augmented/mcp_tools.py"
    click MCPTools "https://github.com/straydragon/exp-llm-mcp-rag/blob/main/src/augmented/utils/mcp_tools.py"
    click Embedding "https://github.com/straydragon/exp-llm-mcp-rag/blob/main/src/augmented/embedding_retriever.py"
    click Vector "https://github.com/straydragon/exp-llm-mcp-rag/blob/main/src/augmented/vector_store.py"
    click Util "https://github.com/straydragon/exp-llm-mcp-rag/tree/main/src/augmented/utils/"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef core fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef processing fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef utility fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef database fill:#FAD7A0,stroke:#BA4A00,stroke-width:2px;
```
