黑玉-MCP服务器

Name: 黑玉-MCP服务器
Author: lupuletic

作者：lupuletic19 星标更新：2025-05-21

安装使用来源：spider==github.com

项目介绍

Onyx MCP 服务器

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

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

功能

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

安装

通过 Smithery 安装

要通过 Smithery 自动安装 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 桌面应用

添加到 ~/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": []
    }
  }
}

对于 Claude 在 VSCode 中 (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": "客户入门流程",
  "documentSets": ["公司政策", "培训材料"],
  "maxResults": 3,
  "chunksAbove": 1,
  "chunksBelow": 1,
  "retrieveFullDocuments": true
}
</arguments>
</use_mcp_tool>

参数：

query (必需)：要搜索的主题
documentSets (可选)：要在其中搜索的文档集名称列表（空表示所有）
maxResults (可选)：返回的最大结果数（默认：5，最大：1
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": "我们公司的远程工作政策是什么？",
  "personaId": 15,
  "documentSets": ["公司政策", "人力资源文档"],
  "chatSessionId": "可选现有会话ID"
}
</arguments>
</use_mcp_tool>

参数：

query (必需)：要询问 Onyx 的问题
personaId (可选)：要使用的角色 ID（默认：15）
documentSets (可选)：要在其中搜索的文档集名称列表（空表示所有）
chatSessionId (可选)：继续对话的现有聊天会话 ID

聊天会话

聊天工具支持在多次交互之间维护对话上下文。首次调用后，响应将包含元数据中的 chat_session_id。您可以在后续调用中传递此 ID 以维持上下文。

选择搜索还是聊天

当需要时使用搜索：从文档中获取具体、有针对性的信息，并且希望精确控制检索多少上下文。
当需要时使用聊天：需要结合多个来源的综合答案，或者希望 LLM 为您合成信息。

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

使用场景

知识管理：通过任何兼容 MCP 的界面访问组织的知识库
客户服务：帮助支持人员快速找到相关信息
研究：跨组织文档进行深入研究
培训：提供对培训材料和文档的访问
政策合规：确保团队可以访问最新的政策和程序

开发

在开发模式下运行

npm run dev

提交更改

该项目要求所有提交消息遵循常规提交规范。为了简化这一过程，我们提供了一个交互式提交工具：

npm run commit

这将引导您创建一个格式正确的提交消息。或者，您可以按照常规格式编写自己的提交消息：

<类型>[可选范围]： <描述>

[可选正文]

[可选脚注]

其中 类型 是以下之一：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 标题都必须符合常规提交规范：
- PR 标题必须以类型开头（例如，feat:，fix:，docs:）
- 当 PR 创建或更新时，此验证会自动进行
- 标题无效的 PR 将失败验证检查
提交消息验证：所有提交消息也必须符合常规提交格式：
- 提交消息必须以类型开头（例如，feat:，fix:，docs:）
- 此规则由在您提交时运行的 git 钩子强制执行
- 提交消息无效的提交将被拒绝
- 使用 npm run commit 创建交互式提交消息
版本提升决定：系统分析 PR 标题和提交消息以确定适当的版本提升：
- PR 标题以 feat 开头或包含新功能 → 次版本提升
- PR 标题以 fix 开头或包含错误修复 → 补丁版本提升
- PR 标题包含 BREAKING CHANGE 或感叹号 → 主版本提升
- 如果 PR 标题没有指示特定的提升类型，则系统分析提交消息
- 找到的最高优先级提升类型（主 > 次 > 补丁）
- 如果未找到常规提交前缀，系统将自动默认为补丁版本提升而不失败
版本更新和发布：
- 根据语义化版本控制原则更新 package.json 中的版本
- 提交并推送版本更改
- 发布新版本到 npm

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

贡献

欢迎贡献！请参阅我们的贡献指南以获取更多详细信息。

安全

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

许可证

本项目根据 MIT 许可证授权 - 详情见许可证文件。