📦 Download Workshop Files

Download the complete workshop package with all code files, documentation, and dependencies list.

MCP Vector Database Server — Hands-On Workshop

Introduction

Welcome to the MCP Vector Database Server Workshop!

This workshop demonstrates how to build a Model Context Protocol (MCP) server that provides vector database capabilities through a standardized interface. MCP is an open protocol that enables seamless integration between AI applications and data sources, making it easier to build context-aware AI systems.

What is MCP?

Model Context Protocol (MCP) is an open standard created by Anthropic that allows AI assistants to securely access external data sources and tools. Think of it as a universal adapter that lets AI applications connect to various services through a standardized interface.

Key Benefits: - Standardized Communication: One protocol for all integrations - Security: Controlled access to resources - Flexibility: Easy to add new tools and data sources - Interoperability: Works with any MCP-compatible client

Project Overview

This project implements an MCP server that exposes two main capabilities: 1. Vector Database Creation: Generate FAISS indexes from knowledge bases 2. Semantic Search: Query the vector database using natural language

Step 1: Install Docker
Step 2: Run the Project with Docker
Step 3: Understanding the Project
Project Structure
Code Explanation
Key Concepts
Troubleshooting
Advanced Usage

Step 1: Install Docker 🐳

Docker is a platform that allows you to run applications in isolated containers. This workshop uses Docker to simplify setup and ensure consistency across different systems.

Check if Docker is Already Installed

First, check if you already have Docker installed:

# Check Docker version
docker --version

# Check Docker Compose version
docker-compose --version

If both commands work, you can skip to Step 2.

Installing Docker

If Docker is not installed, follow the instructions for your operating system:

🍎 macOS

