Onyx MCP Server

Onyx MCP 服务

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

此 MCP 服务可将任何兼容 MCP 的客户端连接到你的 Onyx 知识库，让你搜索并检索文档中的相关上下文。它在 MCP 客户端与 Onyx API 之间搭建桥梁，提供强大的语义搜索和聊天功能。

功能

• 增强搜索：对 Onyx 文档集进行语义搜索，并通过大模型筛选相关内容
• 上下文窗口检索：检索匹配内容块上方和下方的内容块，以获得更好的上下文
• 完整文档检索：可选择检索完整文档，而不仅仅是内容块
• 聊天集成：使用 Onyx 强大的聊天 API，结合大模型和 RAG 提供全面的回答
• 可配置的文档集筛选：针对特定文档集进行搜索，获得更相关的结果

安装

通过 Smithery 安装

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

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

添加到 ~/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 客户端即可使用两个强大的工具：

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，结合大模型和 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（必需）：要向 Onyx 提出的问题
• personaId（可选）：要使用的角色 ID（默认值：15）
• documentSets（可选）：要搜索的文档集名称列表（留空则搜索全部）
• chatSessionId（可选）：用于继续对话的现有聊天会话 ID

聊天会话

聊天工具支持在多次交互中保留对话上下文。首次调用后，响应的元数据中会包含一个 chat_session_id。你可以在后续调用中传入此 ID，以保留上下文。

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

• 使用搜索的场景：需要从文档中获取特定、精准的信息，并希望精确控制检索到的上下文量。
• 使用聊天的场景：需要结合多个来源获取全面的答案，或希望 LLM 为你综合信息。

为获得最佳效果，可以结合使用这两种工具：搜索特定细节，再通过聊天全面理解。

使用场景

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

开发

在开发模式下运行

npm run dev

提交更改

本项目要求所有提交消息遵循 Conventional Commits 规范。为方便你遵循此规范，我们提供了一个交互式提交工具：

npm run commit

该工具将引导你创建格式正确的提交消息。你也可以按照 Conventional Commits 格式自行编写提交消息：

<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 合并到 main 分支后，项目会自动确定适当的版本递增类型并发布到 npm。系统会分析 PR 标题和提交消息，以确定版本递增类型。

1. PR 标题验证：所有 PR 标题都会根据 Conventional Commits 规范进行验证：

   • PR 标题必须以类型开头（例如，feat:、fix:、docs:）
   • 创建或更新 PR 时会自动进行此验证
   • 标题无效的 PR 将无法通过验证检查

2. 提交消息验证：所有提交消息也会根据 Conventional Commits 格式进行验证：

   • 提交消息必须以类型开头（例如，feat:、fix:、docs:）
   • 提交时运行的 git hooks 会强制执行此规则
   • 消息无效的提交将被拒绝
   • 使用 npm run commit 交互式创建提交消息

3. 确定版本递增类型：系统会分析 PR 标题和提交消息，以确定适当的版本递增类型：

   • 以 feat 开头或包含新功能的 PR 标题 → 递增次版本号
   • 以 fix 开头或包含错误修复的 PR 标题 → 递增修订版本号
   • 包含 BREAKING CHANGE 或感叹号的 PR 标题 → 递增主版本号
   • 如果 PR 标题未指明具体的递增类型，系统会分析提交消息
   • 使用任何提交消息中发现的最高优先级递增类型（主版本号 > 次版本号 > 修订版本号）
   • 如果未发现 Conventional Commits 前缀，系统会自动默认递增修订版本号，不会失败

4. 更新版本并发布：

   • 根据语义化版本规范递增 package.json 中的版本号
   • 提交并推送版本变更
   • 将新版本发布到 npm

此自动化流程会根据变更的性质，遵循语义化版本规范，确保版本号保持一致，并免去手动管理版本的工作。

贡献

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

安全

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

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。