Onyx MCP 服务器

一个用于与 Onyx AI 知识库无缝集成的 Model Context Protocol (MCP) 服务器。

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

功能

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

安装

通过 Smithery 安装

要通过 Smithery 自动安装适用于 Claude 桌面版的 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"  # 根据需要调整
   

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 中的 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 标题和提交信息来确定版本更新类型。

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

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

2. 提交信息验证：所有提交信息也按照约定提交格式进行验证：

   • 提交信息必须以类型开头（例如 feat:、fix:、docs:）
   • 这是通过在提交时运行的 git 钩子强制执行的
   • 消息无效的提交将被拒绝
   • 使用 npm run commit 可以获得交互式的提交消息创建工具

3. 版本更新确定：系统同时分析 PR 标题和提交信息以确定适当的版本更新：

   • 以 feat 开头或包含新功能的 PR 标题 → 次版本更新
   • 以 fix 开头或包含错误修复的 PR 标题 → 补丁版本更新
   • 包含 BREAKING CHANGE 或带有感叹号的 PR 标题 → 主版本更新
   • 如果 PR 标题没有指示特定的更新类型，则系统会分析提交信息
   • 在任何提交信息中找到的最高优先级更新类型会被使用（主版本 > 次版本 > 补丁版本）
   • 如果未找到任何约定的提交前缀，系统将默认为补丁版本更新而不会失败

4. 版本更新与发布：

   • 根据语义化版本规则更新 package.json 中的版本
   • 提交并推送版本更改
   • 将新版本发布到 npm

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

贡献

欢迎贡献！请参阅我们的 贡献指南 获取更多细节。

安全

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

许可证

本项目采用 MIT 许可证 - 详情请见 LICENSE 文件。