MCP-Ragdocs
벡터 데이터베이스(Qdrant)를 사용하여 문서의 의미론적 검색 및 조회를 지원하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버를 사용하면 URL이나 로컬 파일에서 문서를 추가한 후 자연어 쿼리를 사용하여 검색할 수 있습니다.
빠른 설치 가이드
- 패키지를 전역으로 설치합니다.지엑스피1
- Qdrant 시작(Docker 사용):
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant
- Ollama가 기본 임베딩 모델로 실행 중인지 확인하세요.
ollama pull nomic-embed-text
- 구성 파일에 다음을 추가합니다.
- 클라인의 경우:
%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"
}
}
}
}
- 설치 확인:
# 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 install -g @qpd-v/mcp-server-ragdocs
이렇게 하면 아래 구성 단계에 필요한 글로벌 npm 디렉토리에 서버가 설치됩니다.
요구 사항
- Node.js 16 이상
- Qdrant(로컬 또는 클라우드)
- 임베딩의 경우 다음 중 하나:
- 로컬에서 실행되는 Ollama(기본, 무료)
- OpenAI API 키(선택 사항, 유료)
Qdrant 설정 옵션
옵션 1: 로컬 Qdrant
- Docker 사용(권장):
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant
- 또는 Qdrant 웹사이트 에서 다운로드하세요
옵션 2: Qdrant 클라우드
- Qdrant Cloud 에 계정을 만드세요
- 새 클러스터를 만듭니다
- 대시보드에서 클러스터 URL과 API 키를 가져옵니다.
- 구성에서 이것을 사용하세요(아래 구성 섹션 참조)
구성
이 서버는 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 )에 추가합니다.
- npm global install 사용(권장):
{
"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"
}
}
}
}
Ollama 대신 OpenAI의 경우:
{
"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": "openai",
"OPENAI_API_KEY": "your-openai-api-key"
}
}
}
}
- 로컬 개발 설정 사용:
{
"mcpServers": {
"ragdocs": {
"command": "node",
"args": ["PATH_TO_PROJECT/mcp-ragdocs/build/index.js"],
"env": {
"QDRANT_URL": "http://127.0.0.1:6333",
"EMBEDDING_PROVIDER": "ollama",
"OLLAMA_URL": "http://localhost:11434"
}
}
}
}
클로드 데스크톱 구성
Claude Desktop 구성 파일에 다음을 추가합니다.
- 윈도우:
%AppData%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Ollama를 사용한 Windows 설치(전체 경로 사용):
{
"mcpServers": {
"ragdocs": {
"command": "C:\\Program Files\\nodejs\\node.exe",
"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"
}
}
}
}
OpenAI를 사용한 Windows 설치:
{
"mcpServers": {
"ragdocs": {
"command": "C:\\Program Files\\nodejs\\node.exe",
"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": "openai",
"OPENAI_API_KEY": "your-openai-api-key"
}
}
}
}
- Ollama를 사용한 macOS 설정:
{
"mcpServers": {
"ragdocs": {
"command": "/usr/local/bin/node",
"args": [
"/usr/local/lib/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"
}
}
}
}
Qdrant 클라우드 구성
Cline 또는 Claude Desktop의 경우 Qdrant Cloud를 사용할 때 env 섹션을 수정하세요.
올라마와 함께:
{
"env": {
"QDRANT_URL": "https://your-cluster-url.qdrant.tech",
"QDRANT_API_KEY": "your-qdrant-api-key",
"EMBEDDING_PROVIDER": "ollama",
"OLLAMA_URL": "http://localhost:11434"
}
}
OpenAI를 사용하면:
{
"env": {
"QDRANT_URL": "https://your-cluster-url.qdrant.tech",
"QDRANT_API_KEY": "your-qdrant-api-key",
"EMBEDDING_PROVIDER": "openai",
"OPENAI_API_KEY": "your-openai-api-key"
}
}
환경 변수
Qdrant 구성
QDRANT_URL (필수): Qdrant 인스턴스의 URLQDRANT_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 키
사용 가능한 도구
add_documentation- URL에서 RAG 데이터베이스에 문서 추가
- 매개변수:
search_documentation- 저장된 문서 검색
- 매개변수:
query : 검색 쿼리limit (선택 사항): 반환할 최대 결과 수(기본값: 5)
list_sources- 현재 저장된 모든 문서 소스를 나열합니다.
- 매개변수가 필요하지 않습니다
사용 예
Claude Desktop 또는 기타 MCP 호환 클라이언트에서:
- 문서 추가:
Add this documentation: https://docs.example.com/api
- 문서 검색:
Search the documentation for information about authentication
- 출처 목록:
What documentation sources are available?
개발
- 저장소를 복제합니다.
git clone https://github.com/qpd-v/mcp-server-ragdocs.git
cd mcp-server-ragdocs
- 종속성 설치:
- 프로젝트를 빌드하세요:
- 로컬로 실행:
특허
MIT
문제 해결
일반적인 문제
- Qdrant 연결 오류
Error: Failed to connect to Qdrant at http://localhost:6333
- Docker가 실행 중인지 확인하세요
- Qdrant 컨테이너가 실행 중인지 확인하세요:
docker ps | grep qdrant - 컨테이너를 다시 시작해 보세요
- 올라마 모델 누락
Error: Model nomic-embed-text not found
- 실행:
ollama pull nomic-embed-text - 모델이 설치되었는지 확인하세요:
ollama list
- 구성 경로 문제
- Windows:
YOUR_USERNAME 실제 Windows 사용자 이름으로 바꾸세요. - 파일 권한 확인
- 경로가 존재하는지 확인하세요
- 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 이상이어야 함)
기여하다
기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.