Сервер Onyx MCP

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

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

Функции

• Расширенный поиск : семантический поиск по всем наборам документов Onyx с фильтрацией по релевантности LLM

• Извлечение контекстного окна : извлечение фрагментов выше и ниже соответствующего фрагмента для лучшего контекста.

• Извлечение всего документа : возможность извлечения целых документов, а не только их частей.

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

• Настраиваемая фильтрация наборов документов : выбор определенных наборов документов для получения более релевантных результатов.

Related MCP server: atlas_mcp

Установка

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

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

npx -y @smithery/cli install @lupuletic/onyx-mcp-server --client claude

Предпосылки

• 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 :

{
  "mcpServers": {
    "onyx-search": {
      "command": "node",
      "args": ["/path/to/onyx-mcp-server/build/index.js"],
      "env": {
        "ONYX_API_TOKEN": "your-api-token-here",
        "ONYX_API_URL": "http://localhost:8080/api"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

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

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

{
  "mcpServers": {
    "onyx-search": {
      "command": "node",
      "args": ["/path/to/onyx-mcp-server/build/index.js"],
      "env": {
        "ONYX_API_TOKEN": "your-api-token-here",
        "ONYX_API_URL": "http://localhost:8080/api"
      },
      "disabled": false, 
      "alwaysAllow": []
    }
  }
}

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

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

• Команда для запуска сервера ( node )

• Путь к файлу собранного сервера ( /path/to/onyx-mcp-server/build/index.js )

• Переменные среды для ONYX_API_TOKEN и ONYX_API_URL

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

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

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

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

<use_mcp_tool>
<server_name>onyx-search</server_name>
<tool_name>search_onyx</tool_name>
<arguments>
{
  "query": "customer onboarding process",
  "documentSets": ["Company Policies", "Training Materials"],
  "maxResults": 3,
  "chunksAbove": 1,
  "chunksBelow": 1,
  "retrieveFullDocuments": true
}
</arguments>
</use_mcp_tool>

Параметры:

• query (обязательно): Тема для поиска

• documentSets (необязательно): список названий наборов документов для поиска (пусто для всех)

• maxResults (необязательно): максимальное количество возвращаемых результатов (по умолчанию: 5, максимум: 10)

• chunksAbove (необязательно): количество фрагментов, которые следует включить выше соответствующего фрагмента (по умолчанию: 1)

• chunksBelow (необязательно): количество фрагментов, которые следует включить под соответствующим фрагментом (по умолчанию: 1)

• retrieveFullDocuments (необязательно): следует ли извлекать полные документы, а не только фрагменты (по умолчанию: false)

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

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

<use_mcp_tool>
<server_name>onyx-search</server_name>
<tool_name>chat_with_onyx</tool_name>
<arguments>
{
  "query": "What is our company's policy on remote work?",
  "personaId": 15,
  "documentSets": ["Company Policies", "HR Documents"],
  "chatSessionId": "optional-existing-session-id"
}
</arguments>
</use_mcp_tool>

Параметры:

• query (обязательно): Вопрос, который нужно задать Ониксу

• personaId (необязательно): идентификатор персоны для использования (по умолчанию: 15)

• documentSets (необязательно): список названий наборов документов для поиска (пусто для всех)

• chatSessionId (необязательно): существующий идентификатор сеанса чата для продолжения разговора

Чат-сессии

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

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

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

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

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

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

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

• Поддержка клиентов : помогите агентам службы поддержки быстро найти нужную информацию.

• Исследование : проведите глубокое исследование документов вашей организации.

• Обучение : Предоставить доступ к учебным материалам и документации.

• Соблюдение политик : обеспечьте командам доступ к последним политикам и процедурам.

Разработка

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

npm run dev

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

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

npm run commit

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

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

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

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

npm run build

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

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

npm test

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

npm run test:coverage

Линтинг

npm run lint

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

npm run lint:fix

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

Этот проект использует 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 .