# 1C RAG MCP — RAG-сервер для документации 1С

[![Статья на Infostart](https://img.shields.io/badge/Infostart-Статья-blue)](https://infostart.ru/1c/articles/2605838)
[![YouTube Demo](https://img.shields.io/badge/YouTube-Demo-red)](http://www.youtube.com/watch?v=74kYcK6bvGk)
[![Docker](https://img.shields.io/badge/Docker-Ready-blue)](https://www.docker.com/)

MCP-сервер для работы с документацией конфигураций 1С Предприятие 8 с использованием RAG (Retrieval-Augmented Generation) и векторной базы данных Qdrant.

---

## 📋 Содержание

- [Возможности](#-возможности)
- [Быстрый старт](#-быстрый-старт)
- [Инструменты MCP](#-инструменты-mcp)
- [Архитектура](#-архитектура)
- [Установка и настройка](#-установка-и-настройка)
- [Использование](#-использование)
- [Документация](#-документация)
- [Оптимизация](#-оптимизация)

---

## ✨ Возможности

### 🔍 Поиск с использованием RAG
- **Мультивекторный поиск** с RRF (Reciprocal Rank Fusion)
- **Два векторных представления**: `object_name` и `friendly_name`
- **Автоматическое ранжирование** по релевантности
- **Фильтрация по типам объектов** 1С

### 🛠️ 5 MCP-инструментов
- Поиск объектов конфигурации
- Информация о коллекции
- Список типов объектов
- Список коллекций Qdrant
- Расширенная диагностика

### 🚀 Оптимизация ресурсов
- Кэширование эмбеддингов (LRU cache)
- HTTP connection pooling
- Лимиты памяти для Docker-контейнеров
- torch.no_grad() для экономии RAM

---

## 🚀 Быстрый старт

### Запуск всех сервисов

```bash
# Сделать скрипты исполняемыми (Linux/Mac)
chmod +x start.sh stop.sh

# Запуск
./start.sh

# Или вручную
docker-compose up --build
```

### Остановка сервисов

```bash
# Остановка
./stop.sh

# Или вручную
docker-compose down
```

### Запуск в режиме production (без inspector)

```bash
docker-compose up -d
```

### Запуск в режиме разработки (с inspector)

```bash
docker-compose --profile dev up -d
```

---

## 🛠️ Инструменты MCP

MCP-сервер предоставляет 5 инструментов для работы с документацией 1С:

| Инструмент | Описание | Пример |
|------------|----------|--------|
| **search_1c_documentation** | Поиск объектов по запросу | `query="Справочник Номенклатура", object_type="Справочник"` |
| **get_collection_info** | Информация о коллекции | `collection_name="1c_rag"` |
| **get_object_types** | Список типов объектов | — |
| **list_collections** | Все коллекции Qdrant | — |
| **health_check_detailed** | Диагностика компонентов | — |

📖 **[Полная документация по инструментам →](mcp/TOOLS.md)**

---

## 🏗️ Архитектура

```
┌─────────────────────────────────────────────────────────────┐
│                     1C RAG MCP                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐     ┌──────────────┐     ┌────────────┐ │
│  │   1С         │────▶│   Loader     │────▶│  Qdrant    │ │
│  │   EPF        │     │  (Streamlit) │     │  (Vector)  │ │
│  └──────────────┘     └──────────────┘     └────────────┘ │
│                            │                    ▲          │
│                            │                    │          │
│                            ▼                    │          │
│                     ┌──────────────┐            │          │
│                     │  Embedding   │────────────┘          │
│                     │   Service    │                       │
│                     └──────────────┘                       │
│                            │                                │
│                            ▼                                │
│                     ┌──────────────┐                       │
│                     │  MCP Server  │◀──── MCP Clients      │
│                     │   (RAG)      │    (Cursor, VSCode)   │
│                     └──────────────┘                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Компоненты

| Компонент | Порт | Назначение |
|-----------|------|------------|
| **Qdrant** | 6333, 6334 | Векторная база данных |
| **Embedding Service** | 5000 | Генерация векторных представлений |
| **Loader** | 8501 | Веб-интерфейс загрузки данных |
| **MCP Server** | 8001 | RAG-сервер для MCP-клиентов |
| **MCP Inspector** | 6274, 6277 | Инструмент отладки (dev) |

---

## 📦 Установка и настройка

### Требования

- Docker и Docker Compose
- 4 GB RAM (минимум), 8 GB RAM (рекомендуется)
- 10 GB свободного места на диске

### Настройка через переменные окружения

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

```bash
# Qdrant
QDRANT_HOST=localhost
QDRANT_PORT=6333
COLLECTION_NAME=1c_rag

# Embedding Service
EMBEDDING_SERVICE_URL=http://localhost:5000

# MCP Server
SERVER_PORT=8001
TRANSPORT_TYPE=streamable-http

# Loader
ROW_BATCH_SIZE=100
EMBEDDING_BATCH_SIZE=32
```

---

## 💡 Использование

### 1. Запустите сервисы

```bash
./start.sh
```

### 2. Выгрузите данные из 1С

Используйте обработку `ПолучитьТекстСтруктурыКонфигурацииФайлами.epf` для выгрузки структуры конфигурации.

### 3. Загрузите данные в Qdrant

Откройте http://localhost:8501 и загрузите ZIP-архив с markdown-файлами и `objects.csv`.

### 4. Подключите MCP-клиент

#### **VSCode Copilot** (`.vscode/mcp.json`)

```json
{
  "servers": {
    "my-1c-mcp-server": {
      "headers": {
        "x-collection-name": "1c_rag"
      },
      "url": "http://localhost:8001/mcp/sse"
    }
  }
}
```

#### **Cursor** (`.cursor/mcp.json`)

```json
{
  "servers": {
    "my-1c-mcp-server": {
      "headers": {
        "x-collection-name": "1c_rag"
      },
      "url": "http://localhost:8001/mcp"
    }
  }
}
```

#### **Claude Desktop** (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "1c-rag": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "COLLECTION_NAME=1c_rag", "mcp-1c-server"]
    }
  }
}
```

---

## 📖 Документация

| Файл | Описание |
|------|----------|
| **[mcp/TOOLS.md](mcp/TOOLS.md)** | Полное описание MCP-инструментов |
| **[mcp/MULTIVECTOR_SEARCH.md](mcp/MULTIVECTOR_SEARCH.md)** | Мультивекторный поиск с RRF |
| **[OPTIMIZATION.md](OPTIMIZATION.md)** | Оптимизация потребления ресурсов |
| **[article/article.md](article/article.md)** | Статья для Infostart |

---

## ⚡ Оптимизация

### Потребление ресурсов (после оптимизации)

| Ресурс | До | После | Экономия |
|--------|-----|-------|----------|
| **RAM** | 2.6-4.4 GB | 1.8-3.0 GB | ~35% |
| **CPU** | 45-65% | 35-50% | ~25% |
| **Контейнеры** | 6 | 5 | -1 |

### Ключевые оптимизации

- ✅ Лимиты памяти для Docker-контейнеров
- ✅ Кэширование эмбеддингов (LRU, 1000 запросов)
- ✅ HTTP Session pooling
- ✅ torch.no_grad() в embedding-сервисе
- ✅ Уменьшенные батчи загрузки (100/32)

📖 **[Полное руководство по оптимизации →](OPTIMIZATION.md)**

---

## 🔧 Отладка

### Просмотр логов

```bash
# Логи конкретного сервиса
docker-compose logs -f mcp-server
docker-compose logs -f embedding-service
docker-compose logs -f loader

# Логи всех сервисов
docker-compose logs -f
```

### Проверка здоровья

```bash
# Через MCP-инструмент
health_check_detailed()

# Через HTTP
curl http://localhost:8001/health
```

### Мониторинг ресурсов

```bash
# Потребление памяти контейнерами
docker stats --no-stream
```

---

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

```
1c-rag-mcp/
├── embeddings/              # Сервис эмбеддингов
│   ├── Dockerfile
│   ├── embedding_service.py
│   ├── config.json
│   └── requirements.txt
├── loader/                  # Загрузчик данных
│   ├── Dockerfile
│   ├── loader.py
│   ├── config.py
│   └── requirements.txt
├── mcp/                     # MCP-сервер
│   ├── Dockerfile
│   ├── mcp_server.py
│   ├── config.py
│   ├── TOOLS.md
│   └── MULTIVECTOR_SEARCH.md
├── common/                  # Общие модули
│   ├── __init__.py
│   ├── config.py
│   └── exceptions.py
├── inspector/               # MCP Inspector (dev)
├── article/                 # Статья и материалы
├── docs/                    # Документация
├── docker-compose.yml       # Конфигурация Docker
├── start.sh, stop.sh        # Скрипты управления
├── ПолучитьТекст...epf      # Обработка 1С
├── README.md                # Главная документация
└── OPTIMIZATION.md          # Оптимизация ресурсов
```
│   └── exceptions.py
├── inspector/               # MCP Inspector (dev)
├── article/                 # Статья и материалы
├── docker-compose.yml       # Конфигурация Docker
├── start.sh, stop.sh        # Скрипты управления
├── ПолучитьТекст...epf      # Обработка 1С
├── README.md                # Этот файл
├── OPTIMIZATION.md          # Оптимизация
└── .gitignore
```

---

## 🔗 Ссылки

- [Статья на Infostart](https://infostart.ru/1c/articles/2605838)
- [Видео на YouTube](http://www.youtube.com/watch?v=74kYcK6bvGk)
- [MCP Protocol](https://modelcontextprotocol.io/)
- [Qdrant Documentation](https://qdrant.tech/documentation/)

---

## 📝 Changelog

### v1.2.0 (2026-03)
- ✅ Добавлены 4 новых MCP-инструмента
- ✅ Оптимизация потребления ресурсов (-35% RAM)
- ✅ Кэширование эмбеддингов
- ✅ HTTP connection pooling
- ✅ Улучшена документация

### v1.1.0
- ✅ Мультивекторный поиск с RRF
- ✅ Поддержка streamable-http транспорта
- ✅ MCP Inspector в Docker

### v1.0.0
- ✅ Базовый RAG-поиск
- ✅ Интеграция с Qdrant
- ✅ Загрузчик данных (Streamlit)

---

## 📄 Лицензия

MIT License — см. файл [LICENSE](LICENSE)

---

## 👥 Авторы

- [FSerg](https://github.com/FSerg)

---

**1C RAG MCP** — RAG-сервер для работы с документацией 1С Предприятие 8