MCP RAG Service
MCP сервис для интеграции с Python RAG Server (DuckDB VSS) v2.0
Улучшенный MCP сервис для работы с продвинутыми методами векторного поиска, основанный на принципе KISS (Keep It Simple, Stupid).
🚀 Возможности
Основные функции:
rag_upload_file- Загрузка файлов в RAG серверrag_search- Продвинутый поиск по документам (гибридный, семантический, ключевой) с переранжированием и расширением запроса.rag_get_file_content- Получение полного содержимого файла из базы данных.rag_similar_documents- Поиск похожих документовrag_analyze_collection- Анализ коллекции (кластеры, выбросы, центральность)rag_get_collection_stats- Получение быстрой статистики по RAG коллекции.rag_query_direct- Прямые SQL запросы к DuckDB VSS
Поддерживаемые форматы файлов:
- Текстовые:
.txt,.md - Документы:
.pdf - Программный код:
.py,.js,.java,.c,.cpp - Конфигурационные:
.json,.yaml,.yml,.ini,.toml
📋 Требования
- Python 3.8+
- Работающий Python RAG Server с DuckDB VSS
- MCP совместимый клиент (например, Claude Desktop)
🛠️ Установка и запуск
# Клонирование репозитория
cd mcp-rag-service
# Установка в режиме разработки
pip install -e .
# Или с dev зависимостями
pip install -e ".[dev]"
Запуск через Docker (Рекомендуется)
- Сборка Docker образа:
docker build -t mcp-rag-service:latest .
- Запуск контейнера:
docker run --rm -it \
--network="host" \
-v "/path/to/your/rag-server/data:/data" \
mcp-rag-service:latest
Контейнеру нужен доступ к RAG серверу (по умолчанию http://localhost:8000) и к файлу базы данных rag.duckdb.
--network="host": Позволяет контейнеру обращаться к localhost хост-машины.-v "/path/to/your/rag-server/data:/data": Монтирует папку с rag.duckdb внутрь контейнера.
Настройка MCP клиента (например, Cursor или Claude Desktop)
Добавьте в конфигурационный файл вашего клиента:
{
"mcpServers": {
"rag-vector-service": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--network=host",
"-v", "/path/to/your/rag-server/data:/data",
"mcp-rag-service:latest"
],
"env": {
"RAG_SERVER_URL": "http://localhost:8000"
}
}
}
}
Замените /path/to/your/rag-server/data на реальный путь к папке data вашего основного RAG сервера.
Убедитесь, что основной RAG сервер запущен:
cd /path/to/your/python-rag-server
docker run -p 8000:8000 -v "$(pwd)/data:/app/data" ...
📖 Использование
Загрузка файла
# Загрузка документа
await mcp_client.call_tool(
"rag_upload_file",
{"file_path": "/path/to/document.pdf"}
)
Продвинутый поиск
# Гибридный поиск с переранжированием
await mcp_client.call_tool(
"rag_search",
{
"query": "машинное обучение и нейронные сети",
"top_k": 5,
"search_type": "hybrid",
"use_reranker": true,
"expand_query": false
}
)
Анализ коллекции
# Поиск похожих документов
await mcp_client.call_tool(
"rag_similar_documents",
{
"reference_file": "main.py",
"top_k": 3
}
)
# Анализ кластеров
await mcp_client.call_tool(
"rag_analyze_collection",
{
"analysis_type": "clusters",
"top_k": 10
}
)
Получение статистики
# Получить общую статистику по базе данных
await mcp_client.call_tool(
"rag_get_collection_stats",
{}
)
Прямой SQL запрос
# Для продвинутых пользователей
await mcp_client.call_tool(
"rag_query_direct",
{
"sql_query": "SELECT file_name, COUNT(*) FROM chunks GROUP BY file_name"
}
)
🔒 Безопасность
- ✅ Валидация путей к файлам
- ✅ Whitelist разрешенных расширений файлов
- ✅ SQL injection защита для прямых запросов
- ✅ Ограничение на команды только для чтения (SELECT, WITH, SHOW, etc.)
- ✅ Санитизация имен файлов
- ✅ Контейнеризация через Docker для простоты развертывания.
🏗️ Архитектура
mcp-rag-service/
├── Dockerfile # Docker-файл для сборки сервиса
├── src/ # Исходный код
│ ├── rag_mcp_server.py # Главный MCP сервер
│ ├── rag_client.py # HTTP клиент для RAG сервера
│ ├── vector_operations.py # Векторные операции и аналитика
│ └── utils.py # Утилиты и валидация
├── examples/ # Примеры использования
│ ├── upload_example.py # Загрузка файлов
│ ├── search_example.py # Семантический поиск
│ └── analysis_example.py # Анализ коллекции
└── pyproject.toml # Конфигурация проекта
🧠 Векторная аналитика
Основные типы анализа:
Кластеризация: Поиск самых похожих пар документов для понимания тематических групп.
Поиск выбросов: Выявление уникального контента, который отличается от основной коллекции.
Анализ центральности: Определение "центральных" документов, которые связаны с большинством других.
Матрица similarity: Анализ связей между файлами для понимания структуры коллекции.
🚦 Статус проекта
- ✅ Основные MCP функции реализованы
- ✅ Интеграция с DuckDB VSS
- ✅ Безопасность и валидация
- ✅ Векторная аналитика
- ✅ Продвинутые методы поиска
- ⏳ REST API интеграция (улучшение)
- ⏳ Тесты
- ⏳ Продвинутая обработка ошибок
📄 Лицензия
MIT License
Metadata
Release files for iflow-mcp_niksh06-rag-duckdb-with-mcp 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_niksh06_rag_duckdb_with_mcp-1.0.0.tar.gz | 22.3 kB | Without provenance | Details for iflow_mcp_niksh06_rag_duckdb_with_mcp-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_niksh06_rag_duckdb_with_mcp-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_niksh06_rag_duckdb_with_mcp-1.0.0-py3-none-any.whl |
Total release size: 40.9 kB
Release files / iflow_mcp_niksh06_rag_duckdb_with_mcp-1.0.0.tar.gz
| Download URL | iflow_mcp_niksh06_rag_duckdb_with_mcp-1.0.0.tar.gz |
|---|---|
| Size | 22.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
142fb54a9d9e1e4b7413a7a2d7ea91d3fbd55ff30f08837033799e97e548c352
|
|
BLAKE2b-256 checksum How to use checksums |
018954b0c01b83dc7dfbedb48770d908f478ba191ce69360a04f72df8872c856
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_niksh06_rag_duckdb_with_mcp-1.0.0-py3-none-any.whl
| Download URL | iflow_mcp_niksh06_rag_duckdb_with_mcp-1.0.0-py3-none-any.whl |
|---|---|
| Size | 18.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2524349510b92007d082bb6660b8cb557ca6f105485ffad1f8b1ddb73744768e
|
|
BLAKE2b-256 checksum How to use checksums |
dcbb9ef797055ea1e9c5645cfa7cfe77e192c0eea05bc557ef89a5d539ff3f7f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_niksh06-rag-duckdb-with-mcp 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.