nodebb-plugin-integration 0.4.4 → 0.6.0

package/README.ru.md

@@ -1,198 +1,209 @@
-# NodeBB Integration Layer
+# NodeBB Integration
 
-Плагин интеграции с форумами NodeBB, предоставляющий MCP (Model Context Protocol), семантический поиск на базе AI, RAG-поиск и хранение векторов в Qdrant.
+Слой интеграции NodeBB с AI-сервисами и MCP.
 
-## Возможности
+Плагин подключает NodeBB к семантическому поиску на базе искусственного интеллекта и предоставляет внешним AI-клиентам доступ к функциям форума через Model Context Protocol (MCP).
 
-- Интеграция с NodeBB
-- MCP-сервер с транспортом Streamable HTTP
-- Отдельный дочерний процесс MCP под управлением NodeBB
-- Аутентификация MCP-клиентов по Bearer Token
-- Внутренняя аутентификация API между MCP и NodeBB
-- Генерация embeddings через OpenAI
-- Хранение векторов и семантический поиск в Qdrant
-- RAG-поиск с проверкой прав доступа NodeBB
-- Индексация каждого сообщения отдельно, включая ответы
-- Настройка исключённых категорий
-- Режимы AI-провайдера OpenAI и Fake
-- Интерфейс настройки в ACP
-- Автоматизированные тесты
+- **Версия:** 0.6.0
+- **Лицензия:** MIT
+- **NodeBB:** 4.x
+- **Node.js:** >= 22
 
-## Архитектура
+## Возможности
 
-NodeBB → Integration Plugin → MCP / AI
+- MCP-сервер с транспортом Streamable HTTP.
+- Отдельный дочерний процесс MCP под управлением плагина.
+- Аутентификация MCP-клиентов по Bearer-токену.
+- Отдельный токен аутентификации внутреннего API NodeBB.
+- Настройка адреса прослушивания, порта MCP и сервисного аккаунта.
+- 15 MCP-инструментов для получения информации о форуме, чтения, поиска и управления содержимым.
+- Создание векторных представлений (embeddings) с помощью OpenAI и семантический поиск.
+- Интеграция с векторной базой данных Qdrant.
+- Фильтрация результатов с учётом прав доступа NodeBB.
+- Индексация отдельных сообщений и исключение категорий.
+- Режимы AI-провайдера OpenAI и Fake.
+- Интерфейс настройки в NodeBB ACP.
+- Автоматические тесты обработчиков API и MCP-инструментов.
 
-MCP: Streamable HTTP → MCP Child Process → Internal NodeBB API → NodeBB Access Control
+## Требования
 
-AI: OpenAI → Embeddings → Qdrant → Vector Search → Knowledge Retrieval
+- Node.js >= 22.
+- npm >= 10.
+- NodeBB 4.x.
+- Работающий экземпляр NodeBB.
 
-## Требования
+Для семантического поиска дополнительно необходимы:
 
-- Node.js >= 20
-- npm >= 10
-- NodeBB 4.x
+- API-ключ OpenAI.
+- Доступный экземпляр Qdrant и настроенная коллекция, соответствующая используемой модели embeddings.
 
-Для работы AI необходимы API-ключ OpenAI и сервер Qdrant. Для работы MCP необходим запущенный экземпляр NodeBB.
+MCP может использоваться независимо от семантического поиска. Инструмент `search_knowledge` требует провайдера OpenAI и Qdrant.
 
 ## Установка
 
-Установите плагин через интерфейс управления плагинами NodeBB или используйте обычную процедуру установки плагинов.
+Установите плагин через интерфейс администрирования NodeBB или стандартным способом установки плагинов NodeBB.
 
-Установите зависимости командой npm install в каталоге плагина.
+При ручной установке:
 
-Перезапустите NodeBB и откройте настройки плагина: ACP → Plugins → NodeBB Integration.
+```bash
+cd /path/to/nodebb
+npm install nodebb-plugin-integration
+```
 
-## Настройка
+Соберите NodeBB и перезапустите его стандартным способом, предусмотренным вашей установкой.
 
-Плагин настраивается через интерфейс ACP NodeBB.
+После установки откройте:
 
-### AI-провайдер
+**NodeBB ACP → Plugins → NodeBB Integration**
 
-Доступны два режима.
+Настройте необходимые параметры и сохраните настройки.
 
-**OpenAI**
-
-Включает:
-- Генерацию embeddings через OpenAI
-- Хранение векторов в Qdrant
-- Индексацию сообщений
-- Семантический поиск
-- RAG-поиск
+## Настройка
 
-Настраиваются API-ключ OpenAI, модель и размерность embeddings, URL Qdrant и имя коллекции.
+Настройки плагина выполняются через NodeBB ACP.
 
-**Fake**
+### AI-провайдер
 
