MCP Kbdb

🚀 rag-mcp: a ridiculously over-engineered retrieval system

Welcome to rag-mcp, a project that answers the age-old question: "What if we took a perfectly good idea—retrieval-augmented generation—and made it so complicated it becomes a monument to our own hubris?" It's a model context protocol (mcp) server that slings text embeddings around like a coked-up short-stop, using PostgreSQL and the pgvector extension because, honestly, who needs simplicity?

This project is for the real sickos, the ones who look at a problem and think, "I could solve this with a simple script, but what if, instead, I built a byzantine system of interlocking parts that will be a nightmare to maintain?" You're my people.

🚀 Quick Start

📦 Installation

Getting this beast to run is a rite of passage.

Prerequisites:

• Python 3.whatever. If it works, it works.
• PostgreSQL, with the pgvector extension enabled. If you don't know how to do that, google it. This isn't a charity.

Installation Steps:

1. Clone the repo. Obviously.
2. Install the python dependencies:

pip install -r requirements.txt

3. Set up the database. Connect to your PostgreSQL instance and run the create_tables.pgsql script. It'll create the tables and the fancy hnsw indexes for fast vector searches.
4. Set environment variables. You can create a .env file or just set them in the environment, your choice.

# database stuff
rm_db_host=localhost
rm_db_port=5432
rm_db_name=your_db_name
rm_db_user=your_db_user
rm_db_password=your_super_secret_password

# embedding model stuff
rm_openai_api_key=your_api_key
rm_openai_endpoint=your_model_endpoint_url

💻 Usage Examples

Basic Usage

If you've made it this far, you're either a genius or you're very, very lost. Either way, let's fire it up.

1. Run the server:

python rag_mcp_server.py

2. If it doesn't immediately crash and burn, the server is now listening, exposing its mcp tools to the world. You can now call search_style, search_qa, and search_semantic_similarity from whatever mcp client you've got.

Connecting from Clients

So you've got this glorious monstrosity running. Now what? You need something to talk to it. If you're using some AI assistant thingy in VSCode or Claude Desktop or whatever, you'll need to tell it how to find our server.

You'll probably have to edit some JSON settings file. Find the spot for mcpServers and add something like this:

{
  "mcpServers": {
    "RAG-MCP Knoledge Base Server": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/location/of/the/script/rag_mcp_server.py:mcp"
      ],
      "env": {
        "RM_DB_HOST": "localhost",
        "RM_DB_PORT": "5432",
        "RM_DB_NAME": "your_db_name",
        "RM_DB_USER": "your_db_user",
        "RM_DB_PASSWORD": "your_super_secret_password",
        "RM_OPENAI_API_KEY": "your_api_key",
        "RM_OPENAI_ENDPOINT": "your_model_endpoint_url"
      },
      "transport": "stdio",
      "type": null,
      "cwd": null,
      "timeout": null,
      "description": null,
      "icon": null,
      "authentication": null
    }
  }
}

Obviously, change /location/of/the/script/rag_mcp_server.py:mcp to the actual location of the script. And fill in the env with your secrets. Don't just copy-paste this like a mindless drone. Or do. I'm not your dad.

✨ Features

What the hell is this thing?

At its core, rag-mcp is a Python server that provides a set of tools for searching a knowledge base of text. But instead of just one boring way to search, we've got modalities. Think of them as different flavors of search, each one a special little snowflake optimized for a specific kind of task.

• Semantic search: For when you want to find things that are, like, vibing with your query.
• Question/answer search: You ask a question, it pretends to have the answer. Classic.
• Style search: Finds stuff that feels the same. It's like a sommelier for text. Deeply pretentious and surprisingly useful.

It's all built on the fastmcp framework, which means you can talk to it with other AI agents, creating a truly absurd, self-referential ouroboros of code.

🔧 Technical Details

Architecture, or "how the sausage gets made"

It's a beautiful mess. Here's the blueprint:

1. The server (rag_mcp_server.py): A Python script that's the brains of the operation. It handles incoming requests, talks to the database, and generally tries to keep its cool.
2. The database (postgresql + pgvector): This is where we stash all the text and its corresponding vector embeddings. The create_tables.pgsql script lays out the whole schema, which is surprisingly organized for something I came up with. We're talking documents, document_chunks, and embeddings tables, all linked up. It's almost professional.
3. The embedding engine (openai-compatible): We need something to turn words into numbers. The server calls out to an OpenAI-compatible API to get the embeddings. You get to provide the endpoint, so you can use whatever weird, home-brewed model you want.
4. The tools: The server exposes its search modalities as mcp tools. Right now, we've got search_semantic_similarity, search_qa, and search_style.

📚 Documentation

Extending the system, or "make it weirder"

The best part of this whole thing is how easy it is to make it even more baroque. You can add your own search modalities. Maybe you want a search that only returns results in iambic pentameter. Maybe you want one that searches for recipes for disaster. Go nuts.

I wrote a whole damn manual for it. Check out manual.md. It'll walk you through the process of adding new models, tasks, and tool functions. It's so easy, it's almost disappointing.

📄 License

This project is provided as-is, without any warranty, express or implied. If it sets your computer on fire, that's on you. You chose this life.