Personal Knowledge-Base MCP Server

Готовый к показу рекрутерам MCP-сервер, предоставляющий семантический поиск по реальному личному корпусу документов.

Проблема

Поиск по ключевым словам упускает семантически связанную информацию, если формулировки отличаются. Этот проект индексирует личные заметки с помощью эмбеддингов и предоставляет переиспользуемые инструменты поиска через Model Context Protocol.

Related MCP server: research-mcp

Что входит

• Сервер FastMCP с 3 вызываемыми инструментами:

  • search_notes(user_id, query, top_k) — ранжированные фрагменты + ссылки на источники

  • get_document(user_id, doc_id) — полный контекст проиндексированного документа

  • list_sources(user_id) — проиндексированные источники

• Импорт PDF/Markdown/TXT и чанкинг с учётом перекрытий

• Эмбеддинги sentence-transformers/all-MiniLM-L6-v2

• Векторное хранилище Qdrant с коллекциями для каждого пользователя

• Порог сходства с явным результатом no_confident_match

• Многопользовательское веб-демо на FastAPI с регистрацией/входом, загрузкой и поиском

• Скрипт оценки поиска на вручную размеченных данных

Архитектура

См. architecture.md.

Быстрый старт

1. Установка

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

2. Настройка Qdrant Cloud

Создайте бесплатный кластер Qdrant Cloud, скопируйте его URL/API-ключ и создайте .env из .env.example.

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

3. Добавьте свой реальный корпус

Положите 2–5 своих конспектов за семестр в corpus/, затем:

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

4. Запустите веб-демо

uvicorn api:app --reload

Откройте http://127.0.0.1:8000.

5. Запустите MCP-сервер

python server.py

Для Claude Desktop добавьте команду сервера в конфигурацию MCP, указав абсолютный путь к server.py и тот же интерпретатор Python из вашего виртуального окружения.

Пример структуры:

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

Качество поиска

Создайте небольшой вручную размеченный набор в evaluation_queries.json, где каждый запрос сопоставлен с правильным doc_id, затем выполните:

python evaluate.py --user demo

Укажите фактически измеренное Precision@k в финальном README. Не выдумывайте цифру.

Демо

См. demo_script.md — сценарий 5-минутной живой демонстрации.

Технический стек

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

Почему это полезно

Слой MCP работает на уровне протокола: ту же функцию поиска может вызывать Claude Desktop или другой MCP-совместимый клиент, а не только кастомный интерфейс чат-бота.

Ограничения

Это учебная/демонстрационная реализация. Аутентификация намеренно базовая; в продакшен-деплойментах стоит добавить защищённые сессии, хеширование паролей, middleware авторизации, лимиты запросов, шифрованное хранилище и более строгую изоляцию арендаторов.