onyx-mcp-server

Сервер Onyx MCP

Сервер протокола контекста модели (MCP) для бесшовной интеграции с базами знаний Onyx AI.

Этот сервер MCP подключает любой клиент, совместимый с MCP, к вашей базе знаний Onyx, позволяя вам искать и извлекать соответствующий контекст из ваших документов. Он обеспечивает мост между клиентами MCP и API Onyx, обеспечивая мощные возможности семантического поиска и чата.

Функции

• Расширенный поиск : семантический поиск по всем наборам документов Onyx с фильтрацией по релевантности LLM
• Извлечение контекстного окна : извлечение фрагментов выше и ниже соответствующего фрагмента для лучшего контекста.
• Извлечение всего документа : возможность извлечения целых документов, а не только их частей.
• Интеграция чата : используйте мощный API чата Onyx с LLM + RAG для получения исчерпывающих ответов
• Настраиваемая фильтрация наборов документов : выбор определенных наборов документов для получения более релевантных результатов.

Установка

Установка через Smithery

Чтобы автоматически установить Onyx MCP Server для Claude Desktop через Smithery :

Предпосылки

• Node.js (v16 или выше)
• Экземпляр Onyx с доступом к API
• Токен API Onyx

Настраивать

1. Клонируйте репозиторий:
   git clone https://github.com/lupuletic/onyx-mcp-server.git cd onyx-mcp-server
2. Установить зависимости:
   npm install
3. Сборка сервера:
   npm run build
4. Настройте свой токен API Onyx:
   export ONYX_API_TOKEN="your-api-token-here" export ONYX_API_URL="http://localhost:8080/api" # Adjust as needed
5. Запустите сервер:
   npm start

Настройка клиентов MCP

Для приложения Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json :

Для Клода в VSCode (Cline)

Добавьте в файл настроек Cline MCP:

Для других клиентов MCP

Обратитесь к документации вашего клиента MCP, чтобы узнать, как добавить пользовательский сервер MCP. Вам нужно будет предоставить:

• Команда для запуска сервера ( node )
• Путь к файлу собранного сервера ( /path/to/onyx-mcp-server/build/index.js )
• Переменные среды для ONYX_API_TOKEN и ONYX_API_URL

Доступные инструменты

После настройки ваш клиент MCP получит доступ к двум мощным инструментам:

1. Инструмент поиска

Инструмент search_onyx обеспечивает прямой доступ к возможностям поиска Onyx с улучшенным контекстным поиском:

Параметры:

• query (обязательно): Тема для поиска
• documentSets (необязательно): список названий наборов документов для поиска (пусто для всех)
• maxResults (необязательно): максимальное количество возвращаемых результатов (по умолчанию: 5, максимум: 10)
• chunksAbove (необязательно): количество фрагментов, которые следует включить выше соответствующего фрагмента (по умолчанию: 1)
• chunksBelow (необязательно): количество фрагментов, которые следует включить под соответствующим фрагментом (по умолчанию: 1)
• retrieveFullDocuments (необязательно): следует ли извлекать полные документы, а не только фрагменты (по умолчанию: false)

2. Инструмент чата

Инструмент chat_with_onyx использует мощный API чата Onyx с LLM + RAG для получения исчерпывающих ответов:

Параметры:

• query (обязательно): Вопрос, который нужно задать Ониксу
• personaId (необязательно): идентификатор персоны для использования (по умолчанию: 15)
• documentSets (необязательно): список названий наборов документов для поиска (пусто для всех)
• chatSessionId (необязательно): существующий идентификатор сеанса чата для продолжения разговора

Чат-сессии

Инструмент чата поддерживает сохранение контекста разговора в нескольких взаимодействиях. После первого вызова ответ будет включать chat_session_id в метаданных. Вы можете передавать этот идентификатор в последующих вызовах для сохранения контекста.

Выбор между поиском и чатом

• Используйте поиск, когда : вам нужна конкретная, целевая информация из документов, и вы хотите точно контролировать объем извлекаемого контекста.
• Используйте чат, когда : Вам нужны исчерпывающие ответы, объединяющие информацию из нескольких источников, или когда вы хотите, чтобы LLM синтезировал информацию для вас.

