🇫🇷 Version française

genai-mcp-assistant

A RAG + agent + MCP server assistant that answers technical questions about DevOps / Kubernetes / Docker using a local knowledge base: core concepts, networking pitfalls, and a personal troubleshooting journal. Built to concretely apply, on a real use case, a modern GenAI stack:

• Python (backend, data pipeline, MCP server)

• RAG (Retrieval-Augmented Generation): document chunking, vector embeddings, a vector database (ChromaDB), semantic search

• Local LLM via Ollama (no external API key required)

• LangChain / LangGraph for the RAG chain and an agent that decides on its own when to query the knowledge base (agentic AI)

• MCP server (official mcp SDK) exposing the assistant as MCP tools usable by any MCP client (Cursor, Claude Desktop, etc.)

• Docker for containerization

• Kubernetes / Helm for deployment (full chart included)

• Automated tests (pytest), CI-ready

Why this project

This project exists to concretely demonstrate a modern GenAI/agentic stack (RAG, embeddings, local LLM, LangChain/LangGraph, MCP servers) end to end, on a domain (Kubernetes/Docker troubleshooting) that lends itself well to retrieval-augmented Q&A: there's a mix of stable reference concepts and concrete, narrower troubleshooting knowledge that benefits from being looked up rather than guessed by the LLM alone.

The knowledge base is intentionally generic — it is not tied to any specific company, job application, or individual. It's meant to be shown as a standalone technical project.

Related MCP server: Markdown RAG MCP

Architecture

┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
│  data/*.txt       │ ---> │  ingest.py        │ ---> │  ChromaDB         │
│  (K8s/Docker docs,│      │  chunking +       │      │  (vectorstore/)   │
│   troubleshooting)│      │  embeddings       │      └────────┬─────────┘
└──────────────────┘      └──────────────────┘               │
                                                               │ semantic
                                                               ▼ search
┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
│  rag.py           │ <--> │  agent.py         │      │  mcp_server.py    │
│  retrieval + LLM  │      │  LangGraph ReAct  │      │  FastMCP tools     │
│  (Ollama)         │      │  (agentic loop)   │      │  (stdio / HTTP)    │
└──────────────────┘      └──────────────────┘      └──────────────────┘

Quickstart (local)

Prerequisites: Ollama installed and running (brew install ollama && brew services start ollama), with the following models pulled:

ollama pull llama3.2:3b
ollama pull nomic-embed-text

Then:

make venv install   # create the venv and install dependencies
make ingest          # chunk the knowledge base, compute embeddings, persist to ChromaDB
make test            # run the automated test suite (pytest)

Query the assistant via the agent (CLI)

make agent
# or with a custom question:
.venv/bin/python -m genai_mcp_assistant.agent "How do I debug a Kubernetes pod stuck in CrashLoopBackOff?"

Run the MCP server

make mcp   # stdio transport, to plug into an MCP client (Cursor, Claude Desktop, ...)

Tools exposed (mcp_server.py):

Containerized deployment

make docker-up     # runs Ollama + the MCP server (HTTP transport) via docker-compose

Kubernetes deployment (Helm)

A complete Helm chart is provided in helm/genai-mcp-assistant/:

helm install genai-mcp-assistant ./helm/genai-mcp-assistant \
  --set image.repository=<your-registry>/genai-mcp-assistant \
  --set image.tag=0.1.0

The chart deploys: a Deployment, a Service, a ConfigMap (env vars), and a PersistentVolumeClaim for the vector store. Ollama is assumed to run as a separate service in the cluster (OLLAMA_BASE_URL configurable via values.yaml).

Project structure

genai-mcp-assistant/
├── data/
│   └── knowledge_base/          # Kubernetes/Docker docs + troubleshooting journal (RAG knowledge base)
├── src/genai_mcp_assistant/
│   ├── config.py                # centralized configuration (env vars)
│   ├── ingest.py                # loading + chunking + embeddings -> ChromaDB
│   ├── rag.py                   # retrieval + generation (LangChain + Ollama)
│   ├── agent.py                 # LangGraph agent (agentic AI, tool-use)
│   └── mcp_server.py            # MCP server (FastMCP) exposing the tools
├── tests/                       # automated tests (pytest)
├── helm/genai-mcp-assistant/    # Helm chart (Deployment, Service, ConfigMap, PVC)
├── Dockerfile
├── docker-compose.yml
└── Makefile

What this project demonstrates (and what it doesn't)

Demonstrates: end-to-end Python development, RAG, vector embeddings, semantic search, LLM orchestration (LangChain/LangGraph), designing an agent that autonomously decides when to use its tools, building an MCP server exposing MCP tools, Docker containerization, writing a Helm chart for Kubernetes, automated testing.

Does NOT demonstrate: training or fine-tuning ML/deep-learning models (the LLM and the embedding model are used purely at inference time, pre-trained and served via Ollama), classical statistical analysis, data visualization, or scientific publication work. It's a focused, infrastructure-and-orchestration-layer project, not a machine-learning- research project.

Known limitations / possible improvements

• llama3.2:3b is deliberately lightweight to run without a GPU; answer quality (and citation accuracy) improves noticeably with a larger model.

• No automated answer-quality re-evaluation yet (e.g. RAGAS or similar).

• The LangGraph agent only has one tool for now; adding a second tool (e.g. a structured lookup against a small severity/runbook table) would better illustrate genuine multi-step agentic reasoning.