# kelvinqiu802/llm-mcp-rag architecture

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

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

## Overview

This project is an augmented LLM system that combines Chat capabilities, the Model Context Protocol (MCP), and a simplified Retrieval Augmented Generation (RAG) mechanism. Its purpose is to process content (such as reading web pages or local documents), summarize it, and store the output in files. The system is built without relying on external frameworks (like LangChain or AutoGen) and is implemented in TypeScript.

##### Main Components
- Agent: The central controller that initializes and coordinates interactions among various services.
- ChatOpenAI: Handles communication with the OpenAI API, processes prompts, and manages chat messages.
- MCPClient: Manages interactions with multiple MCP servers; it is responsible for calling and orchestrating tools via MCP.
- EmbeddingRetriever: Generates embeddings for documents and queries, and performs retrieval from the vector store.
- VectorStore: Stores and retrieves vector embeddings along with their associated document information.

##### Relationships and Interactions
- The Agent interacts with both the ChatOpenAI and MCPClient; it delegates tasks and calls methods on these objects.
- ChatOpenAI communicates with the OpenAI API to generate chat completions, optionally manages tool calls.
- Agent uses MCPClient to perform tool executions via MCP; this client abstracts multiple MCP Servers.
- The EmbeddingRetriever relies on VectorStore to both add embeddings of documents and search due to queries from the RAG process.
- The flow from knowledge (input) → EmbeddingRetriever/VectorStore (to capture context) → ChatOpenAI (to generate responses) illustrates the retrieval augmentation pipeline.

##### Architectural Patterns and Design Principles
- Modular design: Each file in the src directory corresponds to a discrete module (Agent, ChatOpenAI, etc.), emphasizing separation of concerns.
- Integration: The system integrates multiple external services (e.g., OpenAI API, MCP servers) via specific client modules.
- Simplified RAG: The Retrieval Augmented Generation design is implemented by embedding documents and retrieving context based on queries.
- Dependency Injection and Composition: Although not explicitly stated, note how the Agent uses instances of MCPClient and ChatOpenAI in a decoupled way.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Controller
    subgraph "Core Controller"
        A["Agent"]:::core
    end

    %% LLM Services
    subgraph "LLM Services"
        CO["ChatOpenAI"]:::core
        MCP["MCPClient"]:::core
    end

    %% Retrieval Augmentation
    subgraph "Retrieval Augmentation"
        ER["EmbeddingRetriever"]:::retrieval
        VS["VectorStore"]:::retrieval
    end

    %% External Interfaces
    OAPI["OpenAI API"]:::external
    MCPsrv["MCP Servers"]:::external
    K["Knowledge (Input)"]:::external
    OUT["Output (Destination)"]:::external

    %% Connections
    %% Agent interactions
    A -->|"delegates-chat"| CO
    A -->|"delegates-tool-calls"| MCP
    A -->|"queries"| ER

    %% LLM Services external calls
    CO -->|"calls"| OAPI
    MCP -->|"calls"| MCPsrv

    %% Retrieval Augmentation flow
    K -->|"reads"| ER
    ER -->|"stores/searches"| VS
    VS -->|"provides-context"| CO

    %% Output flow
    CO -->|"generates-summary"| OUT

    %% Click Events
    click A "https://github.com/kelvinqiu802/llm-mcp-rag/blob/main/src/Agent.ts"
    click CO "https://github.com/kelvinqiu802/llm-mcp-rag/blob/main/src/ChatOpenAI.ts"
    click MCP "https://github.com/kelvinqiu802/llm-mcp-rag/blob/main/src/MCPClient.ts"
    click ER "https://github.com/kelvinqiu802/llm-mcp-rag/blob/main/src/EmbeddingRetriever.ts"
    click VS "https://github.com/kelvinqiu802/llm-mcp-rag/blob/main/src/VectorStore.ts"
    click K "https://github.com/kelvinqiu802/llm-mcp-rag/tree/main/knowledge"
    click OUT "https://github.com/kelvinqiu802/llm-mcp-rag/tree/main/output"

    %% Styles
    classDef core fill:#C1E1C1,stroke:#2F8F2F,stroke-width:2px;
    classDef retrieval fill:#C1D4E1,stroke:#2F5F8F,stroke-width:2px;
    classDef external fill:#FFE4B5,stroke:#CD853F,stroke-width:2px;
```
