Onyx-MCP-Server

Onyx MCP Server

Ein Model Context Protocol (MCP)-Server für die nahtlose Integration mit Onyx AI-Wissensdatenbanken.

Dieser MCP-Server verbindet jeden MCP-kompatiblen Client mit Ihrer Onyx-Wissensdatenbank und ermöglicht Ihnen die Suche und den Abruf relevanter Kontexte in Ihren Dokumenten. Er bildet eine Brücke zwischen MCP-Clients und der Onyx-API und ermöglicht leistungsstarke semantische Such- und Chatfunktionen.

Merkmale

Erweiterte Suche : Semantische Suche in Ihren Onyx-Dokumentensätzen mit LLM-Relevanzfilterung
Kontextfensterabruf : Rufen Sie Blöcke oberhalb und unterhalb des passenden Blocks ab, um einen besseren Kontext zu erhalten
Vollständiger Dokumentabruf : Option zum Abrufen ganzer Dokumente statt nur von Teilen
Chat-Integration : Nutzen Sie die leistungsstarke Chat-API von Onyx mit LLM + RAG für umfassende Antworten
Konfigurierbare Dokumentsatzfilterung : Zielen Sie auf bestimmte Dokumentsätze, um relevantere Ergebnisse zu erzielen

Installation

Installation über Smithery

So installieren Sie Onyx MCP Server für Claude Desktop automatisch über Smithery :

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

Voraussetzungen

Node.js (v16 oder höher)
Eine Onyx-Instanz mit API-Zugriff
Ein Onyx-API-Token

Aufstellen

Klonen Sie das Repository:
git clone https://github.com/lupuletic/onyx-mcp-server.git cd onyx-mcp-server
Installieren Sie Abhängigkeiten:
npm install
Erstellen Sie den Server:
npm run build
Konfigurieren Sie Ihr Onyx-API-Token:
export ONYX_API_TOKEN="your-api-token-here" export ONYX_API_URL="http://localhost:8080/api" # Adjust as needed
Starten Sie den Server:
npm start

Konfigurieren von MCP-Clients

Für Claude Desktop App

Zu ~/Library/Application Support/Claude/claude_desktop_config.json hinzufügen:

{
  "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": []
    }
  }
}

Für Claude in VSCode (Cline)

Fügen Sie Ihrer Cline MCP-Einstellungsdatei Folgendes hinzu:

{
  "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": []
    }
  }
}

Für andere MCP-Clients

Informationen zum Hinzufügen eines benutzerdefinierten MCP-Servers finden Sie in der Dokumentation Ihres MCP-Clients. Sie benötigen Folgendes:

Der Befehl zum Ausführen des Servers ( node )
Der Pfad zur erstellten Serverdatei ( /path/to/onyx-mcp-server/build/index.js )
Umgebungsvariablen für ONYX_API_TOKEN und ONYX_API_URL

Verfügbare Tools

Nach der Konfiguration hat Ihr MCP-Client Zugriff auf zwei leistungsstarke Tools:

1. Suchwerkzeug

Das Tool search_onyx bietet direkten Zugriff auf die Suchfunktionen von Onyx mit erweiterter Kontextabfrage:

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

Parameter:

query (erforderlich): Das zu suchende Thema
documentSets (optional): Liste der Dokumentsatznamen, in denen gesucht werden soll (für alle leer)
maxResults (optional): Maximale Anzahl der zurückzugebenden Ergebnisse (Standard: 5, Max: 10)
chunksAbove (optional): Anzahl der Chunks, die über dem passenden Chunk eingefügt werden sollen (Standard: 1)
chunksBelow (optional): Anzahl der Chunks, die unterhalb des passenden Chunks eingefügt werden sollen (Standard: 1)
retrieveFullDocuments (optional): Ob vollständige Dokumente statt nur Teile abgerufen werden sollen (Standard: „false“)

2. Chat-Tool

Das Tool chat_with_onyx nutzt die leistungsstarke Chat-API von Onyx mit LLM + RAG für umfassende Antworten:

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

Parameter:

query (erforderlich): Die Frage, die Onyx gestellt werden soll
personaId (optional): Die ID der zu verwendenden Persona (Standard: 15)
documentSets (optional): Liste der Dokumentsatznamen, in denen gesucht werden soll (für alle leer)
chatSessionId (optional): Vorhandene Chat-Sitzungs-ID zum Fortsetzen einer Unterhaltung

Chat-Sitzungen

Das Chat-Tool unterstützt die Aufrechterhaltung des Konversationskontexts über mehrere Interaktionen hinweg. Nach dem ersten Aufruf enthält die Antwort eine chat_session_id in den Metadaten. Sie können diese ID in nachfolgenden Aufrufen weitergeben, um den Kontext beizubehalten.

Auswählen zwischen Suche und Chat

Verwenden Sie die Suche, wenn : Sie bestimmte, zielgerichtete Informationen aus Dokumenten benötigen und genau steuern möchten, wie viel Kontext abgerufen wird.
Verwenden Sie den Chat, wenn : Sie umfassende Antworten benötigen, die Informationen aus mehreren Quellen kombinieren, oder wenn Sie möchten, dass der LLM Informationen für Sie zusammenfasst.

