Personal Knowledge-Base MCP Server

Un servidor MCP orientado a reclutadores que expone búsqueda semántica sobre un corpus documental real y de propiedad personal.

Problema

La búsqueda por palabras clave no encuentra información semánticamente relacionada cuando la redacción difiere. Este proyecto indexa notas personales con embeddings y expone herramientas de recuperación reutilizables a través del Model Context Protocol.

Related MCP server: Personal Knowledge-Base MCP Server

Qué incluye

• Servidor FastMCP con 3 herramientas invocables:

  • search_notes(user_id, query, top_k) — fragmentos ordenados por relevancia + citas de la fuente

  • get_document(user_id, doc_id) — contexto completo del documento indexado

  • list_sources(user_id) — fuentes indexadas

• Ingesta de PDF/Markdown/TXT y fragmentación en bloques con solapamiento

• Embeddings de sentence-transformers/all-MiniLM-L6-v2

• Almacenamiento vectorial con Qdrant y colecciones por usuario

• Umbral de similitud con no_confident_match explícito

• Demo web de FastAPI multiusuario con registro/inicio de sesión, subida y búsqueda

• Script de recuperación de evaluación con etiquetado manual

Arquitectura

Consulta architecture.md.

Inicio rápido

1. Instalar

python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate
pip install -r requirements.txt

2. Configurar Qdrant Cloud

Crea un clúster gratuito de Qdrant Cloud, copia su URL y su clave de API, y crea .env a partir de .env.example.

QDRANT_URL=https://YOUR-CLUSTER.qdrant.io
QDRANT_API_KEY=YOUR_KEY

3. Añadir tu corpus real

Coloca 2–5 de tus apuntes del semestre en corpus/ y luego:

python ingest.py --user demo --path corpus

4. Ejecutar la demo web

uvicorn api:app --reload

Abre http://127.0.0.1:8000.

5. Ejecutar el servidor MCP

python server.py

Para Claude Desktop, añade el comando del servidor a la configuración de MCP usando la ruta absoluta a server.py y el mismo intérprete de Python de tu entorno virtual.

Ejemplo orientativo:

{
  "mcpServers": {
    "personal-knowledge-base": {
      "command": "C:\\PATH\\TO\\.venv\\Scripts\\python.exe",
      "args": ["C:\\PATH\\TO\\personal-knowledge-base-mcp\\server.py"]
    }
  }
}

Calidad de la recuperación

Crea un pequeño conjunto etiquetado a mano en evaluation_queries.json, con cada consulta que o mapeada al doc_id correcto, y ejecuta:

python evaluate.py --user demo

Informa la Precision\@k realmente medida en tu README final. No inventes el número.

Demo

Consulta demo_script.md para obtener una secuencia de demo en vivo de 5 minutos.

Stack tecnologico

Python · FastMCP · Qdrant Cloud · Sentence Transformers · FastAPI · SQLite · PDF/Markdown/TXT

Por qué esto es útil

La capa MCP es a nivel de protocolo: la misma capacidad de recuperación puede ser invocada por Claude Desktop u otro cliente compatible con MCP, en lugar de quedar encerrada en una interfaz de chatbot personalizada.

Limitaciones

Esta es una implementación de fellowship/demo. La autenticación es básica a propósito; los despliegues de producción deberían añadir sesiones seguras, hash de contraseñas, middleware de autorización, límites de peticiones, almacenamiento cifrado y un aislamiento de inquilinos más sólido.