🇫🇷 [Version française](README.fr.md)

# 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.

## 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](https://ollama.com) installed and running
(`brew install ollama && brew services start ollama`), with the following
models pulled:

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

Then:

```bash
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)

```bash
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

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

Tools exposed (`mcp_server.py`):

| Tool | Description |
|---|---|
| `list_knowledge_topics` | Lists the ingested knowledge base files |
| `search_docs(query, k)` | Raw semantic search (no generation) |
| `ask_devops_question(question)` | Full RAG pipeline (retrieval + generated answer) |
| `search_troubleshooting_journal(symptom)` | Targeted search in the personal troubleshooting journal, from a symptom description |

## Containerized deployment

```bash
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/`:

```bash
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.