FAQ RAG Chatbot — PeopleForce HR SaaS

Intelligent support chatbot system for FAQs based on Retrieval-Augmented Generation (RAG). It processes an FAQ document from an HR SaaS company, indexes it in a vector database, and answers user questions by retrieving the most relevant fragments from the document to generate accurate responses with an LLM. This eliminates the need for manual searches and reduces the burden on the customer support team.

RAG Architecture

┌──────────────────────────────────────────────────────────────────┐
│                    PIPELINE DE INDEXACIÓN                        │
│                                                                  │
│  faq_document.txt ──► Chunking ──► Embeddings ──► ChromaDB      │
│                     (300 chars,   (text-embedding   (persistente │
│                      50 overlap)   -3-small)         local)      │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│                    PIPELINE DE CONSULTA                          │
│                                                                  │
│  Pregunta ──► Embedding ──► k-NN Search ──► Contexto ──► LLM    │
│  del usuario   de query     (coseno,        (top-k       (gpt-4o │
│                              ChromaDB)       chunks)      -mini)  │
│                                                     │            │
│                                                     ▼            │
│                                              JSON Response       │
│                                        { user_question,          │
│                                          system_answer,          │
│                                          chunks_related }        │
└──────────────────────────────────────────────────────────────────┘

Related MCP server: RAG-MCP

Installation

1. Clone the repository

git clone <repo-url>
cd kunz-mcp-project

2. Create virtual environment and install dependencies

python -m venv .venv
source .venv/bin/activate   # macOS/Linux
# .venv\Scripts\activate    # Windows

pip install -r requirements.txt

3. Configure API Key

cp .env.example .env
# Edita .env y agrega tu clave de OpenAI:
# OPENAI_API_KEY=sk-...

Usage

Run the indexing pipeline

python src/build_index.py

This loads data/faq_document.txt, splits it into chunks, generates embeddings, and stores them in ChromaDB (data/chroma_db/).

Run a query

python src/query.py "¿Cuántos días de vacaciones me corresponden?"

Example JSON output:

{
  "user_question": "¿Cuántos días de vacaciones me corresponden?",
  "system_answer": "Todos los colaboradores de tiempo completo tienen derecho a 15 días hábiles de vacaciones al año a partir de su primer aniversario. Con más de 3 años de antigüedad, se reciben 20 días hábiles, y con más de 7 años, 25 días hábiles.",
  "chunks_related": [
    {
      "text": "¿Cuántos días de vacaciones me corresponden?...",
      "metadata": {
        "chunk_index": 1,
        "total_chunks": 30,
        "source": "faq_document.txt"
      }
    }
  ]
}

Run the evaluator agent (Bonus)

python src/evaluator.py

Evaluates the responses in outputs/sample_queries.json and returns a 0-10 score with justification.

MCP Server (Model Context Protocol)

The project includes src/mcp_server.py, which exposes the RAG pipeline as an MCP server so that AI agents (Claude Desktop, Cursor, VS Code with Copilot, etc.) can invoke the tools directly.

Available Tools

Prerequisite

Make sure you have built the index before starting the server:

python src/build_index.py

Option A — Run directly (stdio mode)

python src/mcp_server.py

This launches the server in stdio mode, compatible with any MCP client.

Option B — Run with MCP CLI

mcp run src/mcp_server.py

Option C — Integrate with Claude Desktop

Edit the Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hr-faq-rag": {
      "command": "python",
      "args": ["/ruta/absoluta/a/kunz-mcp-project/src/mcp_server.py"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Restart Claude Desktop. The server will appear as an available tool in the chat.

Option D — Integrate with Cursor or VS Code

Add to the editor's MCP configuration (.cursor/mcp.json or settings.json):

{
  "mcpServers": {
    "hr-faq-rag": {
      "command": "python",
      "args": ["src/mcp_server.py"]
    }
  }
}

Note: the server reads OPENAI_API_KEY from the project's .env file; if the editor does not inherit the environment, pass it explicitly in the "env" block as shown in Option C.

Project structure

kunz-mcp-project/
├── README.md               # Documentación del proyecto
├── requirements.txt        # Dependencias con versiones
├── .env.example            # Plantilla de variables de entorno
├── config.yaml             # Configuración del modelo, embeddings y RAG
├── data/
│   └── faq_document.txt    # Documento FAQ fuente (≥1000 palabras)
├── src/
│   ├── __init__.py
│   ├── build_index.py      # Pipeline de indexación (load → chunk → embed → store)
│   ├── query.py            # Pipeline de consulta (search → generate → JSON)
│   ├── evaluator.py        # Agente evaluador de calidad (bonus)
│   ├── mcp_server.py       # Servidor MCP (expone los tools vía FastMCP)
│   └── shared/
│       ├── __init__.py
│       ├── config_loader.py  # Carga config.yaml + .env
│       └── logger.py         # Logger con Rich (colores y formato)
└── outputs/
    └── sample_queries.json   # ≥3 ejemplos de consulta-respuesta

Technical decisions

Chunking strategy

RecursiveCharacterTextSplitter is used with chunk_size=300 and chunk_overlap=50.

• Why recursive? Hierarchical separators (\n\n → \n → . → ) preserve the natural semantic boundaries of the text (sections, paragraphs, sentences), producing more coherent chunks than a fixed-size cut.

• Why 300 characters? It generates chunks of ~75-125 tokens, within the required range of 50-500 tokens. Smaller chunks improve vector search accuracy by reducing semantic noise.

• Why 50 overlap? The overlap ensures context continuity between adjacent chunks, preventing relevant information from being cut off at a boundary.

Vector search method

k-NN (k-Nearest Neighbors) with cosine similarity is used over the HNSW index of ChromaDB.

• Why k-NN? It is the most direct and predictable method for similar vector search. ChromaDB optimizes internally with HNSW (Hierarchical Navigable Small World) for sub-linear searches.

• Why cosine? Cosine similarity measures the semantic direction of vectors, not their magnitude. It is ideal for normalized text embeddings like those from OpenAI (text-embedding-3-small), where vectors with similar meaning point in the same direction.

• Top-k = 3 returns between 2-5 chunks per query, enough to provide context without introducing noise.

RAG benefits

• Update without re-training: Simply update the source document and re-index, without the need for costly LLM fine-tuning.

• Transparency: Each response includes the chunks used (chunks_related), allowing verification of the information source.

• Attribution: The metadata of each chunk (source, chunk_index) enables full traceability of the response.

Configuration

The config.yaml file centralizes all parameters: