MCP-Ragdocs

벡터 데이터베이스(Qdrant)를 사용하여 문서의 의미론적 검색 및 조회를 지원하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버를 사용하면 URL이나 로컬 파일에서 문서를 추가한 후 자연어 쿼리를 사용하여 검색할 수 있습니다.

빠른 설치 가이드

1. 패키지를 전역으로 설치합니다.

   지엑스피1

2. Qdrant 시작(Docker 사용):

   docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

3. Ollama가 기본 임베딩 모델로 실행 중인지 확인하세요.

   ollama pull nomic-embed-text

4. 구성 파일에 다음을 추가합니다.

   • 클라인의 경우: %AppData%\Roaming\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

   • Roo-Code의 경우: %AppData%\Roaming\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json

   • Claude Desktop의 경우: %AppData%\Claude\claude_desktop_config.json

   { "mcpServers": { "ragdocs": { "command": "node", "args": ["C:/Users/YOUR_USERNAME/AppData/Roaming/npm/node_modules/@qpd-v/mcp-server-ragdocs/build/index.js"], "env": { "QDRANT_URL": "http://127.0.0.1:6333", "EMBEDDING_PROVIDER": "ollama", "OLLAMA_URL": "http://localhost:11434" } } } }

5. 설치 확인:

   # Check Qdrant is running curl http://localhost:6333/collections # Check Ollama has the model ollama list | grep nomic-embed-text

버전

현재 버전: 0.1.6

특징

• URL 또는 로컬 파일에서 문서 추가

• 의미 검색을 위해 벡터 데이터베이스에 문서 저장

• 자연어를 사용하여 문서 검색

• 모든 문서 출처 나열

설치

npm을 사용하여 전역적으로 설치합니다.

이렇게 하면 아래 구성 단계에 필요한 글로벌 npm 디렉토리에 서버가 설치됩니다.

요구 사항

• Node.js 16 이상

• Qdrant(로컬 또는 클라우드)

• 임베딩의 경우 다음 중 하나:

  • 로컬에서 실행되는 Ollama(기본, 무료)

  • OpenAI API 키(선택 사항, 유료)

Qdrant 설정 옵션

옵션 1: 로컬 Qdrant

1. Docker 사용(권장):

2. 또는 Qdrant 웹사이트 에서 다운로드하세요

옵션 2: Qdrant 클라우드

1. Qdrant Cloud 에 계정을 만드세요

2. 새 클러스터를 만듭니다

3. 대시보드에서 클러스터 URL과 API 키를 가져옵니다.

4. 구성에서 이것을 사용하세요(아래 구성 섹션 참조)

구성

이 서버는 Cline/Roo와 Claude Desktop 모두에서 사용할 수 있습니다. 두 서버 간에 구성은 약간씩 다릅니다.

클라인 구성

Cline 설정 파일( %AppData%\Roaming\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json )에 추가하거나 Roo-Code 설정 파일( %AppData%\Roaming\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json )에 추가합니다.

1. npm global install 사용(권장):

Ollama 대신 OpenAI의 경우:

2. 로컬 개발 설정 사용:

클로드 데스크톱 구성

Claude Desktop 구성 파일에 다음을 추가합니다.

• 윈도우: %AppData%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

1. Ollama를 사용한 Windows 설치(전체 경로 사용):

OpenAI를 사용한 Windows 설치:

2. Ollama를 사용한 macOS 설정:

Qdrant 클라우드 구성

Cline 또는 Claude Desktop의 경우 Qdrant Cloud를 사용할 때 env 섹션을 수정하세요.

올라마와 함께:

OpenAI를 사용하면:

환경 변수

Qdrant 구성

• QDRANT_URL (필수): Qdrant 인스턴스의 URL

  • 로컬의 경우: http://localhost:6333

  • 클라우드의 경우: https://your-cluster-url.qdrant.tech

• QDRANT_API_KEY (클라우드에 필요): Qdrant Cloud API 키

임베딩 구성

• EMBEDDING_PROVIDER (선택 사항): 'ollama'(기본값) 또는 'openai' 중에서 선택하세요.

• EMBEDDING_MODEL (선택 사항):

  • Ollama의 경우: 기본값은 'nomic-embed-text'입니다.

  • OpenAI의 경우: 기본값은 'text-embedding-3-small'입니다.

• OLLAMA_URL (선택 사항): Ollama 인스턴스의 URL(기본값은 http://localhost:11434 )

• OPENAI_API_KEY (OpenAI를 사용하는 경우 필수): OpenAI API 키

사용 가능한 도구

1. add_documentation

   • URL에서 RAG 데이터베이스에 문서 추가

   • 매개변수:

     • url : 가져올 문서의 URL

2. search_documentation

   • 저장된 문서 검색

   • 매개변수:

     • query : 검색 쿼리

     • limit (선택 사항): 반환할 최대 결과 수(기본값: 5)

3. list_sources

   • 현재 저장된 모든 문서 소스를 나열합니다.

   • 매개변수가 필요하지 않습니다

사용 예

Claude Desktop 또는 기타 MCP 호환 클라이언트에서:

1. 문서 추가:

2. 문서 검색:

3. 출처 목록:

개발

1. 저장소를 복제합니다.

2. 종속성 설치:

3. 프로젝트를 빌드하세요:

4. 로컬로 실행:

특허

MIT

문제 해결

일반적인 문제

1. Qdrant 연결 오류

   Error: Failed to connect to Qdrant at http://localhost:6333

   • Docker가 실행 중인지 확인하세요

   • Qdrant 컨테이너가 실행 중인지 확인하세요: docker ps | grep qdrant

   • 컨테이너를 다시 시작해 보세요

2. 올라마 모델 누락

   Error: Model nomic-embed-text not found

   • 실행: ollama pull nomic-embed-text

   • 모델이 설치되었는지 확인하세요: ollama list

3. 구성 경로 문제

   • Windows: YOUR_USERNAME 실제 Windows 사용자 이름으로 바꾸세요.

   • 파일 권한 확인

   • 경로가 존재하는지 확인하세요

4. npm 글로벌 설치 문제

   • 관리자 권한으로 설치를 시도해 보세요

   • npm이 PATH에 있는지 확인하세요: npm -v

   • 글로벌 설치 확인: npm list -g @qpd-v/mcp-server-ragdocs

다른 문제는 다음을 확인하세요.

• Docker 로그: docker logs $(docker ps -q --filter ancestor=qdrant/qdrant)

• 올라마 상태: ollama list

• Node.js 버전: node -v (16 이상이어야 함)

기여하다

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.