-Полностью отключает функциональность AI:
-- API OpenAI не вызывается.
-- Qdrant не используется.
-- Embeddings не создаются.
-- Индексация сообщений отключена.
-- Семантический поиск отключён.
+Поддерживаются два режима:
 
-Интеграция с NodeBB и MCP продолжают работать.
+- **OpenAI** — включает embeddings и семантический поиск.
+- **Fake** — отключает обращения к OpenAI. Семантический поиск в этом режиме недоступен.
 
-Настройки OpenAI и Qdrant сохраняются при переключении провайдеров. Повторный выбор OpenAI снова включает AI-конвейер.
+Для семантического поиска настройте API-ключ OpenAI, параметры embeddings и подключение к Qdrant в соответствии с вашей инфраструктурой.
 
-Режим Fake предназначен для разработки и тестирования интеграции NodeBB и MCP без внешних AI-сервисов.
+### Поиск и индексация
 
-### Исключённые категории
+Плагин использует embeddings для индексации содержимого форума, а Qdrant — для хранения и поиска векторов.
 
-Категории, выбранные в ACP, исключаются из AI-индексации и семантического поиска.
+Результаты не возвращаются только на основании векторного сходства. Перед выдачей результата плагин проверяет, может ли настроенный пользователь NodeBB читать соответствующее сообщение и тему.
 
-## AI-конвейер
+Параметр Excluded Categories позволяет исключить выбранные категории из семантического поиска.
 
-При включённом OpenAI обработка выполняется следующим образом:
+Плагин проверяет метаданные найденных сообщений по данным NodeBB перед возвратом содержимого. Qdrant используется как векторный индекс; источником содержимого сообщений и информации о правах доступа остаётся NodeBB.
 
-Сообщение форума → Генерация Embeddings → Сохранение векторов в Qdrant → Семантический поиск → Проверка прав доступа NodeBB → Получение содержимого сообщений
+### MCP-сервер
 
-Каждое сообщение индексируется отдельно, включая ответы.
+Настройки MCP:
 
-Результаты поиска проверяются на соответствие правам NodeBB до получения содержимого сообщений. Сообщения и темы, недоступные сервисному пользователю, исключаются из результатов.
+| Параметр | Описание |
+|---|---|
+| Enable MCP | Включение и выключение MCP-сервера |
+| Bind address | Адрес, на котором слушает HTTP-сервер MCP |
+| Port | HTTP-порт MCP |
+| NodeBB URL | Внутренний URL NodeBB для доступа процесса MCP |
+| Bearer token | Токен аутентификации MCP-клиентов |
+| Service user UID | NodeBB-аккаунт для проверок прав и операций записи |
 
-Qdrant хранит только векторы и метаданные. Текст сообщений извлекается из NodeBB после проверки прав доступа.
+Настройки подключения MCP по умолчанию:
 
-## Qdrant
+```text
+Bind address: 127.0.0.1
+Port:         3100
+NodeBB URL:   http://127.0.0.1:4567
+```
 
-Через ACP задаются URL Qdrant, имя коллекции и размерность векторов.
+Адрес `127.0.0.1` по умолчанию ограничивает доступ к MCP локальным интерфейсом. Меняйте его только при осознанной необходимости удалённого доступа и при условии защиты сетевого подключения.
 
-Плагин проверяет наличие коллекции и создаёт её при необходимости.
+Плагин автоматически генерирует отдельный случайный токен внутреннего API. Он отличается от Bearer-токена MCP-клиентов и не предназначен для передачи клиентам.
 
-При выборе Fake обращения к Qdrant не выполняются.
+Настроенный сервисный пользователь является субъектом всех операций MCP. Клиент не может подменить UID пользователя, от имени которого выполняется операция.
 
-## MCP-сервер
+## MCP-инструменты
 
-MCP-сервер управляется плагином NodeBB и работает в отдельном дочернем процессе.
+MCP-сервер предоставляет 15 инструментов:
 
-Транспорт:
-- Streamable HTTP
-- Аутентификация Bearer Token
+| Инструмент | Описание |
+|---|---|
+| `get_forum_info` | Получение общедоступной информации о форуме |
+| `get_post` | Чтение сообщения |
+| `get_topic` | Получение метаданных темы |
+| `get_user` | Получение публичных полей профиля пользователя |
+| `search_knowledge` | Семантический поиск по содержимому форума |
+| `create_topic` | Создание темы |
+| `delete_topic` | Логическое удаление темы |
+| `restore_topic` | Восстановление темы |
+| `list_topics` | Получение списка доступных тем |
+| `create_post` | Создание ответа |
+| `edit_post` | Редактирование сообщения |
+| `delete_post` | Логическое удаление сообщения |
+| `restore_post` | Восстановление сообщения |
+| `delete_user_posts` | Пакетное логическое удаление ответов пользователя |
+| `list_posts` | Получение сообщений темы |
 
