Skip to main content

RAG & MCP Architecture

To allow AI agents (like the Secretary Agent or coding assistants) to efficiently access technical knowledge, we have implemented a Retrieval-Augmented Generation (RAG) system exposed via the Model Context Protocol (MCP).

Overview​

The system runs as a set of Docker containers alongside the main documentation site.

  1. Docusaurus: Serves the human-readable HTML documentation.
  2. RAG Service: A Python application providing the query_knowledge_base tool.
  3. PostgreSQL (pgvector): Stores document embeddings for semantic search.

Components​

1. Vector Database (rag-postgres)​

  • Image: pgvector/pgvector:pg16
  • Role: Stores documents (metadata) and document_chunks (text + 1536d embeddings).
  • Search: Uses HNSW indexing and Cosine Distance (<=>) to find relevant documentation chunks.

2. RAG Service (rag-service)​

  • Path: <local_root>/rag-service/
  • Role: Exposes the search functionality to AI agents using MCP over Server-Sent Events (SSE).
  • Tool: query_knowledge_base(query: str)

3. The Indexer​

  • Script: rag-service/indexer.py
  • Role:
    1. Scans documentation/docs/ for .md and .mdx files.
    2. Calculates checksums to skip processing text that hasn't changed.
    3. Splits updated files into 1000-token chunks (with 200-token overlap).
    4. Generates embeddings using OpenAI text-embedding-3-small.
    5. Updates the Postgres database.

Usage​

Prerequisites​

  • OPENAI_API_KEY must be set in the environment or .env file.

First Run (Indexing)​

The database starts empty. To verify content, run the indexer manually:

docker-compose run --rm rag-service python indexer.py

Running the Server​

The server starts automatically with the docker stack:

docker-compose up -d --build

The MCP server listens on port 8080.