Personal Knowledge-Base MCP Server

Personal Knowledge-Base MCP Server, обеспечивающий семантический поиск по коллекции документов, принадлежащей студенту, с использованием Model Context Protocol (MCP), эмбеддингов Gemini и Qdrant.

Обзор проекта

Этот проект предоставляет личную базу знаний в виде вызываемых инструментов MCP.

Вместо поиска по ключевым словам система преобразует запросы пользователей в векторные эмбеддинги и извлекает семантически релевантные фрагменты документов из Qdrant.

Related MCP server: Solarium

Архитектура

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

Перечисляет все индексированные исходные документы.

Пример вывода:

1. Complex_Variables_Project_Report.pdf

Структура проекта

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

Настройка

1. Создайте и активируйте виртуальное окружение

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

2. Установите зависимости

pip install -r requirements.txt

3. Настройте API-ключ Gemini

Создайте файл .env в корне проекта:

GEMINI_API_KEY=your_api_key_here

Никогда не коммитьте .env в Git.

4. Запустите Qdrant

Проект использует локальный Qdrant по адресу:

http://localhost:6333

Пример команды Docker:

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

Загрузка документов

Поместите PDF внутрь:

documents/

Запустите:

python ingest.py

Конвейер загрузки выполняет:

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

Каждый сохранённый фрагмент содержит:

text
page
source

Запуск MCP-сервера

Запустите MCP Inspector:

mcp dev server.py

MCP-сервер использует транспорт STDIO.

Доступные инструменты:

search_notes
get_document
list_source_documents

Оценка поиска

Небольшой оценочный набор из пяти запросов использовался для проверки того, появилась ли хотя бы одна ожидаемая релевантная страница среди первых трёх полученных результатов.

Результат оценки:

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

Примеры оценочных запросов:

• Что такое комплексная переменная?

• Что такое уравнения Коши-Римана?

• Как преобразование Лапласа помогает инженерным системам?

• В чём разница между преобразованиями Лапласа и Фурье?

• Как БПФ используется для подавления шума в аудио?

Фильтрация по уверенности

Инструмент поиска использует начальный порог сходства:

0.60

Например, релевантные запросы давали оценки около:

0.79
0.76
0.75

в то время как несвязанный запрос давал оценки около:

0.52

Поэтому результаты с низкими оценками отфильтровываются, и инструмент возвращает:

No confident match found.

Технологии

• Python

• FastMCP

• Model Context Protocol (MCP)

• Google Gemini Embeddings

• Qdrant

• PyMuPDF

• LangChain Text Splitters

• Docker

• MCP Inspector

Текущий источник знаний

Текущий демонстрационный корпус:

Complex_Variables_Project_Report.pdf

Документ содержит 7 страниц и был разбит на 30 фрагментов для индексированной коллекции personal_knowledge.

Безопасность

• API-ключи хранятся в .env

• .env исключён с помощью .gitignore

• Секреты никогда не должны попадать в систему контроля версий

Будущие улучшения

• Поддерживать документы Markdown и TXT

• Добавить постоянные идентификаторы на уровне документов

• Улучшить обработку дублирующихся фрагментов

• Расширить набор оценочных данных

• Добавить больше метрик поиска

• Поддерживать несколько коллекций документов

• Добавить опциональное развертывание Qdrant Cloud