Download Docker Desktop for Mac from docker.com/products/docker-desktop
Open the downloaded .dmg file
Drag the Docker icon to your Applications folder
Launch Docker Desktop from Applications
Wait for Docker to start (you'll see a whale icon in your menu bar)

Verify installation:

docker --version
docker-compose --version

🪟 Windows

Download Docker Desktop for Windows from docker.com/products/docker-desktop
Run the installer (Docker Desktop Installer.exe)
Follow the installation wizard (enable WSL 2 if prompted)
Restart your computer if required
Launch Docker Desktop
Verify installation in PowerShell or Command Prompt:
```
docker --version
docker-compose --version
```

🐧 Linux

Ubuntu/Debian:

# Update package index
sudo apt-get update

# Install Docker
sudo apt-get install docker.io docker-compose

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Add your user to docker group (to run without sudo)
sudo usermod -aG docker $USER

# Log out and back in, then verify
docker --version
docker-compose --version

Fedora/RHEL/CentOS:

# Install Docker
sudo dnf install docker docker-compose

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Add your user to docker group
sudo usermod -aG docker $USER

# Log out and back in, then verify
docker --version
docker-compose --version

Verify Docker is Running

Test that Docker is working correctly:

# Run a test container
docker run hello-world

If you see a "Hello from Docker!" message, Docker is installed and working correctly! ✅

💡 Troubleshooting: If you encounter permission errors on Linux, make sure you've added your user to the docker group and logged out/in again. Alternatively, you can run commands with sudo.

Step 2: Run the Project with Docker 🚀

Now that Docker is installed, let's run the MCP Vector Database Server project!

1. Extract Workshop Files

First, extract the MCP.zip file you downloaded and navigate to the directory:

# Navigate to where you extracted the files
cd /path/to/MCP

2. Build and Run with Docker

Choose one of the following options to run the project:

Option 1: Using the Helper Script (Easiest)

cd /path/to/MCP

# 1. Build the Docker image
./docker-run.sh build

# 2. Start the container
./docker-run.sh start

# 3. Generate vector database (first time only)
docker-compose exec mcp-server python generate_vector_db.py

# 4. Test with the MCP client
docker-compose exec mcp-server python client_vector.py mcp_vector_server.py

Option 2: Using Docker Compose Directly

# Build and start
docker-compose up -d --build

# Generate vector database
docker-compose exec mcp-server python generate_vector_db.py

# Run client
docker-compose exec mcp-server python client_vector.py mcp_vector_server.py

# Stop container
docker-compose down

Option 3: Using Docker Commands

# Build image
docker build -t oss-chatbot-mcp .

# Run container
docker run -it --name mcp-container -v $(pwd):/app oss-chatbot-mcp

# Execute commands in running container
docker exec -it mcp-container python generate_vector_db.py

Helper Script Commands

The docker-run.sh script provides convenient commands:

Command	Description
`./docker-run.sh build`	Build the Docker image
`./docker-run.sh start`	Start the container in background
`./docker-run.sh run-server`	Run the MCP server
`./docker-run.sh run-client`	Run the MCP client (requires server path argument)
`./docker-run.sh shell`	Open a bash shell in the container
`./docker-run.sh stop`	Stop and remove the container

Complete Docker Workflow

# 1. Build and start container
./docker-run.sh build
./docker-run.sh start

# 2. Generate vector database (first time)
docker-compose exec mcp-server python generate_vector_db.py

# Expected output:
# ✅ FAISS vector DB created successfully!
# 📁 Location: faiss_index
# 📦 Entries: 4 | Dimensions: 384

# 3. Test the system
docker-compose exec mcp-server python client_vector.py mcp_vector_server.py

# Expected output:
# 🔌 Starting MCP client for server: mcp_vector_server.py
# ✅ MCP Handshake Complete
# 🛠 Tools detected: ['create_vector_db', 'search_vector_db']
# 📌 RAW RESPONSE FROM SERVER:
# 1) score=0.7131
# Critical TechWorks Quality...

# 4. When done
./docker-run.sh stop

Docker Architecture

┌─────────────────────────────────────┐
│     Docker Container                │
│  (oss-chatbot-mcp)                  │
├─────────────────────────────────────┤
│                                     │
│  📁 /app (mounted from host)        │
│  ├── mcp_vector_server.py          │
│  ├── client_vector.py               │
│  ├── generate_vector_db.py          │
│  ├── search_vector_db.py            │
│  ├── knowledge_base.json            │
│  └── faiss_index/                   │
│      ├── faiss.index                │
│      ├── embeddings.npy             │
│      └── texts.json                 │
│                                     │
│  🐍 Python 3.12 + Dependencies      │
│  📦 sentence-transformers           │
│  📦 faiss-cpu                        │
│  📦 mcp + fastmcp                    │
│                                     │
└─────────────────────────────────────┘
         ↕ Volume Mount (sync)
┌─────────────────────────────────────┐
│     Host Machine                    │
│  /path/to/MCP/                      │
└─────────────────────────────────────┘

Docker Troubleshooting

Issue: Container not running

Error: service "mcp-server" is not running

Solution:

./docker-run.sh start
# or
docker-compose up -d

Issue: "version is obsolete" warning

Warning: the attribute 'version' is obsolete

Solution: This is just a warning and can be safely ignored. The project works normally. To remove it, you can delete the version: '3.8' line from docker-compose.yml.

Issue: Port already in use

Error: address already in use

Solution:

# Stop existing containers
docker-compose down

# Or find and stop the conflicting container
docker ps
docker stop <container-id>

Issue: FAISS index not found

Error: ERROR: faiss.index missing

Solution:

# Generate the index first
docker-compose exec mcp-server python generate_vector_db.py

Issue: Permission denied

Error: Permission denied when running docker-run.sh

Solution:

# Make the script executable
chmod +x docker-run.sh

Why Use Docker?

✅ No dependency conflicts - Isolated environment
✅ Consistent setup - Works the same on all machines
✅ Easy cleanup - Remove container when done
✅ Pre-configured - All dependencies included
✅ Volume mounting - Edit files on host, run in container

Useful Docker Commands

# View container logs
docker-compose logs -f mcp-server

# Access container shell
./docker-run.sh shell
# or
docker-compose exec mcp-server bash

# Restart container
docker-compose restart mcp-server

# Rebuild image (after changing Dockerfile)
docker-compose build --no-cache

# Remove all stopped containers and images
docker system prune -a

💡 Pro Tip: The Docker volume mount (-v .:/app) automatically syncs files between your host machine and the container. You can edit files on your Mac and they'll be immediately available in the container!

Step 3: Understanding the Project 📚

Now that you have the project running, let's understand what it does and how it works!

What Does This Project Do?

This project implements a Model Context Protocol (MCP) server that provides vector database capabilities. It allows AI assistants to:

🔍 Search knowledge bases using natural language queries
📊 Create vector databases from text documents
🤖 Integrate with AI applications through a standardized interface

How It Works

The system has four main components:

Knowledge Base (knowledge_base.json) - Contains the text data to be searched
Vector Database Generator (generate_vector_db.py) - Converts text into searchable vectors
Search Engine (search_vector_db.py) - Finds relevant information using similarity search
MCP Server (mcp_vector_server.py) - Exposes these capabilities through MCP protocol

Typical Workflow

1. 📝 Add knowledge to knowledge_base.json
2. 🔄 Generate vector database (embeddings)
3. 🚀 Start MCP server
4. 💬 AI assistant queries the server
5. 🎯 Server returns relevant results

Project Structure

MCP/
├── generate_vector_db.py          # Creates FAISS vector database
├── search_vector_db.py             # Searches the vector database
├── mcp_vector_server.py            # MCP server implementation
├── client_vector.py                # MCP client for testing
├── knowledge_base.json             # Knowledge base content
├── docker-compose.yml              # Docker Compose configuration
├── Dockerfile                      # Docker image definition
├── docker-run.sh                   # Helper script for Docker commands
├── faiss_index/                    # Generated vector database directory
│   ├── faiss.index                 # FAISS index (binary)
│   ├── embeddings.npy              # Stored embeddings (numpy array)
│   └── texts.json                  # Text references for retrieval
└── README.md                       # Documentation

File Descriptions

File	Purpose	Type
`generate_vector_db.py`	Standalone script to create vector DB	Utility
`search_vector_db.py`	Standalone script to search vector DB	Utility
`mcp_vector_server.py`	MCP server exposing vector DB tools	Server
`client_vector.py`	MCP client for testing the server	Client
`knowledge_base.json`	Source knowledge base	Data
`faiss.index`	FAISS index file	Generated
`embeddings.npy`	Embedding vectors	Generated
`texts.json`	Text chunks for retrieval	Generated

💻 Code Explanation

Let's dive into each file and understand how the code works. We'll go through the four main Python files that make up this project.

File 1: Generate Vector Database

File: generate_vector_db.py

Overview

This script creates a FAISS vector database from a knowledge base. It demonstrates: - Loading text data from JSON - Generating embeddings using SentenceTransformers - Creating a FAISS index with cosine similarity - Saving the index for later use

📦 Pre-Generated Vector Database Available!

This workshop includes a pre-generated vector database ready to use:

Location: faiss_index_mcp/

Documents: 13 files (Python scripts, documentation, guides)

Chunks: 66 text chunks

Size: ~164 KB (index.faiss + index.pkl)

Embedding Model: all-MiniLM-L6-v2 (384 dimensions)

The database contains knowledge about:

MCP server and client implementation

Vector database generation and search scripts

Docker setup and configuration

Installation guides (INSTALL.md, GUIA_DOCKER.md)

Critical TechWorks principles and best practices

The MCP server exposes this database through standardized tools that AI assistants can query!

Key Components

Embedding Model: all-MiniLM-L6-v2 (lightweight, 384 dimensions)
FAISS Index: IndexFlatIP for inner product (cosine similarity on normalized vectors)
Normalization: Ensures embeddings are unit vectors for cosine similarity
Knowledge Base: Critical TechWorks principles and guidelines

How It Works

# 1. Load knowledge base from JSON
with open("knowledge_base.json", "r") as f:
    data = json.load(f)
    texts = data["Texts"]

# 2. Generate embeddings
model = SentenceTransformer("all-MiniLM-L6-v2")
embeddings = model.encode(texts)
embeddings = normalize(embeddings)  # For cosine similarity

# 3. Create FAISS index
index = faiss.IndexFlatIP(dim)
index.add(embeddings)

# 4. Save index and metadata
faiss.write_index(index, "faiss.index")
np.save("embeddings.npy", embeddings)
json.dump(texts, "texts.json")

How to Run

python3 generate_vector_db.py

Expected Output

🧠 Loading knowledge base from: knowledge_base.json
📚 4 knowledge chunks loaded.
⚙️ Generating embeddings with model: all-MiniLM-L6-v2

✅ FAISS vector DB created successfully!
📁 Location: faiss_index
📦 Entries: 4 | Dimensions: 384

Generated Files

After running, you'll have: - faiss_index/faiss.index - FAISS index file - faiss_index/embeddings.npy - Numpy array of embeddings - faiss_index/texts.json - Original text chunks - knowledge_base.json - Source knowledge base

What You'll Learn

How to create vector embeddings from text
FAISS index creation and configuration
Cosine similarity vs other distance metrics
Efficient storage of embeddings

File 2: Search Vector Database

File: search_vector_db.py

Overview

This script provides a search function for querying the FAISS vector database. It demonstrates: - Loading a pre-built FAISS index - Encoding query text to embeddings - Performing similarity search - Ranking and formatting results

Key Components

Search Function: search_in_faiss(query_text, top_k, index_dir)
Similarity Threshold: Minimum score of 0.35 for valid results
Result Formatting: Displays ranked results with cosine scores

How It Works

# 1. Load FAISS index and texts
index = faiss.read_index("faiss_index/faiss.index")
with open("faiss_index/texts.json") as f:
    texts = json.load(f)

# 2. Encode query
model = SentenceTransformer("all-MiniLM-L6-v2")
query_embedding = model.encode([query])
query_embedding = normalize(query_embedding)

# 3. Search for similar vectors
similarities, indices = index.search(query_embedding, top_k)

# 4. Return ranked results
for rank, (idx, score) in enumerate(zip(indices[0], similarities[0])):
    print(f"Rank {rank+1}: {texts[idx]} (Score: {score:.4f})")

How to Run

Prerequisites: Run generate_vector_db.py first!

# Import and use in Python
python3 -c "
from search_vector_db import search_in_faiss
result = search_in_faiss('What are the quality principles?', top_k=2)
print(result)
"

Expected Output

🔎 Query: What are the quality principles?
Top 2 similar results (cosine)
============================================================
🏅 Rank 1 (Cosine: 0.8234)
Critical TechWorks Quality (Quality, Reliability, and Resilience):
We ensure delivery of high-quality, reliable, and resilient software...
------------------------------------------------------------
🏅 Rank 2 (Cosine: 0.5421)
Critical TechWorks Principles:
A principle is a rule, belief, or idea that guides action...
------------------------------------------------------------

What You'll Learn

How to load and query FAISS indexes
Understanding similarity scores
Result ranking and filtering
Handling edge cases (missing index, dimension mismatches)

File 3: MCP Vector Server

File: mcp_vector_server.py

Overview

This is the core MCP server that exposes vector database functionality through the Model Context Protocol. It demonstrates: - Creating an MCP server with FastMCP - Defining MCP tools (functions callable by clients) - Handling asynchronous operations - Logging and error handling

Key Components

FastMCP Server: Simplified MCP server implementation
Tool 1 - create_vector_db: Creates a FAISS index from JSON
Tool 2 - search_vector_db: Searches the vector database
Logging: Outputs to stderr (doesn't interfere with MCP protocol)

MCP Tools Exposed

Tool 1: `create_vector_db`

Purpose: Create a FAISS vector database from a JSON knowledge base

Parameters: - json_path (str): Path to the knowledge base JSON file - output_dir (str): Directory to save the FAISS index

Returns: Success message with entry count

Example:

{
  "json_path": "knowledge_base.json",
  "output_dir": "faiss_index"
}

Tool 2: `search_vector_db`

Purpose: Search the vector database using semantic similarity

Parameters: - query (str): Search query in natural language - index_dir (str): Directory containing the FAISS index - top_k (int): Number of results to return (default: 5)

Returns: Formatted search results with scores

Example:

{
  "query": "collaboration principles",
  "index_dir": "faiss_index",
  "top_k": 3
}

How to Run

# Start the MCP server
python3 mcp_vector_server.py

The server will start and wait for MCP client connections via stdio.

Server Architecture

┌─────────────────────────────────────┐
│       MCP Vector Server             │
│  (mcp_vector_server.py)             │
├─────────────────────────────────────┤
│                                     │
│  Tool 1: create_vector_db()         │
│  ├─ Load JSON knowledge base        │
│  ├─ Generate embeddings             │
│  ├─ Create FAISS index              │
│  └─ Save index files                │
│                                     │
│  Tool 2: search_vector_db()         │
│  ├─ Load FAISS index                │
│  ├─ Encode query                    │
│  ├─ Perform similarity search       │
│  └─ Return ranked results           │
│                                     │
└─────────────────────────────────────┘
         ↕ (MCP Protocol via stdio)
┌─────────────────────────────────────┐
│         MCP Client                  │
│    (client_vector.py or any         │
│     MCP-compatible client)          │
└─────────────────────────────────────┘

What You'll Learn

How to create an MCP server with FastMCP
Defining tools that clients can call
MCP protocol communication (stdio)
Error handling in server tools
Logging without breaking MCP protocol

File 4: MCP Client

File: client_vector.py

Overview

This is a test client for the MCP server. It demonstrates: - Connecting to an MCP server via stdio - Discovering available tools - Calling server tools with parameters - Handling responses

Key Components

MCPClient Class: Manages connection and communication
Connection Method: Establishes stdio connection to server
Tool Calling: Invokes server tools with arguments
Response Handling: Processes and displays results

How It Works

# 1. Create client and connect to server
client = MCPClient()
await client.connect_to_server("mcp_vector_server.py")

# 2. List available tools
tools = await client.session.list_tools()
print("Available tools:", [t.name for t in tools.tools])

# 3. Call a tool
response = await client.call_tool(
    "search_vector_db",
    query="quality principles",
    index_dir="faiss_index",
    top_k=2
)

# 4. Process response
print(response)

How to Run

# Run the client (it will start the server automatically)
python3 client_vector.py mcp_vector_server.py

Expected Output

🔌 Starting MCP client for server: mcp_vector_server.py
[DEBUG] Initializing MCP session...
✅ MCP Handshake Complete

🛠 Tools detected: ['create_vector_db', 'search_vector_db']

⚙ Calling tool 'search_vector_db' with: {'query': 'critical techworks quality', 'index_dir': '/Users/...', 'top_k': 1}

📌 RAW RESPONSE FROM SERVER:
1) score=0.8234
Critical TechWorks Quality (Quality, Reliability, and Resilience):
We ensure delivery of high-quality, reliable, and resilient software...

🔚 Client closed.

What You'll Learn

How to build an MCP client
Connecting to MCP servers via stdio
Tool discovery and invocation
Handling MCP responses
Async/await patterns in Python

Key Concepts

1. Model Context Protocol (MCP)

MCP is an open protocol that standardizes how AI applications communicate with external data sources and tools.

Key Features: - Tools: Functions that can be called by AI assistants - Resources: Data sources that can be read - Prompts: Reusable prompt templates - Stdio Communication: Uses standard input/output for communication

Why MCP? - Eliminates the need for custom integrations - Provides security through controlled access - Enables interoperability between different AI systems - Simplifies development of AI-powered applications

2. FastMCP

FastMCP is a Python library that simplifies MCP server creation.

Benefits: - Decorator-based tool definition - Automatic type validation - Built-in error handling - Easy to use and understand

Example:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("MyServer")

@mcp.tool()
def my_tool(param: str) -> str:
    return f"Processed: {param}"

mcp.run()

3. Vector Databases

Vector databases store and retrieve data based on semantic similarity rather than exact matches.

How They Work: 1. Embedding: Convert text to numerical vectors 2. Indexing: Store vectors in an efficient data structure 3. Querying: Find vectors similar to a query vector 4. Ranking: Return results sorted by similarity

Use Cases: - Semantic search - Recommendation systems - Document retrieval - Question answering

4. FAISS (Facebook AI Similarity Search)

FAISS is a library for efficient similarity search and clustering of dense vectors.

Key Features: - Fast: Optimized for large-scale search - Flexible: Supports various distance metrics - Scalable: Can handle billions of vectors - CPU & GPU: Works on both architectures

Index Types: - IndexFlatIP: Exact search with inner product (used in this project) - IndexFlatL2: Exact search with L2 distance - IndexIVFFlat: Approximate search with clustering - And many more...

5. Embeddings

Embeddings are dense vector representations of text that capture semantic meaning.

Properties: - Similar texts have similar embeddings - Dimensionality typically ranges from 128 to 1536 - Generated by neural networks trained on large text corpora

Model Used: all-MiniLM-L6-v2 - Dimensions: 384 - Size: ~120MB - Speed: Fast inference - Quality: Good for general-purpose tasks

6. Cosine Similarity

Cosine similarity measures the cosine of the angle between two vectors.

Formula: similarity = (A · B) / (||A|| × ||B||)

Range: -1 to 1 (for normalized vectors: 0 to 1) - 1 = Identical direction (very similar) - 0 = Orthogonal (unrelated) - -1 = Opposite direction (very dissimilar)

Why Cosine? - Invariant to vector magnitude - Works well for text embeddings - Efficient to compute

Troubleshooting

Issue: Module not found

Error: ModuleNotFoundError: No module named 'mcp'

Solution:

pip install -U mcp fastmcp

Issue: FAISS index not found

Error: ERROR: faiss.index missing

Solution:

# Generate the index first
python3 generate_vector_db.py

Issue: Dimension mismatch

Error: Dimension mismatch: query=384, index=768

Solution: Ensure you're using the same embedding model (all-MiniLM-L6-v2) for both indexing and searching. Delete the old index and regenerate:

rm -rf faiss_index/
python3 generate_vector_db.py

Issue: MCP server not responding

Symptoms: Client hangs or times out

Solutions: 1. Check if the server script path is correct 2. Ensure Python 3.8+ is being used 3. Check server logs in stderr 4. Verify all dependencies are installed

Issue: Permission denied

Error: PermissionError: [Errno 13] Permission denied

Solution:

# Make scripts executable
chmod +x generate_vector_db.py
chmod +x mcp_vector_server.py
chmod +x client_vector.py

Issue: Out of memory

Error: System runs out of RAM during embedding generation

Solutions: - Close other applications - Process texts in smaller batches - Use a smaller embedding model - Increase system swap space

📦 Manual Installation (Optional)

Note: This section is for users who prefer not to use Docker. If you're using Docker (recommended), you can skip this section.

1. Create Virtual Environment

# Navigate to the project directory
# (Replace with the path where you extracted the MCP.zip file)
cd /path/to/MCP

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

2. Install Python Dependencies

# Install required packages
pip install -U sentence-transformers faiss-cpu numpy mcp fastmcp

3. Verify Installation

# Check if packages are installed
python3 -c "import faiss; import sentence_transformers; import mcp; print('✅ All packages installed successfully!')"

4. Running Without Docker

After installing dependencies, you can run the scripts directly:

# Generate vector database
python3 generate_vector_db.py

# Run the MCP client
python3 client_vector.py mcp_vector_server.py

Advanced Usage

Custom Knowledge Base

Create your own knowledge base by modifying knowledge_base.json:

{
  "Texts": [
    "Your first knowledge chunk here...",
    "Your second knowledge chunk here...",
    "Add as many as you need..."
  ]
}

Then regenerate the index:

python3 generate_vector_db.py

Using Different Embedding Models

Modify the EMBED_MODEL constant in the scripts:

# Smaller, faster model
EMBED_MODEL = "all-MiniLM-L6-v2"  # 384 dims, ~120MB

# Larger, more accurate model
EMBED_MODEL = "all-mpnet-base-v2"  # 768 dims, ~420MB

# Multilingual model
EMBED_MODEL = "paraphrase-multilingual-MiniLM-L12-v2"  # 384 dims

Important: Use the same model for both indexing and searching!

Integrating with Claude Desktop

Add the MCP server to Claude Desktop's configuration:

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

{
  "mcpServers": {
    "vector-db": {
      "command": "python3",
      "args": ["/absolute/path/to/mcp_vector_server.py"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/project"
      }
    }
  }
}

Restart Claude Desktop, and the tools will be available!

Scaling to Larger Datasets

For larger knowledge bases (10,000+ documents):

Use Approximate Search:

# Instead of IndexFlatIP
quantizer = faiss.IndexFlatIP(dim)
index = faiss.IndexIVFFlat(quantizer, dim, nlist=100)
index.train(embeddings)
index.add(embeddings)

Batch Processing:

# Process embeddings in batches
batch_size = 1000
for i in range(0, len(texts), batch_size):
    batch = texts[i:i+batch_size]
    batch_embeddings = model.encode(batch)
    index.add(batch_embeddings)

Use GPU (if available):

pip install faiss-gpu

Testing the System

Test 1: Create Vector Database

python3 generate_vector_db.py

Expected: Index files created in faiss_index/ directory

Test 2: Search Standalone

from search_vector_db import search_in_faiss

# Test different queries
queries = [
    "What are the collaboration principles?",
    "Tell me about quality",
    "How do we ensure visibility?"
]

for query in queries:
    print(f"\n{'='*60}")
    print(search_in_faiss(query, top_k=1))

Test 3: MCP Server + Client

python3 client_vector.py mcp_vector_server.py

Expected: Client connects, discovers tools, executes search, displays results

Next Steps

After completing this workshop, you can:

Extend the MCP Server: Add more tools (e.g., update index, delete entries)
Build a Web Interface: Create a Flask/FastAPI frontend for the vector DB
Integrate with AI Assistants: Connect to Claude, ChatGPT, or custom LLMs
Scale Up: Use cloud vector databases (Pinecone, Weaviate, Qdrant)
Add Authentication: Implement access control for the MCP server
Monitor Performance: Add metrics and logging for production use

Additional Resources

Happy Learning! 🚀

← Back to Hands-on Workshops

📦 Download Workshop Files

MCP Vector Database Server — Hands-On Workshop

Introduction

What is MCP?

Project Overview

Table of Contents

Step 1: Install Docker 🐳

Check if Docker is Already Installed

Installing Docker

🍎 macOS

🪟 Windows

🐧 Linux

Verify Docker is Running

Step 2: Run the Project with Docker 🚀

1. Extract Workshop Files

2. Build and Run with Docker

Option 1: Using the Helper Script (Easiest)

Option 2: Using Docker Compose Directly

Option 3: Using Docker Commands

Helper Script Commands

Complete Docker Workflow

Docker Architecture

Docker Troubleshooting

Issue: Container not running

Issue: "version is obsolete" warning

Issue: Port already in use

Issue: FAISS index not found

Issue: Permission denied

Why Use Docker?

Useful Docker Commands

Step 3: Understanding the Project 📚

What Does This Project Do?

How It Works

Typical Workflow

Project Structure

File Descriptions

💻 Code Explanation

File 1: Generate Vector Database

Overview

Key Components

How It Works

How to Run

Expected Output

Generated Files

What You'll Learn

File 2: Search Vector Database

Overview

Key Components

How It Works

How to Run

Expected Output

What You'll Learn

File 3: MCP Vector Server

Overview

Key Components

MCP Tools Exposed

Tool 1: create_vector_db

Tool 2: search_vector_db

How to Run

Server Architecture

What You'll Learn

File 4: MCP Client

Overview

Key Components

How It Works

How to Run

Expected Output

What You'll Learn

Key Concepts

1. Model Context Protocol (MCP)

2. FastMCP

3. Vector Databases

4. FAISS (Facebook AI Similarity Search)

5. Embeddings

6. Cosine Similarity

Troubleshooting

Issue: Module not found

Issue: FAISS index not found

Issue: Dimension mismatch

Issue: MCP server not responding

Tool 1: `create_vector_db`

Tool 2: `search_vector_db`