nodebb-plugin-integration 0.4.4 → 0.6.0

package/docs/MCP.ru.md

@@ -0,0 +1,719 @@
+# Справочник MCP API
+
+Версия: 0.6.0
+
+Документ описывает все MCP-инструменты, предоставляемые плагином `nodebb-plugin-integration`.
+
+## 1. Обзор
+
+Плагин предоставляет сервер Model Context Protocol (MCP) с транспортом Streamable HTTP.
+
+Архитектура:
+
+```text
+MCP-клиент
+    |
+    | Streamable HTTP + Bearer-токен
+    v
+Дочерний процесс MCP
+    |
+    | Внутренний HTTP API + отдельный Bearer-токен
+    v
+Плагин интеграции NodeBB
+    |
+    v
+Нативные API NodeBB и проверки прав
+```
+
+MCP работает в отдельном дочернем процессе, которым управляет плагин NodeBB.
+
+Все операции записи выполняются от имени NodeBB-аккаунта, заданного параметром `mcpServiceUid`. MCP-клиент не может самостоятельно выбрать или подменить пользователя, от имени которого выполняется операция.
+
+## 2. Настройка
+
+Настройки находятся в NodeBB ACP → Plugins → NodeBB Integration.
+
+| Параметр | Описание |
+|---|---|
+| Enable MCP | Включение и выключение MCP-сервера |
+| Bind address | Сетевой интерфейс, на котором слушает HTTP-сервер MCP |
+| Port | HTTP-порт MCP |
+| NodeBB URL | Адрес NodeBB, используемый процессом MCP |
+| Bearer token | Секрет для аутентификации MCP-клиентов |
+| Service user UID | NodeBB UID пользователя для проверок прав и операций записи | . Обязательный параметр; должен быть положительным целым числом. 
+
+Значения по умолчанию:
+
+- Адрес: `127.0.0.1`
+- Порт: `3100`
+- NodeBB URL: `http://127.0.0.1:4567`
+
+Плагин автоматически генерирует и сохраняет отдельный токен внутреннего API.
+
+Внешний Bearer-токен MCP и токен внутреннего API — разные секреты.
+
+Не передавайте токен внутреннего API MCP-клиентам.
+
+## 3. Аутентификация и права доступа
+
+MCP-клиент передаёт токен в заголовке:
+
+```http
+Authorization: Bearer YOUR_MCP_TOKEN
+```
+
+Дочерний процесс MCP использует отдельный токен для аутентификации запросов к NodeBB.
+
+Внутренний API отклоняет запросы, если MCP выключен или внутренний токен неверен.
+
+### Пользователь, от имени которого выполняются операции
+
+Настроенный `mcpServiceUid` используется для:
+
+- Чтения сообщений и тем с проверкой прав.
+- Фильтрации результатов семантического поиска.
+- Получения списков тем и сообщений.
+- Создания тем и ответов.
+- Редактирования, удаления и восстановления сообщений.
+- Удаления и восстановления тем.
+- Массового удаления ответов пользователя.
+
+Аргумент `uid` инструмента `delete_user_posts` указывает целевого автора сообщений. Он не меняет пользователя, от имени которого выполняется удаление.
+
+### Проверки NodeBB
+
+Для операций записи используются нативные методы NodeBB. Сохраняются штатные проверки прав, ограничения и хуки.
+
+В частности:
+
+- Проверки прав категории при создании темы.
+- Проверки права ответа и состояния темы.
+- Проверки права редактирования и ограничений редактирования.
+- Проверки прав удаления и восстановления сообщений и тем.
+- Нативные хуки NodeBB, связанные с этими операциями.
+
+Операции чтения содержимого сообщений и тем проверяют доступ пользователя сервиса.
+
+`get_user` возвращает публичные поля профиля и не раскрывает приватные данные аккаунта.
+
+При ошибке проверки доступа доступ запрещается.
+
+## 4. Общие правила аргументов
+
+- ID должны быть положительными безопасными целыми числами.
+- Смещения пагинации должны быть неотрицательными целыми числами.
+- Неизвестные аргументы отклоняются.
+- Дополнительные свойства объектов запрещены.
+- Текстовые аргументы не могут быть пустыми или состоять только из пробелов.
+- Ограничения длины текста измеряются в символах JavaScript-строки.
+- Аргументы инструмента должны быть JSON-объектами.
+
+Результаты инструментов возвращаются в MCP как текст с форматированным JSON. Ошибки возвращаются как результаты инструмента с `isError: true`.
+
+## 5. Описание инструментов
+
+### 5.1 get_forum_info
+
+Получает общедоступную информацию о форуме.
+
+Аргументы: отсутствуют.
+
+Пример:
+
+```json
+{}
+```
+
+Поля ответа:
+
+| Поле | Тип | Описание |
+|---|---|---|
+| title | string | Название форума |
+| url | string | URL форума |
+| version | string | Версия NodeBB |
+| language | string или null | Язык форума |
+
+Пример:
+
+```json
+{
+  "title": "Example Forum",
+  "url": "https://forum.example.com",
+  "version": "4.16.7",
+  "language": "ru"
+}
+```
+
+### 5.2 get_post
+
+Получает сообщение по ID после проверки прав настроенного пользователя сервиса на чтение сообщения и его темы.
+
+Аргументы:
+
+| Имя | Тип | Обязательный | Ограничения |
+|---|---|---|---|
+| pid | integer | Да | Минимум 1 |
+
+Пример:
+
+```json
+{
+  "pid": 123
+}
+```
+
+Поля ответа:
+
+| Поле | Тип | Описание |
+|---|---|---|
+| pid | integer | ID сообщения |
+| tid | integer | ID темы |
+| uid | integer | UID автора |
+| cid | integer | ID категории |
+| content | string | Содержимое сообщения |
+| timestamp | NodeBB timestamp | Время создания сообщения |
+
+Удалённые, отсутствующие и недоступные пользователю сервиса сообщения возвращаются как ненайденные.
+
+### 5.3 get_topic
+
+Получает метаданные темы после проверки права на её чтение.
+
+Аргументы:
+
+| Имя | Тип | Обязательный | Ограничения |
+|---|---|---|---|
+| tid | integer | Да | Минимум 1 |
+
+Пример:
+
+```json
+{
+  "tid": 42
+}
+```
+
+Поля ответа:
+
+| Поле | Тип | Описание |
+|---|---|---|
+| tid | integer | ID темы |
+| uid | integer | UID автора темы |
+| title | string | Заголовок темы |
+| cid | integer | ID категории |
+| timestamp | NodeBB timestamp | Время создания темы |
+| mainPid | integer | ID первого сообщения |
+
+Инструмент возвращает метаданные темы, а не полный список сообщений. Для получения сообщений используйте `list_posts`.
+
+### 5.4 get_user
+
+Возвращает публичную информацию о профиле пользователя.
+
+Аргумент `uid` указывает пользователя, чей профиль требуется получить. Он не меняет пользователя сервиса и не используется для выполнения операций от его имени.
+
+Аргументы:
+
+| Имя | Тип | Обязательный | Ограничения |
+|---|---|---|---|
+| uid | integer | Да | Минимум 1 |
+
+Пример:
+
+```json
+{
+  "uid": 7
+}
+```
+
+Поля ответа:
+
+| Поле | Тип | Описание |
+|---|---|---|
+| uid | integer | ID пользователя |
+| username | string | Имя пользователя |
+| userslug | string | URL-совместимое имя |
+| picture | string | URL или значение аватара, предоставленное NodeBB |
+
+Возвращаются только перечисленные выше поля.
+
+### 5.5 search_knowledge
+
+Выполняет семантический поиск по базе знаний форума.
+
+Требует включённого провайдера OpenAI и работающей коллекции Qdrant.
+
+Аргументы:
+
+| Имя | Тип | Обязательный | Ограничения |
+|---|---|---|---|
+| query | string | Да | 1–2000 символов |
+| limit | integer | Нет | 1–20; по умолчанию 5 |
+
+Пример:
+
+```json
+{
+  "query": "Как настроить уведомления форума?",
+  "limit": 5
+}
+```
+
+Ответ:
+
+```json
+{
+  "results": [
+    {
+      "pid": 123,
+      "tid": 42,
+      "uid": 7,
+      "cid": 3,
+      "score": 0.91,
+      "content": "Содержимое сообщения..."
+    }
+  ]
+}
+```
+
+Поля результата:
+
+| Поле | Тип | Описание |
+|---|---|---|
+| pid | integer | ID сообщения |
+| tid | integer | ID темы |
+| uid | integer | UID автора |
+| cid | integer | ID категории |
+| score | number | Оценка семантического сходства из векторного поиска |
+| content | string | Содержимое сообщения, полученное из NodeBB |
+
+Алгоритм поиска:
+
+1. Создаёт embedding для запроса.
+2. Ищет кандидатов в Qdrant.
+3. Проверяет исключённые категории.
+4. Проверяет права пользователя сервиса на чтение сообщения и темы.
+5. Получает разрешённое содержимое сообщений из NodeBB.
+6. Возвращает не более запрошенного количества подходящих результатов.
+
+Реализация может получить больше кандидатов, чем запрошено, чтобы компенсировать отсеивание по правам доступа.
+
+В режиме Fake AI инструмент возвращает ошибку о выключенном AI. Семантический поиск не выполняется.
+
+### 5.6 create_topic
+
+Создаёт тему в категории NodeBB от имени настроенного пользователя сервиса.
+
+Аргументы:
+
+| Имя | Тип | Обязательный | Ограничения |
+|---|---|---|---|
+| cid | integer | Да | Минимум 1 |
+| title | string | Да | 1–255 символов |
+| content | string | Да | 1–20000 символов |
+| tags | массив строк | Нет | Не более 10 тегов; каждый 1–32 символа |
+
+Пример:
+
+```json
+{
+  "cid": 3,
+  "title": "Новая дискуссия",
+  "content": "Содержимое первого сообщения.",
+  "tags": ["discussion", "help"]
+}
+```
+
+Если `tags` не указан, используется пустой массив.
+
+Перед отправкой заголовок очищается от пробелов по краям. Содержимое передаётся NodeBB без обрезки.
+
+NodeBB выполняет проверки прав категории, ограничений публикации, тегов и штатные хуки создания темы.
+
+Ответ соответствует результату нативного метода NodeBB создания темы.
+
+### 5.7 delete_topic
+
+Удаляет тему логически (soft delete), используя нативные проверки прав и хуки NodeBB.
+
+Аргументы:
+
+| Имя | Тип | Обязательный | Ограничения |
+|---|---|---|---|
+| tid | integer | Да | Минимум 1 |
+
+Пример:
+
+```json
+{
+  "tid": 42
+}
+```
+
+Это логическое удаление, а не физическое уничтожение данных.
+
+Ответ соответствует результату нативной операции NodeBB.
+
+### 5.8 restore_topic
+
+Восстанавливает ранее логически удалённую тему.
+
+Аргументы:
+
+| Имя | Тип | Обязательный | Ограничения |
+|---|---|---|---|
+| tid | integer | Да | Минимум 1 |
+
+Пример:
+
+```json
+{
+  "tid": 42
+}
+```
+
+NodeBB проверяет права пользователя и выполняет штатные хуки восстановления.
+
+Восстановление темы не восстанавливает автоматически сообщения, которые были удалены отдельно.
+
+Ответ соответствует результату нативной операции NodeBB.
+
+### 5.9 list_topics
+
+Получает список тем, доступных настроенному пользователю сервиса.
+
+Аргументы:
+
+| Имя | Тип | Обязательный | Ограничения |
+|---|---|---|---|
+| start | integer | Нет | 0–10000000; по умолчанию 0 |
+| limit | integer | Нет | 1–100; по умолчанию 20 |
+| sort | string | Нет | Одно из допустимых значений; по умолчанию `recent` |
+| cid | integer | Нет | Минимум 1; фильтр по категории |
+
+Допустимые значения `sort`:
+
+| Значение | Описание |
+|---|---|
+| recent | По последней активности |
+| old | Более старые темы |
+| create | Сортировка по созданию |
+| posts | По количеству сообщений |
+| votes | По голосам |
+| views | По просмотрам |
+
+Пример:
+
+```json
+{
+  "start": 0,
+  "limit": 20,
+  "sort": "recent",
+  "cid": 3
+}
+```
+
+Ответ содержит результат нативного списка NodeBB и метаданные пагинации:
+
+| Поле | Тип | Описание |
+|---|---|---|
+| topics | array | Записи тем, возвращённые NodeBB |
+| topicCount | integer | Общее количество тем по данным NodeBB |
+| nextStart | integer | Рекомендуемое смещение следующего запроса |
+| hasMore | boolean | `hasMore` — подсказка о наличии следующих результатов, рассчитанная по общему количеству записей NodeBB. Она не гарантирует, что следующий запрос вернёт непустую страницу. |
+
+Точный набор полей записей тем определяется установленной версией NodeBB.
+
+### 5.10 create_post
+
+Создаёт ответ в существующей теме.
+
+Инструмент создаёт ответ, а не новую тему и не заменяет первое сообщение темы.
+
+Аргументы:
+
+| Имя | Тип | Обязательный | Ограничения |
+|---|---|---|---|
+| tid | integer | Да | Минимум 1 |
+| content | string | Да | 1–20000 символов |
+
+Пример:
+
+```json
+{
+  "tid": 42,
+  "content": "Это ответ в теме."
+}
+```
+
+Ответ создаётся от имени настроенного пользователя сервиса.
+
+NodeBB проверяет право ответа, состояние темы, права категории и штатные ограничения публикации.
+
+Ответ соответствует результату нативного метода NodeBB создания ответа.
+
+### 5.11 edit_post
+
+Редактирует существующее сообщение.
+
+Аргументы:
+
+| Имя | Тип | Обязательный | Ограничения |
+|---|---|---|---|
+| pid | integer | Да | Минимум 1 |
+| content | string | Да | 1–20000 символов |
+
+Пример:
+
+```json
+{
+  "pid": 123,
+  "content": "Обновлённый текст сообщения."
+}
+```
+
+Операция выполняется от имени настроенного пользователя сервиса.
+
+NodeBB применяет штатные проверки прав и ограничения редактирования. Сохраняются нативные хуки и история редактирования.
+
+Ответ соответствует результату нативного метода NodeBB редактирования.
+
+### 5.12 delete_post
+
+Логически удаляет сообщение.
+
+Аргументы:
+
+| Имя | Тип | Обязательный | Ограничения |
+|---|---|---|---|
+| pid | integer | Да | Минимум 1 |
+
+Пример:
+
+```json
+{
+  "pid": 123
+}
+```
+
+NodeBB применяет штатные проверки прав и хуки удаления сообщения.
+
+Это не физическое удаление. Методы окончательной очистки (purge) не вызываются.
+
+Ответ соответствует результату нативной операции NodeBB.
+
+### 5.13 restore_post
+
+Восстанавливает логически удалённое сообщение.
+
+Аргументы:
+
+| Имя | Тип | Обязательный | Ограничения |
+|---|---|---|---|
+| pid | integer | Да | Минимум 1 |
+
+Пример:
+
+```json
+{
+  "pid": 123
+}
+```
+
+NodeBB применяет штатные проверки прав и хуки восстановления.
+
+Ответ соответствует результату нативной операции NodeBB.
+
+### 5.14 delete_user_posts
+
+Логически удаляет ответы, написанные указанным пользователем.
+
+Первое сообщение каждой темы всегда пропускается. Инструмент не удаляет первые сообщения тем.
+
+Аргументы:
+
+| Имя | Тип | Обязательный | Ограничения |
+|---|---|---|---|
+| uid | integer | Да | UID целевого пользователя; минимум 1 |
+| start | integer | Нет | 0–10000000; по умолчанию 0 |
+| limit | integer | Нет | 1–100; по умолчанию 100 |
+
+Пример:
+
+```json
+{
+  "uid": 25,
+  "start": 0,
+  "limit": 100
+}
+```
+
+Удаление выполняется настроенным пользователем сервиса. Переданный `uid` указывает только целевого автора сообщений.
+
+Операция обрабатывает сообщения последовательно и продолжает работу после отдельных ошибок удаления.
+
+Ошибки отдельных операций удаления включаются в массив `failed`. Сами по себе такие ошибки не прерывают обработку остальных сообщений и не означают, что весь вызов инструмента завершился ошибкой.
+
+Сообщения пропускаются, если их ID некорректен, сообщение отсутствует, уже удалено, принадлежит другому пользователю или является первым сообщением темы.
+
+Ответ:
+
+| Поле | Тип | Описание |
+|---|---|---|
+| uid | integer | UID целевого пользователя |
+| scanned | integer | Количество ID, полученных на текущей странице |
+| deleted | integer | Количество успешно удалённых ответов |
+| skipped | integer | Количество пропущенных сообщений |
+| failed | array | Ошибки отдельных операций удаления |
+| hasMore | boolean | Заполнена ли текущая страница ID до запрошенного лимита |
+| nextStart | integer | Рекомендуемое смещение следующей пачки |
+
+Каждая запись `failed` содержит:
+
+```json
+{
+  "pid": 123,
+  "error": "Permission denied"
+}
+```
+
+Пример ответа:
+
+```json
+{
+  "uid": 25,
+  "scanned": 100,
+  "deleted": 85,
+  "skipped": 10,
+  "failed": [
+    {
+      "pid": 456,
+      "error": "Permission denied"
+    }
+  ],
+  "hasMore": true,
+  "nextStart": 15
+}
+```
+
+Пример иллюстративный: реальные значения зависят от полученных ID и результатов операций.
+
+#### Обработка пачками
+
+Для следующего запроса используйте `nextStart` из предыдущего ответа в качестве `start`:
+
+```json
+{
+  "uid": 25,
+  "start": 15,
+  "limit": 100
+}
+```
+
+Успешно удалённые сообщения исчезают из активного списка сообщений пользователя. Реализация вычитает количество успешно удалённых сообщений из `nextStart`, чтобы не пропускать оставшиеся ответы из-за смещения списка.
+
+`hasMore` определяется по тому, содержит ли текущая страница ID полное запрошенное количество записей. Это подсказка пагинации: дополнительный запрос может вернуть пустую страницу.
+
+Операция не выполняет физическое уничтожение данных. Первые сообщения тем этим инструментом не удаляются.
+### 5.15 list_posts
+
+Получает сообщения темы с применением фильтрации доступа NodeBB и пагинации.
+
+Аргументы:
+
+| Имя | Тип | Обязательный | Ограничения |
+|---|---|---|---|
+| tid | integer | Да | Минимум 1 |
+| start | integer | Нет | 0–10000000; по умолчанию 0 |
+| limit | integer | Нет | 1–100; по умолчанию 20 |
+| reverse | boolean | Нет | По умолчанию false |
+
+Пример:
+
+```json
+{
+  "tid": 42,
+  "start": 0,
+  "limit": 20,
+  "reverse": false
+}
+```
+
+Ответ:
+
+| Поле | Тип | Описание |
+|---|---|---|
+| tid | integer | ID темы |
+| start | integer | Запрошенное смещение |
+| limit | integer | Запрошенный размер страницы |
+| reverse | boolean | Флаг обратного порядка |
+| posts | array | Записи сообщений темы, возвращённые NodeBB |
+| total | integer | Количество сообщений темы по данным NodeBB |
+| nextStart | integer | Рекомендуемое смещение следующей страницы |
+| hasMore | boolean | `hasMore` — подсказка о наличии следующих результатов, рассчитанная по общему количеству записей NodeBB. Она не гарантирует, что следующий запрос вернёт непустую страницу. |
+
+Поля записей сообщений определяются установленной версией NodeBB.
+
+Перед получением сообщений проверяется право пользователя сервиса на чтение темы. Удалённые или недоступные темы не возвращаются.
+
+## 6. Пагинация
+
+Инструменты списков используют смещения, начинающиеся с нуля.
+
+| Инструмент | Начальное смещение | Лимит по умолчанию | Максимум |
+|---|---:|---:|---:|
+| list_topics | 0 | 20 | 100 |
+| list_posts | 0 | 20 | 100 |
+| delete_user_posts | 0 | 100 | 100 |
+
+Для инструментов списков используйте возвращённый `nextStart` в следующем запросе, если `hasMore` равен `true`.
+
+Для массового удаления всегда используйте возвращённый `nextStart`, поскольку успешное удаление изменяет активный список сообщений пользователя.
+
+## 7. Ошибки
+
+Сервер MCP возвращает ошибки выполнения как текст с `isError: true`.
+
+Типичные ситуации:
+
+| Ситуация | Поведение |
+|---|---|
+| Некорректные аргументы | Ошибка проверки аргументов |
+| Неизвестный или дополнительный аргумент | Запрос отклоняется |
+| Некорректный ID | Запрос отклоняется |
+| MCP выключен | Внутренний API отклоняет запрос |
+| Неверный внутренний токен | Внутренний API возвращает Unauthorized |
+| Сообщение или тема отсутствуют либо недоступны | Для защищённых операций чтения возвращается Not found |
+| Нет прав NodeBB | Ошибка нативной операции NodeBB |
+| AI-провайдер выключен | Семантический поиск недоступен |
+| Ошибка внутренней операции | Инструмент возвращает ошибку |
+
+Для `search_knowledge` выключенный AI возвращается как явная ошибка. Другие ошибки поисковой инфраструктуры также возвращаются как ошибки.
+
+Массовое удаление отличается от одиночных операций: отдельные ошибки собираются в `failed`, обработка остальных ID продолжается.
+
+## 8. Безопасность и эксплуатация
+
+- Используйте отдельную учётную запись NodeBB с минимально необходимыми правами.
+- Не раскрывайте токен внутреннего API MCP.
+- Используйте `127.0.0.1` для bind-адреса, если удалённый доступ не требуется.
+- При удалённом доступе используйте защищённый сетевой канал.
+- Инструменты удаления выполняют логическое удаление, а не окончательную очистку.
+- `delete_user_posts` пропускает первые сообщения тем.
+- Восстановление темы не восстанавливает отдельно удалённые сообщения.
+- Семантический поиск возвращает только сообщения, доступные пользователю сервиса.
+- Плагин не доверяет UID пользователя, переданному клиентом для операций записи.
+
+## 9. Совместимость
+
+Плагин предназначен для NodeBB 4.x и требует Node.js >= 22.
+
+Реализация версии 0.6.0 проверена на NodeBB 4.16.7.
+
+Для создания, редактирования, удаления, восстановления и получения списков используются нативные методы NodeBB. Набор полей нативных ответов может отличаться между версиями NodeBB.
+
+## 10. Связанная документация
+
+- [README проекта](../README.md)
+- [English MCP documentation](MCP.md)
+- [Русский README](../README.ru.md)