Vector Knowledge Base MCP Server

A high-performance FastAPI/FastMCP-based Model Context Protocol (MCP) server that provides vector-based knowledge management with document storage, similarity search, and intelligent retrieval capabilities.

---

📖 Table of Contents

• Vector Knowledge Base MCP Server
  • 📖 Table of Contents
  • 🚀 Features
  • 🏗️ Architecture
  • 🛠️ Tech Stack
  • 📋 Prerequisites
  • 🚀 Quick Start
    • Environment Variables
    • Development Setup
    • Production Setup
    • Service Ports (dev)
  • 🔑 Authentication and API Keys
    • Using the Admin API Key
    • Using the API Key
    • Summary Table
  • 📖 API Documentation
  • 📁 Project Structure
  • 🚨 Troubleshooting
    • Health Checks
  • 🤝 Contributing
    • Development Guidelines
  • 📄 License
  • 🆘 Support

---

🚀 Features

• FastAPI Backend: High-performance async API server
• Vector Database: ChromaDB integration for semantic search
• Document Storage: MinIO object storage for file management
• PostgreSQL Database: Structured data storage and metadata
• MCP Protocol: Model Context Protocol server implementation using FastMCP
• Admin Interface: PgAdmin for database management (development only)
• Development Ready: Hot-reload and development tools included

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   FastAPI App   │────│   ChromaDB      │────│   PostgreSQL    │
│   (Port 8100)   │    │   (Port 8101)   │    │   (Port 5432)   │
│─────────────────│    └─────────────────┘    └─────────────────┘
│   FastMCP App   │
│ (Port 8100/mcp) │
└─────────────────┘
         │
         │
┌─────────────────┐    ┌─────────────────┐
│     MinIO       │    │    PgAdmin      │
│ (Ports 9100/01) │    │   (Port 5550)   │
└─────────────────┘    └─────────────────┘

All port described in above schema are for development

🛠️ Tech Stack

• Backend: FastAPI with Python 3.11+
• Vector Database: ChromaDB for embeddings and similarity search
• Database: PostgreSQL 12 with Alpine Linux
• Object Storage: MinIO for file storage
• Containerization: Docker & Docker Compose
• MCP Protocol: FastMCP for model context protocol implementation

📋 Prerequisites

• Docker and Docker Compose
• Python 3.11+ (for local development)
• Git

🚀 Quick Start

Environment Variables

Before running the application, create a .env file based on .env.example:

cp .env.example .env

Fill in the variables according to your environment:

APP_ENV=dev
APP_PORT=8100

DATABASE_URL=postgresql://akvo:password@db:5432/kb_mcp

# MinIO settings
MINIO_ENDPOINT=minio:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET_NAME=documents

# Chroma DB settings
CHROMA_DB_HOST=chromadb
CHROMA_DB_PORT=8000
VECTOR_STORE_BATCH_SIZE=100

# OpenAI settings
OPENAI_API_KEY=your-openai-api-key-here
OPENAI_API_BASE=https://api.openai.com/v1
OPENAI_MODEL=gpt-4
OPENAI_EMBEDDINGS_MODEL=text-embedding-ada-002

# Admin Auth
ADMIN_API_KEY=your-admin-api-key-here

Notes

• APP_ENV accepts two values: prod or dev.
• This variable controls the startup command in entrypoint.sh, determining whether the application runs in reload mode (dev) or in production mode (prod).
• VECTOR_STORE_BATCH_SIZE controls how many documents are processed in a single batch when adding to the vector store. There is a trade off between performance and hitting limits on the number of chunks that can be stored at once default is 100 but you can tune this setting here.
• ADMIN_API_KEY currently used for authentication to access the CRUD API keys endpoint. With this, the script can create an API key that will be used as the authentication token to access the CRUD Knowledge Base.
  • 👉 How to generate ADMIN_API_KEY

Development Setup

1. Clone the repository

   git clone [email protected]:akvo/vector-knowledge-base-mcp-server.git
   cd vector-knowledge-base-mcp-server

2. Set up environment variables

   cp .env.example .env
   # Edit .env with your configurations

3. Start the development environment

   ./dev.sh up -d

