AI导哈

知识库搜索服务器

Onyx MCP服务器是一个模型上下文协议服务器，用于无缝集成Onyx AI知识库，提供语义搜索和聊天功能。

  • by lupuletic
  • TypeScript
  • 本地部署
  • 27 星标
  • 更新于
在 GitHub 查看 lupuletic/onyx-mcp-server

使用说明

Onyx MCP服务器

用于与Onyx AI知识库无缝集成的模型上下文协议（MCP）服务器。

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

特性

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

安装

通过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（克莱恩）

添加到您的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 该工具利用Onyx强大的聊天API和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 （可选）：要使用的角色的ID（默认值：15）
  • documentSets （可选）：要搜索的文档集名称列表（全部为空）
  • chatSessionId （可选）：现有聊天会话ID以继续对话

聊天会话

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

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

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

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

用例

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

发展

以开发模式运行

npm run dev

提交更改

该项目执行 常规承诺 所有提交消息的规范。为了使这更容易，我们提供了一个交互式提交工具：

npm run commit

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

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

哪里 type 是以下之一：feat、fix、docs、style、重构、perf、测试、构建、ci、chore、revert

生产大楼

npm run build

测试

运行测试套件：

npm test

运行覆盖率测试：

npm run test:coverage

代码检查

npm run lint

修复掉毛问题：

npm run lint:fix

持续集成

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

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

自动版本缓冲和发布

当PR合并到主分支时，项目会自动确定适当的版本碰撞类型并发布到npm。系统分析PR标题和提交消息，以确定版本冲突类型。

  1. PR标题验证：所有PR标题均根据 常规承诺 规范：

    • 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许可证获得许可-请参阅 许可证 文件以获取详细信息。

相关 MCP