Onyx MCP服务器
用于与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代币
设置
- 克隆存储库：
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" # Adjust as needed- 启动服务器：
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标题和提交消息，以确定版本冲突类型。
- 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许可证获得许可-请参阅 许可证 文件以获取详细信息。