Die besten Ergebnisse erzielen Sie, wenn Sie beide Tools in Kombination verwenden: Suchen Sie nach bestimmten Details und chatten Sie, um ein umfassendes Verständnis zu erhalten.

Anwendungsfälle

Wissensmanagement : Greifen Sie über jede MCP-kompatible Schnittstelle auf die Wissensdatenbank Ihres Unternehmens zu
Kundensupport : Helfen Sie Supportmitarbeitern, schnell relevante Informationen zu finden
Recherche : Führen Sie eine gründliche Recherche der Dokumente Ihrer Organisation durch
Schulung : Gewähren Sie Zugriff auf Schulungsmaterialien und Dokumentation
Richtlinieneinhaltung : Stellen Sie sicher, dass die Teams Zugriff auf die neuesten Richtlinien und Verfahren haben

Entwicklung

Ausführen im Entwicklungsmodus

npm run dev

Änderungen übernehmen

Dieses Projekt setzt die Conventional-Commits -Spezifikation für alle Commit-Nachrichten um. Um dies zu vereinfachen, stellen wir ein interaktives Commit-Tool zur Verfügung:

npm run commit

Dies führt Sie durch die Erstellung einer korrekt formatierten Commit-Nachricht. Alternativ können Sie Ihre eigenen Commit-Nachrichten im herkömmlichen Format verfassen:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Wobei type einer der folgenden ist: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Bauen für die Produktion

npm run build

Testen

Führen Sie die Testsuite aus:

npm test

Führen Sie Tests mit Abdeckung durch:

npm run test:coverage

Fusseln

npm run lint

Beheben Sie Linting-Probleme:

npm run lint:fix

Kontinuierliche Integration

Dieses Projekt nutzt GitHub Actions für kontinuierliche Integration und Bereitstellung. Die CI-Pipeline wird bei jedem Push in den Hauptzweig und bei Pull Requests ausgeführt. Sie führt die folgenden Prüfungen durch:

Fusseln
Gebäude
Testen
Berichterstellung zur Codeabdeckung

Automatisiertes Versions-Bumping und -Publizieren

Wenn ein PR mit dem Hauptzweig zusammengeführt wird, ermittelt das Projekt automatisch den entsprechenden Versionstyp und veröffentlicht ihn in npm. Das System analysiert sowohl PR-Titel als auch Commit-Nachrichten, um den Versionstyp zu bestimmen.

PR-Titelvalidierung : Alle PR-Titel werden anhand der Spezifikation „Conventional Commits“ validiert:
- PR-Titel müssen mit einem Typ beginnen (z. B. feat:``fix:``docs:
- Diese Validierung erfolgt automatisch, wenn ein PR erstellt oder aktualisiert wird.
- PRs mit ungültigen Titeln schlagen bei der Validierungsprüfung fehl
Validierung von Commit-Nachrichten : Alle Commit-Nachrichten werden auch anhand des herkömmlichen Commit-Formats validiert:
- Commit-Nachrichten müssen mit einem Typ beginnen (z. B. feat: , fix: , docs: )
- Dies wird durch Git-Hooks erzwungen, die ausgeführt werden, wenn Sie committen
- Commits mit ungültigen Nachrichten werden abgelehnt
- Verwenden Sie npm run commit für ein interaktives Tool zur Erstellung von Commit-Nachrichten
Bestimmung der Versionserhöhung : Das System analysiert sowohl den PR-Titel als auch die Commit-Nachrichten, um die entsprechende Versionserhöhung zu bestimmen:
- PR-Titel, die mit feat beginnen oder neue Funktionen enthalten → geringfügige Versionsverbesserung
- PR-Titel, die mit fix beginnen oder Fehlerbehebungen enthalten → Patch-Versionserhöhung
- PR-Titel mit BREAKING CHANGE oder mit einem Ausrufezeichen → wichtiger Versionssprung
- Wenn der PR-Titel keinen bestimmten Bump-Typ angibt, analysiert das System Commit-Nachrichten
- Es wird der Bump-Typ mit der höchsten Priorität verwendet, der in einer Commit-Nachricht gefunden wurde (Major > Minor > Patch).
- Wenn keine herkömmlichen Commit-Präfixe gefunden werden, führt das System automatisch einen Patch-Versions-Bump aus, ohne dass es zu einem Fehler kommt.
Versionsaktualisierung und Veröffentlichung :
- Erhöht die Version in package.json entsprechend der semantischen Versionierung
- Committet und pusht die Versionsänderung
- Veröffentlicht die neue Version auf npm

Dieser automatisierte Prozess gewährleistet eine konsistente Versionierung basierend auf der Art der Änderungen, folgt den Prinzipien der semantischen Versionierung und macht die manuelle Versionsverwaltung überflüssig.

Beitragen

Beiträge sind willkommen! Weitere Informationen finden Sie in unserem Leitfaden für Beiträge .

Sicherheit

Wenn Sie eine Sicherheitslücke entdecken, befolgen Sie bitte unsere Sicherheitsrichtlinie .

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert – Einzelheiten finden Sie in der Datei LICENSE .

onyx-mcp-server

Integrations