How gopeshkhandelwal/idc-llm-mcp works
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