-MCP-сервер взаимодействует с NodeBB через защищённый внутренний API. Для него используется отдельный секрет, управляемый плагином.
+Все операции записи используют нативные методы NodeBB и штатные проверки прав.
 
-В ACP настраиваются:
-- Включение и отключение MCP
-- Адрес привязки
-- Порт
-- URL NodeBB
-- Bearer Token
-- UID сервисного пользователя
+Инструменты удаления выполняют логическое удаление, а не безвозвратное уничтожение данных. `delete_user_posts` пропускает первое сообщение каждой темы. Восстановление темы не восстанавливает автоматически сообщения, удалённые отдельно.
 
-UID сервисного пользователя задаётся администратором. MCP-клиенты не могут его переопределять.
+Полное описание аргументов, схем, значений по умолчанию, ограничений, результатов, прав доступа, пагинации и примеров:
 
-### Доступные инструменты
+- [Справочник MCP API (Русский)](docs/MCP.ru.md)
+- [MCP API Reference (English)](docs/MCP.md)
 
-- get_forum_info — Получение общедоступной информации о форуме.
-- get_post — Получение сообщения после проверки прав доступа.
-- get_topic — Получение темы после проверки прав доступа.
-- get_user — Получение общедоступной информации о пользователе.
-- search_knowledge — Поиск по проиндексированным данным форума.
+## Безопасность
 
-Для search_knowledge необходим провайдер OpenAI. В режиме Fake инструмент возвращает явную ошибку о выключенном AI.
+- MCP-клиенты должны проходить Bearer-аутентификацию.
+- Внутренний API NodeBB использует отдельный автоматически сгенерированный токен.
+- Внутренние маршруты API требуют аутентификации и недоступны при выключенном MCP.
+- Адрес прослушивания MCP по умолчанию — `127.0.0.1`.
+- Права MCP-операций определяются настроенным сервисным пользователем.
+- Операции чтения выполняют проверки доступа NodeBB.
+- Семантический поиск фильтрует результаты с учётом прав сервисного пользователя.
+- Публичный поиск пользователей возвращает только выбранные поля профиля.
+- Секретные значения не включаются в публичную информацию о конфигурации плагина.
 
-## Безопасность
+Используйте отдельную учётную запись NodeBB с минимально необходимыми правами. Не раскрывайте токен внутреннего API.
 
-- MCP-клиенты проходят аутентификацию по Bearer Token.
-- Внутренние API-запросы используют отдельный секрет.
-- Секреты не возвращаются в интерфейс ACP.
-- Пустые поля секретов сохраняют ранее заданные значения.
-- Идентификаторам пользователей, переданным MCP-клиентами, не доверяют.
-- Для проверки прав используется настроенный сервисный пользователь.
-- Права на сообщения и темы проверяются до возврата содержимого.
-- При ошибке проверки доступа доступ запрещается.
-- Payload Qdrant содержит идентификаторы и метаданные, но не текст сообщений.
+## Разработка
 
-Не добавляйте API-ключи, токены и другие секреты в систему контроля версий.
+Установка зависимостей:
 
-## Разработка и тестирование
+```bash
+npm install
+```
 
-Установка зависимостей: npm install
+Проверка синтаксиса:
 
-Проверка синтаксиса: npm run check
+```bash
+npm run check
+```
 
-Запуск тестов: npm test
+Запуск тестов:
 
+```bash
+npm test
+```
 
-Тесты проверяют конфигурацию, аргументы MCP-инструментов и другие компоненты плагина.
+Тесты охватывают аутентификацию API, обработчики API, проверку аргументов и работу MCP-инструментов.
 
 ## Структура проекта
 
-library.js
-package.json
-plugin.json
-public/
-  js/admin.js
-  templates/admin/plugins/integration.tpl
-src/
-  ai/
-    embeddings.js
-    indexer.js
-    openai.js
-    qdrant.js
-    search.js
-  config/
-    index.js
-    validation.js
-  events/
-    index.js
-  mcp/
-    manager.js
-    server.js
-    tools.js
-  nodebb/
-    categories.js
-    index.js
-    meta.js
-    posts.js
-    privileges.js
-    topics.js
-    users.js
-  routes/
-    api.js
-    index.js
-test/
-  config-validation.test.js
-  mcp-tools.test.js
+```text
+.
+├── library.js
+├── plugin.json
+├── package.json
+├── README.md
+├── README.ru.md
+├── docs/
+│   ├── MCP.md
+│   └── MCP.ru.md
+├── src/
+│   ├── ai/
+│   ├── config/
+│   ├── mcp/
+│   ├── nodebb/
+│   └── routes/
+├── public/
+├── languages/
+└── test/
+```
+
+## Совместимость
+
+Плагин предназначен для NodeBB 4.x.
+Версия 0.6.0 протестирована с NodeBB 4.16.7.
+
+Плагину требуется Node.js >= 22. Набор полей нативных ответов может отличаться между версиями NodeBB.
 
 ## Лицензия