Onyx MCP Server

Onyx MCP サーバー

Onyx AI ナレッジベースとのシームレスな統合を実現する Model Context Protocol（MCP）サーバーです。

この MCP サーバーは、MCP 互換のあらゆるクライアントをあなたの Onyx ナレッジベースに接続し、ドキュメントから関連するコンテキストを検索・取得できるようにします。MCP クライアントと Onyx API の橋渡しを提供し、強力なセマンティック検索とチャット機能を実現します。

機能

• 強化された検索: LLM による関連性フィルタリングを備えた、Onyx ドキュメントセット全体のセマンティック検索
• コンテキストウィンドウの取得: より良いコンテキストのために、一致したチャンクの前後のチャンクを取得
• ドキュメント全体の取得: チャンクだけでなくドキュメント全体を取得するオプション
• チャット統合: LLM + RAG による Onyx の強力なチャット API を使用して、包括的な回答を取得
• 設定可能なドキュメントセットのフィルタリング: 特定のドキュメントセットを対象にして、より関連性の高い結果を取得

インストール

Smithery 経由でのインストール

Smithery を使用して、Claude Desktop 用の Onyx MCP サーバーを自動的にインストールするには:

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

前提条件

• Node.js（v16 以上）
• API アクセスが可能な Onyx インスタンス
• Onyx API トークン

セットアップ

1. リポジトリをクローンします:

   git clone https://github.com/lupuletic/onyx-mcp-server.git
   cd onyx-mcp-server
   

2. 依存関係をインストールします:

   npm install
   

3. サーバーをビルドします:

   npm run build
   

4. Onyx API トークンを設定します:

   export ONYX_API_TOKEN="your-api-token-here"
   export ONYX_API_URL="http://localhost:8080/api"  # Adjust as needed
   

5. サーバーを起動します:

   npm start
   

MCP クライアントの設定

Claude デスクトップアプリの場合

~/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 上の Claude（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 クライアントは 2 つの強力なツールにアクセスできるようになります:

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 ツールは、LLM + RAG による Onyx の強力なチャット API を活用して、包括的な回答を提供します:

<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（必須）: Onyx に尋ねる質問
• personaId（任意）: 使用するペルソナの ID（デフォルト: 15）
• documentSets（任意）: 検索対象とするドキュメントセット名のリスト（すべてを対象にする場合は空）
• chatSessionId（任意）: 会話を続けるための既存のチャットセッション ID

チャットセッション

チャットツールは、複数のやり取りにわたって会話のコンテキストを維持することをサポートしています。最初の呼び出しの後、レスポンスのメタデータに chat_session_id が含まれます。この 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 パイプラインは、main ブランチへのプッシュごと、およびプルリクエストごとに実行されます。以下のチェックを実施します:

• リンティング
• ビルド
• テスト
• コードカバレッジのレポート

バージョンの自動バンプと公開

PR がメインブランチにマージされると、プロジェクトは適切なバージョンバンプの種類を自動的に判断し、npm に公開します。このシステムは、PR のタイトルとコミットメッセージの両方を分析して、バージョンバンプの種類を決定します。

1. PR タイトルの検証: すべての PR タイトルは Conventional Commits 仕様に照らして検証されます：

   • PR タイトルはタイプ（例：feat:、fix:、docs:）で始まる必要があります
   • この検証は、PR が作成または更新されたときに自動的に実行されます
   • 無効なタイトルの PR は検証チェックに失敗します

2. コミットメッセージの検証: すべてのコミットメッセージも conventional commits 形式に照らして検証されます：

   • コミットメッセージはタイプ（例：feat:、fix:、docs:）で始まる必要があります
   • これは、コミット時に実行される git フックによって強制されます
   • 無効なメッセージのコミットは拒否されます
   • 対話形式のコミットメッセージ作成ツールには npm run commit を使用してください

3. バージョンバンプの決定: このシステムは、PR タイトルとコミットメッセージの両方を分析して、適切なバージョンバンプを決定します：

   • feat で始まる、または新機能を含む PR タイトル → マイナーバージョンバンプ
   • fix で始まる、またはバグ修正を含む PR タイトル → パッチバージョンバンプ
   • BREAKING CHANGE を含む、または感嘆符が付いた PR タイトル → メジャーバージョンバンプ
   • PR タイトルが特定のバンプの種類を示していない場合、システムはコミットメッセージを分析します
   • いずれかのコミットメッセージで見つかった最も優先度の高いバンプの種類が使用されます（major > minor > patch）
   • conventional commit のプレフィックスが見つからない場合、システムは失敗させることなく、自動的にパッチバージョンバンプをデフォルトとします

4. バージョンの更新と公開:

   • セマンティックバージョニングに従って package.json のバージョンをバンプします
   • バージョン変更をコミットしてプッシュします
   • 新しいバージョンを npm に公開します

この自動化されたプロセスにより、変更の性質に基づいた一貫したバージョニングがセマンティックバージョニングの原則に従って保証され、手動でのバージョン管理が不要になります。

コントリビューション

コントリビューションを歓迎します！詳細については、コントリビューションガイドをご覧ください。

セキュリティ

セキュリティ脆弱性を発見した場合は、セキュリティポリシーに従ってください。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています - 詳細については LICENSE ファイルをご覧ください。