MCP 服务器

onyx-mcp-server

将您的 MCP 兼容客户端连接到 Onyx AI 知识库，以增强语义搜索和聊天功能。从您的文档中无缝检索相关上下文，从而实现强大的交互和全面的答案。简化知识管理并改善对信息的访问。

README

Onyx MCP 服务器

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

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

特性

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

安装

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 Onyx MCP 服务器，请执行以下操作：

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

前提条件

Node.js (v16 或更高版本)
具有 API 访问权限的 Onyx 实例
Onyx API 令牌

设置

克隆存储库：

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

安装依赖项：
```
npm install
```
构建服务器：
```
npm run build
```

配置您的 Onyx API 令牌：

export ONYX_API_TOKEN="your-api-token-here"
export ONYX_API_URL="http://localhost:8080/api"  # 根据需要调整

启动服务器：
```
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 与 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 (必需): 要向 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 管道在每次推送到主分支和拉取请求时运行。它执行以下检查：

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

自动版本递增和发布

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

PR 标题验证: 所有 PR 标题都根据 Conventional Commits 规范进行验证：
- PR 标题必须以类型开头（例如，feat:、fix:、docs:）
- 此验证在创建或更新 PR 时自动发生
- 标题无效的 PR 将无法通过验证检查
提交消息验证: 所有提交消息也根据传统提交格式进行验证：
- 提交消息必须以类型开头（例如，feat:、fix:、docs:）
- 这是通过在提交时运行的 git 钩子强制执行的
- 消息无效的提交将被拒绝
- 使用 npm run commit 获取交互式提交消息创建工具
版本递增确定: 系统会分析 PR 标题和提交消息，以确定适当的版本递增：
- 以 feat 开头或包含新功能的 PR 标题 → 次要版本递增
- 以 fix 开头或包含错误修复的 PR 标题 → 补丁版本递增
- 包含 BREAKING CHANGE 或带有感叹号的 PR 标题 → 主要版本递增
- 如果 PR 标题未指示特定的递增类型，则系统会分析提交消息
- 使用在任何提交消息中找到的最高优先级递增类型（主要 > 次要 > 补丁）
- 如果未找到任何传统提交前缀，则系统会自动默认为补丁版本递增，而不会失败
版本更新和发布:
- 根据语义版本控制递增 package.json 中的版本
- 提交并推送版本更改
- 将新版本发布到 npm

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

贡献

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

安全

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

许可证

此项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。