nodebb-plugin-integration 0.3.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Sergey-ek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,320 @@
+# NodeBB Integration Layer
+
+AI integration layer for NodeBB forums with MCP, semantic search, RAG pipeline and Qdrant vector storage.
+
+![Node.js](https://img.shields.io/badge/node-%3E%3D20-green)
+![Tests](https://github.com/Sergey-ek/nodebb-plugin-integration/actions/workflows/test.yml/badge.svg)
+![License](https://img.shields.io/badge/license-MIT-blue)
+
+## Features
+
+* NodeBB integration adapter
+* MCP (Model Context Protocol) server
+* Semantic search
+* RAG knowledge pipeline
+* Qdrant vector database support
+* OpenAI embeddings support
+* Fake embeddings for local development
+* Standalone development mode
+* Automated tests with GitHub Actions
+
+## Architecture
+
+```
+                    NodeBB
+
+                      |
+                      |
+
+                Integration Layer
+
+                      |
+        +-------------+-------------+
+
+        |                           |
+
+      MCP                         AI
+
+        |                           |
+
+   Tools API                  Embeddings
+
+                                    |
+
+                                  Qdrant
+
+                                    |
+
+                              Knowledge Base
+```
+
+## Requirements
+
+* Node.js >= 20
+* npm >= 10
+
+Optional:
+
+* NodeBB
+* Redis
+* Qdrant
+* OpenAI API key
+
+## Installation
+
+Clone repository:
+
+```bash
+git clone https://github.com/Sergey-ek/nodebb-plugin-integration.git
+
+cd nodebb-plugin-integration
+```
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Create environment file:
+
+```bash
+cp .env.example .env
+```
+
+## Development mode
+
+By default the project uses fake embeddings:
+
+```
+AI_PROVIDER=fake
+```
+
+This allows running tests without:
+
+* OpenAI
+* Qdrant
+* NodeBB
+
+Run diagnostics:
+
+```bash
+npm run diagnose
+```
+
+Example:
+
+```
+{
+ environment: "development",
+ embeddings: {
+   provider: "fake",
+   size: 1536
+ }
+}
+```
+
+## Testing
+
+Syntax check:
+
+```bash
+npm run check
+```
+
+Run tests:
+
+```bash
+npm test
+```
+
+Expected:
+
+```
+8 passing
+```
+
+## NodeBB Integration
+
+Configure:
+
+```
+NODEBB_URL=http://localhost:4567
+
+NODEBB_API_KEY=your_token
+```
+
+When running inside NodeBB, the plugin uses native NodeBB modules.
+
+Standalone mode provides safe fallback adapters.
+
+## AI Pipeline
+
+Flow:
+
+```
+Forum post
+
+    |
+
+Embedding generation
+
+    |
+
+Vector storage
+
+    |
+
+Qdrant similarity search
+
+    |
+
+Knowledge retrieval
+
+    |
+
+AI response
+```
+
+Supported providers:
+
+### Fake
+
+Development mode:
+
+```
+AI_PROVIDER=fake
+```
+
+### OpenAI
+
+Production mode:
+
+```
+AI_PROVIDER=openai
+
+OPENAI_API_KEY=your_key
+```
+
+## Qdrant
+
+Configure:
+
+```
+QDRANT_URL=http://localhost:6333
+
+QDRANT_COLLECTION=nodebb_knowledge
+```
+
+The system automatically:
+
+* checks collection;
+* creates collection;
+* stores vectors;
+* performs similarity search.
+
+## MCP Server
+
+Start MCP:
+
+```bash
+npm run mcp
+```
+
+Available tools:
+
+```
+get_forum_info
+
+get_post
+
+get_topic
+
+get_user
+
+search_knowledge
+```
+
+Example:
+
+```
+search_knowledge
+
+{
+ "query": "installation guide",
+ "limit": 5
+}
+```
+
+## Project Structure
+
+```
+.
+├── library.js
+
+├── package.json
+
+├── plugin.json
+
+├── src
+
+│   ├── ai
+
+│   │   ├── embeddings.js
+
+│   │   ├── openai.js
+
+│   │   ├── qdrant.js
+
+│   │   ├── indexer.js
+
+│   │   └── search.js
+
+│   │
+
+│   ├── mcp
+
+│   │   ├── server.js
+
+│   │   └── tools.js
+
+│   │
+
+│   ├── nodebb
+
+│   │   ├── meta.js
+
+│   │   ├── posts.js
+
+│   │   ├── topics.js
+
+│   │   └── users.js
+
+│   │
+
+│   └── config
+
+│       └── index.js
+
+│
+
+└── test
+
+    └── plugin.test.js
+```
+
+## Security
+
+Never commit:
+
+```
+.env
+
+OPENAI_API_KEY
+
+NODEBB_API_KEY
+```
+
+## License
+
+MIT

package/README.ru.md

@@ -0,0 +1,347 @@
+# NodeBB Integration Layer
+
+AI-слой интеграции для форумов NodeBB с поддержкой MCP, семантического поиска, RAG pipeline и векторного хранилища Qdrant.
+
+## Возможности
+
+* Интеграция с NodeBB
+* MCP (Model Context Protocol) сервер
+* Семантический поиск по содержимому форума
+* RAG pipeline (Retrieval Augmented Generation)
+* Поддержка Qdrant Vector Database
+* Поддержка OpenAI Embeddings
+* Локальный режим с fake embeddings
+* Работа без NodeBB для разработки
+* Автоматические тесты через GitHub Actions
+
+# Архитектура
+
+```
+                 NodeBB
+
+                   |
+                   |
+
+          Integration Layer
+
+                   |
+
+      +------------+------------+
+
+      |                         |
+
+     MCP                       AI
+
+      |                         |
+
+   Tools API              Embeddings
+
+                                  |
+
+                                Qdrant
+
+                                  |
+
+                           Knowledge Base
+```
+
+# Требования
+
+Минимально:
+
+* Node.js >= 20
+* npm >= 10
+
+Опционально:
+
+* NodeBB
+* Redis
+* Qdrant
+* OpenAI API
+
+# Установка
+
+Клонирование:
+
+```bash
+git clone https://github.com/Sergey-ek/nodebb-plugin-integration.git
+
+cd nodebb-plugin-integration
+```
+
+Установка зависимостей:
+
+```bash
+npm install
+```
+
+Создание конфигурации:
+
+```bash
+cp .env.example .env
+```
+
+# Режим разработки
+
+По умолчанию используется локальный генератор векторов:
+
+```
+AI_PROVIDER=fake
+```
+
+Этот режим позволяет запускать проект без:
+
+* OpenAI API
+* Qdrant
+* NodeBB
+
+Проверка конфигурации:
+
+```bash
+npm run diagnose
+```
+
+Пример:
+
+```
+{
+ environment: "development",
+
+ embeddings:
+ {
+   provider: "fake",
+   size: 1536
+ }
+}
+```
+
+# Тестирование
+
+Проверка синтаксиса:
+
+```bash
+npm run check
+```
+
+Запуск тестов:
+
+```bash
+npm test
+```
+
+Ожидаемый результат:
+
+```
+8 passing
+```
+
+# Интеграция с NodeBB
+
+Настройка:
+
+```
+NODEBB_URL=http://localhost:4567
+
+NODEBB_API_KEY=your_token
+```
+
+При работе внутри NodeBB используются оригинальные модули NodeBB.
+
+В standalone режиме используются безопасные адаптеры:
+
+```
+NodeBB отсутствует
+
+        |
+
+Fallback adapter
+
+        |
+
+Тесты продолжают работать
+```
+
+# AI Pipeline
+
+Полный поток:
+
+```
+Сообщение форума
+
+        |
+
+Создание embedding
+
+        |
+
+Сохранение vector
+
+        |
+
+Qdrant similarity search
+
+        |
+
+Получение контекста
+
+        |
+
+AI ответ
+```
+
+# Embeddings
+
+## Fake режим
+
+Для разработки:
+
+```
+AI_PROVIDER=fake
+```
+
+Плюсы:
+
+* бесплатно;
+* быстро;
+* не требует сети;
+* используется в тестах.
+
+## OpenAI режим
+
+Настройка:
+
+```
+AI_PROVIDER=openai
+
+OPENAI_API_KEY=your_key
+```
+
+# Qdrant
+
+Конфигурация:
+
+```
+QDRANT_URL=http://localhost:6333
+
+QDRANT_COLLECTION=nodebb_knowledge
+```
+
+Автоматически выполняется:
+
+* проверка коллекции;
+* создание коллекции;
+* загрузка векторов;
+* поиск похожих документов.
+
+# MCP сервер
+
+Запуск:
+
+```bash
+npm run mcp
+```
+
+Доступные инструменты:
+
+```
+get_forum_info
+
+get_post
+
+get_topic
+
+get_user
+
+search_knowledge
+```
+
+Пример поиска:
+
+```
+search_knowledge
+
+{
+ "query": "как установить NodeBB",
+ "limit": 5
+}
+```
+
+# Структура проекта
+
+```
+.
+
+├── library.js
+
+├── package.json
+
+├── plugin.json
+
+
+├── src
+
+│
+
+├── ai
+
+│   ├── embeddings.js
+
+│   ├── openai.js
+
+│   ├── qdrant.js
+
+│   ├── indexer.js
+
+│   └── search.js
+
+
+│
+
+├── mcp
+
+│   ├── server.js
+
+│   └── tools.js
+
+
+│
+
+├── nodebb
+
+│   ├── meta.js
+
+│   ├── posts.js
+
+│   ├── topics.js
+
+│   └── users.js
+
+
+│
+
+└── config
+
+    └── index.js
+
+
+└── test
+
+    └── plugin.test.js
+```
+
+# Безопасность
+
+Не добавлять в Git:
+
+```
+.env
+
+OPENAI_API_KEY
+
+NODEBB_API_KEY
+
+```
+
+# Лицензия
+
+MIT