# gopeshkhandelwal/idc-llm-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/gopeshkhandelwal/idc-llm-mcp
- Repository: https://github.com/gopeshkhandelwal/idc-llm-mcp

## Overview

##### Project type and purpose
- This is a full-stack agent framework that integrates open-source and OpenAI LLMs with Intel Developer Cloud (IDC) via a Model Context Protocol (MCP) server.
- It combines Retrieval-Augmented Generation (RAG), LangGraph orchestration, LangChain tool-calling, local vectorstores (FAISS), and PostgreSQL for long-term memory.

##### File structure
- Top-level scripts and config
- .env.example, Makefile, run.sh: environment, build, and run targets
- requirements.txt: Python dependencies
- Utilities (common_utils/)
- download_model.py, build_vectorstore.py, rag_test.py
- config.py for reading .env, database schema (conversation_history.sql)
- Client module (mcp_client/)
- client.py: entrypoint for user queries
- db_utils.py: short-term memory in Postgres
- langgraph_graph.py, langgraph_tool_wrappers.py: defines LangGraph workflows
- Server module (mcp_server/)
- server.py: HTTP/gRPC server exposing tool execution endpoints
- tools/: individual tool implementations (idc_images, idc_pools, weather, RAG)
- utils/http.py: request handling, auth, logging
- Documentation (docs/) for gRPC API and usage guides

##### Insights from the README
- Supports local Hugging Face and OpenAI GPT models
- Orchestrates multi-step, multi-tool workflows via LangGraph
- Secure, logged tool execution on cloud infrastructure
- Builds and queries a FAISS vectorstore for document QA
- Stores conversation history in PostgreSQL (short- and long-term memory)

