오닉스-mcp-서버

Onyx MCP 서버

Onyx AI 지식 기반과 원활하게 통합하기 위한 MCP(모델 컨텍스트 프로토콜) 서버입니다.

이 MCP 서버는 모든 MCP 호환 클라이언트를 Onyx 지식 기반에 연결하여 문서에서 관련 컨텍스트를 검색하고 불러올 수 있도록 지원합니다. MCP 클라이언트와 Onyx API를 연결하여 강력한 시맨틱 검색 및 채팅 기능을 제공합니다.

특징

향상된 검색 : LLM 관련성 필터링을 통해 Onyx 문서 세트 전반에 걸쳐 의미 검색
컨텍스트 창 검색 : 더 나은 컨텍스트를 위해 일치하는 청크 위아래 청크를 검색합니다.
전체 문서 검색 : 청크만이 아닌 전체 문서를 검색하는 옵션
채팅 통합 : LLM + RAG와 함께 Onyx의 강력한 채팅 API를 사용하여 포괄적인 답변을 얻으세요.
구성 가능한 문서 세트 필터링 : 더욱 관련성 있는 결과를 위해 특정 문서 세트를 타겟팅합니다.

설치

Smithery를 통해 설치

Smithery를 통해 Claude Desktop에 Onyx MCP Server를 자동으로 설치하려면:

지엑스피1

필수 조건

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의 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 도구는 LLM + RAG와 함께 Onyx의 강력한 채팅 API를 활용하여 다음과 같은 포괄적인 답변을 제공합니다.

<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 제목은 기존 커밋 사양에 따라 검증됩니다.
- PR 제목은 유형으로 시작해야 합니다(예: feat: :, fix:``docs:
- 이 검증은 PR이 생성되거나 업데이트될 때 자동으로 수행됩니다.
- 유효하지 않은 제목이 있는 PR은 유효성 검사에 실패합니다.
커밋 메시지 검증 : 모든 커밋 메시지는 기존 커밋 형식에 대해서도 검증됩니다.
- 커밋 메시지는 유형으로 시작해야 합니다(예: feat: , fix: , docs: )
- 이는 커밋할 때 실행되는 git hooks에 의해 적용됩니다.
- 잘못된 메시지가 포함된 커밋은 거부됩니다.
- 대화형 커밋 메시지 생성 도구를 사용하려면 npm run commit 사용하세요.
버전 범프 결정 : 시스템은 PR 제목과 커밋 메시지를 모두 분석하여 적절한 버전 범프를 결정합니다.
- feat 로 시작하거나 새로운 기능을 포함하는 PR 제목 → 마이너 버전 범프
- fix 로 시작하거나 버그 수정을 포함하는 PR 제목 → 패치 버전 범프
- BREAKING CHANGE 포함하거나 느낌표가 있는 PR 제목 → 주 버전 범프
- PR 제목이 특정 범프 유형을 나타내지 않으면 시스템은 커밋 메시지를 분석합니다.
- 커밋 메시지에서 발견된 가장 높은 우선순위의 범프 유형이 사용됩니다(주요 > 부 > 패치).
- 기존 커밋 접두사가 발견되지 않으면 시스템은 실패하지 않고 자동으로 패치 버전 범프를 기본값으로 설정합니다.
버전 업데이트 및 게시 :
- 의미적 버전에 따라 package.json의 버전을 늘립니다.
- 버전 변경 사항을 커밋하고 푸시합니다.
- npm에 새 버전을 게시합니다.

이 자동화된 프로세스는 의미적 버전 관리 원칙을 따르고, 변경 사항의 특성에 따라 일관된 버전 관리를 보장하며, 수동 버전 관리를 제거합니다.

기여하다

기여를 환영합니다! 자세한 내용은 기여 가이드를 참조하세요.

보안

보안 취약점을 발견한 경우, 당사의 보안 정책을 따르시기 바랍니다.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

onyx-mcp-server

Integrations