Onyx MCP Server

](https://mseep.ai/app/lupuletic-onyx-mcp-server)

Onyx MCP服务器

 ](https://www.npmjs.com/package/onyx-mcp-server) ](https://www.npmjs.com/package/onyx-mcp-server) ](https://smithery.ai/server/@lupuletic/onyx-mcp-server) 

用于与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

1. 安装依赖项：

   npm install

1. 构建服务器：

   npm run build

1. 配置您的Onyx API代币：

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

1. 启动服务器：

   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的搜索功能：

onyx-search
search_onyx

{
  "query": "customer onboarding process",
  "documentSets": ["Company Policies", "Training Materials"],
  "maxResults": 3,
  "chunksAbove": 1,
  "chunksBelow": 1,
  "retrieveFullDocuments": true
}

参数：

• query （必填）：要搜索的主题
• documentSets （可选）：要搜索的文档集名称列表（全部为空）
• maxResults （可选）：返回的最大结果数（默认值：5，最大值：10）
• chunksAbove （可选）：匹配块上方要包含的块数（默认值：1）
• chunksBelow （可选）：匹配块下方要包含的块数（默认值：1）
• retrieveFullDocuments （可选）：是否检索完整文档而不是仅检索块（默认值：false）

2.聊天工具

这 chat_with_onyx 该工具利用Onyx强大的聊天API和LLM+RAG获得全面的答案：

onyx-search
chat_with_onyx

{
  "query": "What is our company's policy on remote work?",
  "personaId": 15,
  "documentSets": ["Company Policies", "HR Documents"],
  "chatSessionId": "optional-existing-session-id"
}

参数：

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

聊天会话

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

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

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

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

用例

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

发展

以开发模式运行

npm run dev

提交更改

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

npm run commit

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

[optional scope]: 

[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将无法通过验证检查

1. 提交消息验证：所有提交消息也会根据常规提交格式进行验证：

- 提交消息必须以类型开头（例如。， feat:, fix:, docs:) - 这是由提交时运行的git钩子强制执行的 - 包含无效消息的提交将被拒绝 - 使用 npm run commit 用于交互式提交消息创建工具

1. 版本凹凸确定：系统分析PR标题和提交消息，以确定适当的版本升级：

- PR标题以开头 feat 或包含新功能→ 小版本碰撞 - PR标题以开头 fix 或包含错误修复→ 补丁版本凹凸 - PR标题包含 BREAKING CHANGE 或带有感叹号→ 主要版本碰撞 - 如果PR标题没有指示特定的凹凸类型，系统会分析提交消息 - 使用任何提交消息中发现的最高优先级凹凸类型（主要>次要>补丁） - 如果没有找到常规的提交前缀，系统会自动默认为补丁版本升级，而不会失败

1. 版本更新和发布:

- 根据语义版本控制对package.json中的版本进行缓冲 - 提交并推动版本更改 - 将新版本发布到npm

这种自动化过程确保了基于更改性质的一致版本控制，遵循语义版本控制原则，并消除了手动版本管理。

贡献

欢迎投稿！请查看我们的 贡献指南 了解更多详情。

安全

如果您发现安全漏洞，请按照我们的 安全策略.

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。