Servidor MCP de base de conocimiento personal

Un servidor MCP de base de conocimiento personal que proporciona búsqueda semántica sobre una colección de documentos propiedad de un estudiante utilizando el Model Context Protocol (MCP), embeddings de Gemini y Qdrant.

Descripción general del proyecto

Este proyecto expone una base de conocimiento personal como herramientas MCP invocables.

En lugar de depender de la coincidencia de palabras clave, el sistema convierte las consultas del usuario en embeddings vectoriales y recupera fragmentos de documentos semánticamente relevantes desde Qdrant.

Related MCP server: genai-lab

Arquitectura

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

Enumera todos los documentos fuente indexados.

Ejemplo de salida:

1. Complex_Variables_Project_Report.pdf

Estructura del proyecto

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

Configuración

1. Crear y activar el entorno virtual

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

2. Instalar dependencias

pip install -r requirements.txt

3. Configurar la clave de API de Gemini

Crea un archivo .env en la raíz del proyecto:

GEMINI_API_KEY=your_api_key_here

Nunca hagas commit de .env a Git.

4. Iniciar Qdrant

El proyecto utiliza Qdrant local en:

http://localhost:6333

Ejemplo de comando Docker:

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

Ingestión de documentos

Coloca el PDF dentro de:

documents/

Ejecuta:

python ingest.py

El pipeline de ingestión realiza lo siguiente:

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

Cada fragmento almacenado contiene:

text
page
source

Ejecución del servidor MCP

Inicia el MCP Inspector:

mcp dev server.py

El servidor MCP utiliza transporte STDIO.

Herramientas disponibles:

search_notes
get_document
list_source_documents

Evaluación de la recuperación

Se utilizó un pequeño conjunto de evaluación de cinco consultas para comprobar si al menos una página relevante esperada aparecía entre los tres primeros resultados recuperados.

Resultado de la evaluación:

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

Las consultas de evaluación de ejemplo incluían:

• ¿Qué es una variable compleja?

• ¿Cuáles son las ecuaciones de Cauchy-Riemann?

• ¿Cómo ayuda la transformada de Laplace a los sistemas de ingeniería?

• ¿Cuál es la diferencia entre las transformadas de Laplace y Fourier?

• ¿Cómo se utiliza la FFT para la reducción de ruido en audio?

Filtrado de confianza

La herramienta de búsqueda utiliza un umbral de similitud inicial de:

0.60

Por ejemplo, las consultas relevantes produjeron puntuaciones alrededor de:

0.79
0.76
0.75

mientras que una consulta no relacionada produjo puntuaciones alrededor de:

0.52

Por lo tanto, los resultados con puntuaciones bajas se filtran y la herramienta devuelve:

No confident match found.

Tecnologías

• Python

• FastMCP

• Model Context Protocol (MCP)

• Google Gemini Embeddings

• Qdrant

• PyMuPDF

• LangChain Text Splitters

• Docker

• MCP Inspector

Fuente de conocimiento actual

El corpus de demostración actual es:

Complex_Variables_Project_Report.pdf

El documento contiene 7 páginas y se dividió en 30 fragmentos para la colección indexada personal_knowledge.

Seguridad

• Las claves de API se almacenan en .env

• .env está excluido mediante .gitignore

• Los secretos nunca deben incluirse en el control de versiones

Mejoras futuras

• Soporte para documentos Markdown y TXT

• Añadir identificadores persistentes a nivel de documento

• Mejorar el manejo de fragmentos duplicados

• Ampliar el conjunto de datos de evaluación

• Añadir más métricas de recuperación

• Soporte para múltiples colecciones de documentos

• Añadir despliegue opcional en Qdrant Cloud