4. Verify services are running

   docker compose ps

5. Running pytest

   • Running FastAPI endpoint test

   ./dev.sh exec main ./test.sh api

   • Running e2e test

   ./dev.sh exec main ./test.sh e2e

   • Running FastMCP test

   ./dev.sh exec main ./test.sh mcp

   • Running All test

   ./dev.sh exec main ./test.sh all

Production Setup

1. Build and start production services

   docker compose -f docker-compose.yml up -d

Service Ports (dev)

Service	Development	Production	Description
FastAPI	8100	8000	Main application API
ChromaDB	8101	8001	Vector database
PostgreSQL	5432	5432	Primary database
MinIO API	9100	9000	Object storage API
MinIO Console	9101	9001	MinIO web interface
PgAdmin	5550	-	Database admin (dev only)

🔑 Authentication and API Keys

This project uses API keys for authentication to access the Knowledge Base and Admin APIs. There are two types of keys:

1. Admin API Key (ADMIN_API_KEY) – Used for administrative actions, such as creating or revoking other API keys.
2. API Key – Generated via the Admin API to access the Knowledge Base endpoints.

Using the Admin API Key

• Your ADMIN_API_KEY is defined in your .env file.
• To perform administrative tasks, include it in the Authorization header:

Authorization: Admin-API-Key <your_admin_api_key>

Example: Create a new API key via Admin endpoint

curl -X POST http://localhost:8100/api/v1/api-key \
  -H "Authorization: Admin-Key sk_xxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "app-name", "is_active": true}'

Using the API Key

• The generated API key is used to access protected Knowledge Base endpoints.
• Include it in the Authorization header:

Authorization: API-Key <your_api_key>

Example: Query the Knowledge Base

curl -X GET http://localhost:8100/api/v1/knowledge-base \
  -H "Authorization: API-Key sk_xxxxxxx"

👉 For the detail of API-Key usage, please read: SECURITY.md

Summary Table

Key Type	Header Name	Purpose
Admin API Key	Authorization: Admin-Key <key>	Manage API keys and administrative tasks
User/API Key	Authorization: API-Key <key>	Access Knowledge Base and perform CRUD ops

📖 API Documentation

Once the application is running (uvicorn app.main:app --reload or via Docker), the API documentation is automatically available through FastAPI docs:

• Swagger UI → http://localhost:8000/api/docs or http://localhost:8100/api/docs
• ReDoc → http://localhost:8000/redoc or http://localhost:8100/redoc

From these interfaces, you can:

• Try out endpoints directly
• View request and response schemas
• Test the API interactively

📁 Project Structure

vector-knowledge-base-mcp-server/
├── main/                          # FastAPI application
│   ├── app/
│   │   ├── api/                   # API routes (endpoint FastAPI)
│   │   ├── core/                  # Core configuration (settings, logging, security)
│   │   ├── mcp/                   # MCP related files (FastMCP server, tools)
│   │   ├── models/                # Pydantic models / ORM models
│   │   ├── schemas/               # API schemas (Pydantic / base)
│   │   ├── services/              # Business logic / service layer
│   │   ├── utils/                 # Helpers / utilities
│   ├── tests/                     # Unit / integration tests
│   ├── Dockerfile
│   └── requirements.txt
├── db/
│   ├── docker-entrypoint-initdb.d/ # Init SQL scripts
│   └── script/                    # Migration / seed
├── pgadmin4/
│   └── servers.json               # GUI config
├── docker-compose.yml             # Compose prod
├── docker-compose.override.yml    # Override dev
├── .env.example                   # Env vars
└── README.md

🚨 Troubleshooting

Health Checks

# Check all services
curl http://localhost:8100/health

# Check individual components
curl http://localhost:8101/api/v2/heartbeat  # ChromaDB
curl http://localhost:9100/minio/health/live # MinIO

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow PEP 8 style guide
• Add tests for new features
• Update documentation for API changes
• Use conventional commits for commit messages

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Issues: Open an issue on GitHub
• Documentation: Check the /docs endpoint when server is running
• Community: Join our discussions in GitHub Discussions

---

Built with ❤️ using FastAPI and FastMCP