Для достижения наилучших результатов вы можете использовать оба инструмента одновременно — ищите конкретные детали и общайтесь в чате для получения всестороннего понимания.

Варианты использования

• Управление знаниями : доступ к базе знаний вашей организации через любой совместимый с MCP интерфейс.
• Поддержка клиентов : помогите агентам службы поддержки быстро найти нужную информацию.
• Исследование : проведите глубокое исследование документов вашей организации.
• Обучение : Предоставить доступ к учебным материалам и документации.
• Соблюдение политик : обеспечьте командам доступ к последним политикам и процедурам.

Разработка

Работа в режиме разработки

Внесение изменений

Этот проект обеспечивает спецификацию Conventional Commits для всех сообщений о коммитах. Чтобы сделать это проще, мы предоставляем интерактивный инструмент для коммитов:

Это поможет вам создать правильно отформатированное сообщение о коммите. В качестве альтернативы вы можете написать свои собственные сообщения о коммите, следуя общепринятому формату:

Где type может быть одним из: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Здание для производства

Тестирование

Запустите тестовый набор:

Запустите тесты с покрытием:

Линтинг

Исправление проблем с линтингом:

Непрерывная интеграция

Этот проект использует GitHub Actions для непрерывной интеграции и развертывания. CI-конвейер запускается при каждом push-е в основную ветку и при pull-запросах. Он выполняет следующие проверки:

• Линтинг
• Здание
• Тестирование
• Отчетность о покрытии кода

Автоматизированное обновление и публикация версий

Когда PR объединяется с основной веткой, проект автоматически определяет соответствующий тип версии bump и публикует в npm. Система анализирует как заголовки PR, так и сообщения о коммитах, чтобы определить тип версии bump.

1. Проверка заголовка PR : Все заголовки PR проверяются на соответствие спецификации Conventional Commits :
   • Заголовки PR должны начинаться с типа (например, feat: , fix: , docs: )
   • Эта проверка происходит автоматически при создании или обновлении PR.
   • PR с недействительными названиями не пройдут проверку.
2. Проверка сообщения о коммите : Все сообщения о коммитах также проверяются на соответствие общепринятому формату коммитов:
   • Сообщения о коммитах должны начинаться с типа (например, feat: , fix: , docs: )
   • Это обеспечивается хуками git, которые запускаются при коммите.
   • Коммиты с недействительными сообщениями будут отклонены.
   • Используйте npm run commit для интерактивного инструмента создания сообщений о коммите
3. Определение повышения версии : система анализирует как заголовок PR, так и сообщения о фиксации, чтобы определить соответствующую повышение версии:
   • PR-титулы, начинающиеся с feat или содержащие новые функции → повышение младшей версии
   • Заголовки PR, начинающиеся с fix или содержащие исправления ошибок → повышение версии патча
   • Заголовки PR, содержащие BREAKING CHANGE или восклицательный знак → обновление основной версии
   • Если заголовок PR не указывает на конкретный тип повышения, система анализирует сообщения о коммитах
   • Используется тип исправления с наивысшим приоритетом, найденный в любом сообщении о фиксации (основной > второстепенный > исправление).
   • Если не найдено ни одного обычного префикса для фиксации, система автоматически переходит к версии исправления по умолчанию без сбоев.
4. Обновление и публикация версии :
   • Увеличивает версию в package.json в соответствии с семантическим версионированием
   • Фиксирует и отправляет изменение версии
   • Публикует новую версию в npm

Этот автоматизированный процесс обеспечивает единообразное управление версиями на основе характера изменений, следуя принципам семантического управления версиями, и исключает ручное управление версиями.

Внося вклад

Вклады приветствуются! Более подробную информацию см. в нашем Руководстве по вкладам .

Безопасность

Если вы обнаружили уязвимость системы безопасности, следуйте нашей Политике безопасности .

Лицензия

Данный проект лицензирован по лицензии MIT — подробности см. в файле LICENSE .