a. Main components
- User Interface: CLI or script invoking mcp_client
- mcp_client:
– Query handler (user → Graph agent)
– LangGraph orchestrator + LangChain tool wrappers
– RAG retriever (FAISS vectorstore via common_utils)
– LLM layer (local HuggingFace models or OpenAI API)
- MCP Server (mcp_server):
– HTTP/gRPC API endpoint
– Tool registry and executor
– Tools: IDC pools/images, weather, RAG handler, custom tools
- Data stores and caches:
– Vectorstore (FAISS index directory)
– PostgreSQL (conversation_history)
– Local HF model cache (resources/models)
- External services:
– OpenAI API
– Hugging Face Hub
– IDC REST APIs (pools, images)
b. Relationships and interactions
1. User submits a natural language query via CLI → mcp_client
2. mcp_client loads config, passes query to LangGraph agent
3. Agent decides sequence:
– For facts/document QA → calls RAG retriever (common_utils/build_vectorstore + FAISS)
– For action requests → wraps a tool call (langgraph_tool_wrappers)
4. LLM (local or OpenAI) generates parameters or next action
5. mcp_client invokes MCP Server API (HTTP/gRPC) with tool name and args
6. MCP Server authenticates, logs, dispatches to tool implementation
7. Tool calls external IDC APIs or queries local vectorstore/DB
8. Tool returns result → MCP Server returns to client → LangGraph composes final answer
9. mcp_client logs conversation to PostgreSQL for long-term memory
c. Architectural patterns and principles
- Microservice-style separation: client vs. server
- Plugin architecture: each tool is self-contained under mcp_server/tools
- Orchestration layer: LangGraph for multi-tool, multi-step workflows
- Data-flow directionality: queries flow client → server → external; results flow back
- Security: token-based auth, centralized logging of all tool executions
d. Key technologies and libraries
- Python 3.x, FastAPI or gRPC (mcp_server/utils/http.py)
- LangGraph for orchestration
- LangChain tool-calling adapters
- FAISS vectorstore for RAG (common_utils/build_vectorstore)
- PostgreSQL for conversation history
- Hugging Face Transformers & Hub for local LLMs
- OpenAI-compatible API layer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Utilities & Offline
    subgraph "Utilities & Offline"
        direction TB
        EnvConfig[".env.example"]:::utils
        BuildScripts["Makefile / run.sh / requirements.txt"]:::utils
        DownloadModel["download_model.py"]:::utils
        BuildVectorstore["build_vectorstore.py"]:::utils
        RagTest["rag_test.py"]:::utils
        ConfigLoader["config.py"]:::utils
        ConversationSchema["conversation_history.sql"]:::utils
    end

    %% Client Layer
    subgraph "Client Layer"
        direction TB
        ClientEntry["client.py"]:::orchestration
        ShortTermMemory["db_utils.py"]:::utils
        Orchestration["langgraph_graph.py"]:::orchestration
        ToolWrappers["langgraph_tool_wrappers.py"]:::orchestration
    end

    %% Server Layer
    subgraph "Server Layer"
        direction TB
        ServerCore["server.py"]:::orchestration
        ServerHTTP["utils/http.py"]:::utils
        IDCImages["idc_images.py"]:::tools
        IDCPools["idc_pools.py"]:::tools
        Weather["weather.py"]:::tools
        RAGHandler["rag.py"]:::tools
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        PostgresDB[(PostgreSQL)]:::models
        FAISSStore[(FAISS Index)]:::models
        LocalModelCache["Local HF Model Cache"]:::models
    end

    %% External Integrations
    subgraph "External Integrations"
        direction TB
        OpenAI[/OpenAI API/]:::external
        HuggingFace[/Hugging Face Hub/]:::external
        IDCAPI[/IDC REST APIs/]:::external
    end

    %% Offline Workflow
    DownloadModel -->|"downloads models"| LocalModelCache
    BuildVectorstore -->|"builds index"| FAISSStore

    %% Online Query Flow
    User["User CLI"]:::external
    User -->|"natural language query"| ClientEntry
    EnvConfig --> ClientEntry
    ClientEntry -->|loads config| ConfigLoader
    ClientEntry -->|"invoke orchestration"| Orchestration
    Orchestration -->|"calls tool wrappers"| ToolWrappers
    Orchestration -->|"request embedding"| FAISSStore
    ToolWrappers -->|"tool request"| ServerCore
    ClientEntry -->|"log conversation"| PostgresDB

    %% LLM Calls
    Orchestration -->|"LLM call"| LocalModelCache
    Orchestration -->|"LLM call"| OpenAI
    LocalModelCache -->|"response"| Orchestration
    OpenAI -->|"response"| Orchestration

    %% Server Execution Flow
    ServerCore -->|auth / log| ServerHTTP
    ServerCore -->|"dispatch to tool"| IDCImages
    ServerCore -->|"dispatch to tool"| IDCPools
    ServerCore -->|"dispatch to tool"| Weather
    ServerCore -->|"dispatch to tool"| RAGHandler

    %% Tools to Data/External
    IDCImages -->|"calls"| IDCAPI
    IDCPools -->|"calls"| IDCAPI
    Weather -->|"calls"| IDCAPI
    RAGHandler -->|"queries"| FAISSStore

    %% Responses back to client
    IDCImages -->|"result"| ServerCore
    IDCPools -->|"result"| ServerCore
    Weather -->|"result"| ServerCore
    RAGHandler -->|"result"| ServerCore
    ServerCore -->|"tool response"| ClientEntry
    ClientEntry -->|"final answer"| User

    %% Documentation
    GRPCDocs["docs/grpc_api_guide.txt"]:::utils

    %% Click Events
    click EnvConfig "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/.env.example"
    click BuildScripts "https://github.com/gopeshkhandelwal/idc-llm-mcp/tree/main/Makefile"
    click BuildScripts "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/run.sh"
    click BuildScripts "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/requirements.txt"
    click DownloadModel "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/common_utils/download_model.py"
    click BuildVectorstore "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/common_utils/build_vectorstore.py"
    click RagTest "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/common_utils/rag_test.py"
    click ConfigLoader "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/common_utils/config.py"
    click ConversationSchema "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/common_utils/database/conversation_history.sql"
    click ClientEntry "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/mcp_client/client.py"
    click ShortTermMemory "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/mcp_client/db_utils.py"
    click Orchestration "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/mcp_client/langgraph_graph.py"
    click ToolWrappers "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/mcp_client/langgraph_tool_wrappers.py"
    click ServerCore "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/mcp_server/server.py"
    click ServerHTTP "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/mcp_server/utils/http.py"
    click IDCImages "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/mcp_server/tools/idc_images.py"
    click IDCPools "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/mcp_server/tools/idc_pools.py"
    click Weather "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/mcp_server/tools/weather.py"
    click RAGHandler "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/mcp_server/tools/rag.py"
    click GRPCDocs "https://github.com/gopeshkhandelwal/idc-llm-mcp/blob/main/docs/grpc_api_guide.txt"

    %% Styles
    classDef orchestration fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef models fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef tools fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef utils fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef external fill:#f0f4c3,stroke:#333,stroke-width:1px
```
