Personal Knowledge-Base MCP Server

Ein Personal Knowledge-Base MCP Server, der semantische Suche über eine studenteneigene Dokumentsammlung unter Verwendung von Model Context Protocol (MCP), Gemini-Embeddings und Qdrant bietet.

Projektübersicht

Dieses Projekt stellt eine persönliche Wissensdatenbank als aufrufbare MCP-Tools bereit.

Anstatt auf Schlüsselwortabgleich zu setzen, konvertiert das System Benutzeranfragen in Vektor-Embeddings und ruft semantisch relevante Dokumentabschnitte aus Qdrant ab.

Related MCP server: genai-lab

Architektur

User / MCP Client
       |
       v
MCP Server (FastMCP)
       |
       +----------------------+
       |                      |
       v                      v
 search_notes()        get_document()
       |
       v
Gemini Embedding API
       |
       v
Qdrant Vector Database
       |
       v
Ranked Chunks
       |
       v
Source + Page + Score + Text
## Features

* PDF document ingestion
* Page-by-page text extraction
* Recursive text chunking
* Gemini `gemini-embedding-001` embeddings
* Qdrant vector storage
* Semantic similarity search
* Source and page citations
* Confidence threshold for low-relevance queries
* Full-document retrieval
* Indexed-source listing
* MCP Inspector support

## MCP Tools

### `search_notes`

Searches the knowledge base using semantic similarity.

Arguments:

* `query`: search question or topic
* `top_k`: maximum number of results

Returns:

* similarity score
* source filename
* page number
* relevant text chunk

### `get_document`

Returns the complete text of an indexed PDF document.

Argument:

* `doc_id`: document filename

Example:

```text
Complex_Variables_Project_Report.pdf

list_source_documents

Listet alle indizierten Quelldokumente auf.

Beispielausgabe:

1. Complex_Variables_Project_Report.pdf

Projektstruktur

Personal-Knowledge-MCP/
├── documents/
│   └── Complex_Variables_Project_Report.pdf
├── services/
│   ├── chunking.py
│   ├── embedding.py
│   ├── pdf_reader.py
│   └── qdrant_service.py
├── .env
├── .gitignore
├── evaluation.py
├── ingest.py
├── requirements.txt
└── server.py

Einrichtung

1. Virtuelle Umgebung erstellen und aktivieren

python -m venv .venv
.venv\Scripts\Activate.ps1

2. Abhängigkeiten installieren

pip install -r requirements.txt

3. Gemini-API-Schlüssel konfigurieren

Erstelle eine .env-Datei im Projektstammverzeichnis:

GEMINI_API_KEY=your_api_key_here

.env darf niemals in Git committet werden.

4. Qdrant starten

Das Projekt verwendet lokales Qdrant unter:

http://localhost:6333

Beispiel-Docker-Befehl:

docker run -d --name qdrant -p 6333:6333 -p 6334:6334 qdrant/qdrant

Dokumentenaufnahme

Lege das PDF in den folgenden Ordner:

documents/

Führe aus:

python ingest.py

Die Aufnahmepipeline führt Folgendes aus:

PDF
 ↓
Page extraction
 ↓
Chunking
 ↓
Gemini embeddings
 ↓
Qdrant storage

Jeder gespeicherte Abschnitt enthält:

text
page
source

Den MCP-Server ausführen

Starte den MCP Inspector:

mcp dev server.py

Der MCP-Server verwendet STDIO-Transport.

Verfügbare Tools:

search_notes
get_document
list_source_documents

Retrieval-Bewertung

Ein kleiner Evaluierungssatz von fünf Abfragen wurde verwendet, um zu prüfen, ob mindestens eine erwartete relevante Seite unter den drei besten abgerufenen Ergebnissen erschien.

Evaluierungsergebnis:

Tests: 5
Successful hits: 5
Hit@3: 100%

Beispiel-Evaluierungsabfragen waren:

• Was ist eine komplexe Variable?

• Was sind die Cauchy-Riemann-Gleichungen?

• Wie hilft die Laplace-Transformation bei technischen Systemen?

• Was ist der Unterschied zwischen Laplace- und Fourier-Transformationen?

• Wie wird FFT zur Rauschunterdrückung bei Audio verwendet?

Konfidenzfilterung

Das Suchwerkzeug verwendet einen anfänglichen Ähnlichkeitsschwellenwert von:

0.60

Beispielsweise erzeugten relevante Abfragen Werte um:

0.79
0.76
0.75

während eine nicht verwandte Abfrage Werte um:

0.52

Daher werden Ergebnisse mit niedriger Punktzahl herausgefiltert und das Tool gibt Folgendes zurück:

No confident match found.

Technologien

• Python

• FastMCP

• Model Context Protocol (MCP)

• Google Gemini Embeddings

• Qdrant

• PyMuPDF

• LangChain Text Splitters

• Docker

• MCP Inspector

Aktuelle Wissensquelle

Das aktuelle Demonstrationskorpus ist:

Complex_Variables_Project_Report.pdf

Das Dokument enthält 7 Seiten und wurde in 30 Abschnitte für die indizierte Sammlung personal_knowledge aufgeteilt.

Sicherheit

• API-Schlüssel werden in .env gespeichert

• .env wird über .gitignore ausgeschlossen

• Geheimnisse sollten niemals in die Versionskontrolle committet werden

Zukünftige Verbesserungen

• Unterstützung für Markdown- und TXT-Dokumente

• Hinzufügen persistenter IDs auf Dokumentebene

• Verbesserung der Behandlung doppelter Abschnitte

• Erweitern des Evaluierungsdatensatzes

• Hinzufügen weiterer Retrieval-Metriken

• Unterstützung mehrerer Dokumentsammlungen

• Hinzufügen optionaler Qdrant-Cloud-Bereitstellung