Onyx MCP 服务器

模型上下文协议 (MCP) 服务器可与 Onyx AI 知识库无缝集成。

此 MCP 服务器可将任何兼容 MCP 的客户端连接到您的 Onyx 知识库，让您能够搜索并检索文档中的相关上下文。它为 MCP 客户端和 Onyx API 之间搭建了桥梁，从而实现强大的语义搜索和聊天功能。

特征

• 增强搜索：使用 LLM 相关性过滤功能对 Onyx 文档集进行语义搜索
• 上下文窗口检索：检索匹配块上方和下方的块以获得更好的上下文
• 完整文档检索：可以选择检索整个文档，而不是只检索部分文档
• 聊天集成：使用 Onyx 强大的聊天 API 与 LLM + RAG 获得全面的答案
• 可配置文档集过滤：针对特定文档集获取更相关的结果

安装

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装 Onyx MCP Server：

先决条件

• 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 客户端

对于克劳德桌面应用程序

添加到~/Library/Application Support/Claude/claude_desktop_config.json ：

VSCode 中的 Claude（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工具利用 Onyx 强大的聊天 API 与 LLM + RAG 来提供全面的答案：

参数：

• query （必填）：向 Onyx 询问的问题
• personaId （可选）：要使用的角色的 ID（默认值：15）
• documentSets （可选）：要搜索的文档集名称列表（全部为空）
• chatSessionId （可选）：用于继续对话的现有聊天会话 ID

聊天会话

聊天工具支持在多次交互中维护对话上下文。首次调用后，响应将在元数据中包含一个chat_session_id 。您可以在后续调用中传递此 ID 来维护上下文。

在搜索和聊天之间进行选择

• 使用搜索的情况：您需要从文档中获取特定的、有针对性的信息，并希望精确控制检索到的上下文量。
• 使用聊天的情况：您需要结合来自多个来源的信息的综合答案，或者当您希望 LLM 为您综合信息时。

为了获得最佳效果，您可以结合使用这两种工具 - 搜索具体细节并通过聊天获得全面了解。

用例

• 知识管理：通过任何与 MCP 兼容的界面访问您组织的知识库
• 客户支持：帮助支持代理快速找到相关信息
• 研究：对组织内的文档进行深入研究
• 培训：提供培训材料和文档
• 政策合规性：确保团队能够了解最新的政策和程序

发展

以开发模式运行

提交更改

本项目强制所有提交信息遵循约定式提交规范。为了方便使用，我们提供了一个交互式提交工具：

这将指导您创建格式正确的提交消息。或者，您可以按照常规格式编写自己的提交消息：

其中type为以下之一：feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert

生产环境构建

测试

运行测试套件：

运行覆盖测试：

代码检查

修复 linting 问题：

持续集成

该项目使用 GitHub Actions 进行持续集成和部署。CI 流水线会在每次推送到主分支以及拉取请求时运行。它会执行以下检查：

• 代码检查
• 建筑
• 测试
• 代码覆盖率报告

自动版本升级和发布

当 PR 合并到主分支时，项目会自动确定合适的版本升级类型并发布到 npm。系统会分析 PR 标题和提交信息来确定版本升级类型。

1. PR 标题验证：所有 PR 标题均根据常规提交规范进行验证：
   • PR 标题必须以类型开头（例如feat: 、 fix: 、 docs: ）
   • 创建或更新 PR 时会自动进行此验证
   • 标题无效的 PR 将无法通过验证检查
2. 提交消息验证：所有提交消息也都根据常规提交格式进行验证：
   • 提交消息必须以类型开头（例如， feat: 、 fix: 、 docs: ）
   • 这是由提交时运行的 git hooks 强制执行的
   • 包含无效信息的提交将被拒绝
   • 使用npm run commit作为交互式提交消息创建工具
3. 版本升级确定：系统分析 PR 标题和提交消息以确定适当的版本升级：
   • PR 标题以feat开头或包含新功能 → 小版本升级
   • PR 标题以fix开头或包含错误修复 → patch 版本升级
   • PR 标题包含BREAKING CHANGE或感叹号 → 主要版本升级
   • 如果 PR 标题未指明具体的 bump 类型，系统会分析提交消息
   • 使用在任何提交消息中找到的最高优先级的 bump 类型（主要 > 次要 > 补丁）
   • 如果没有找到常规提交前缀，系统将自动默认使用补丁版本升级，而不会失败
4. 版本更新与发布：
   • 根据语义版本控制来调整 package.json 中的版本
   • 提交并推送版本变更
   • 将新版本发布到 npm

此自动化过程可确保根据变化的性质进行一致的版本控制，遵循语义版本控制原则，并消除手动版本管理。

贡献

欢迎贡献！更多详情请参阅我们的贡献指南。

安全

如果您发现安全漏洞，请遵循我们的安全政策。

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。