MCP Knowledge Retrieval Server
BM25 기반 문서 검색 및 검색을 위한 MCP(Model Context Protocol) 서버입니다.
- 참고한 토스결제연동 MCP 기술블로그. https://toss.tech/article/tosspayments-mcp
🚀 즉시 시작하기
🎯 초간단 설치 (권장)
이 스크립트들이 자동으로 처리합니다:
- ✅ Node.js 버전 확인
- ✅ 의존성 설치 (
npm install
) - ✅ 프로젝트 빌드 (
npm run build
) - ✅ 설정 파일 생성 (
config.json
) - ✅ 예시 문서 생성 (
docs/
폴더) - ✅ Claude Desktop 설정 가이드 출력
- ✅ MCP 서버 실행
수동 설치
개발 모드
📋 기본 설정
config.json (자동 생성됨)
주요 설정 항목
- documentSource.basePath: 문서 파일들이 위치한 기본 경로
- domains: 검색할 도메인들의 설정
- bm25.k1: BM25 알고리즘의 term frequency saturation 파라미터 (기본값: 1.2)
- bm25.b: BM25 알고리즘의 field length normalization 파라미터 (기본값: 0.75)
- chunk.minWords: 청크의 최소 단어 수 (기본값: 30)
🔧 Claude Desktop 연동
설정 파일 위치
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%/Claude/claude_desktop_config.json
설정 내용 (절대 경로)
중요: <프로젝트_경로>
를 실제 프로젝트 폴더의 절대 경로로 바꾸세요!
권장 설정 (작업 디렉토리 지정)
📁 문서 구조
문서는 다음과 같은 구조로 구성되어야 합니다:
지원 파일 형식
.md
(Markdown).mdx
(MDX).markdown
🛠 사용 가능한 MCP 도구들
1. search-documents
문서 검색을 수행합니다.
파라미터:
keywords
: 검색할 키워드 배열maxResults
: 최대 결과 수 (기본값: 10)domain
: 특정 도메인으로 검색 제한 (선택사항)
예시:
2. get-document-by-id
특정 문서 ID로 전체 문서를 가져옵니다.
파라미터:
documentId
: 문서 ID
3. list-domains
사용 가능한 모든 도메인과 문서 수를 조회합니다.
4. get-chunk-with-context
특정 청크와 그 주변 컨텍스트를 가져옵니다.
파라미터:
chunkId
: 청크 IDcontextSize
: 컨텍스트 윈도우 크기 (선택사항)
🧪 테스트 및 검증
1. 서버 작동 확인
✅ 성공시 출력 예시:
2. Claude Desktop에서 즉시 테스트
Claude Desktop 재시작 후 다음 질문들로 테스트:
3. 빠른 문제 해결
문제 | 해결 방법 |
---|---|
서버 시작 실패 | npm install && npm run build |
문서 로드 실패 | docs/ 폴더와 .md 파일 확인 |
Claude Desktop 연결 실패 | 설정 파일 경로 확인 후 Claude Desktop 재시작 |
📊 성능 최적화
BM25 파라미터 튜닝
- k1 값 증가: 단어 빈도의 영향 증가 (1.2 → 2.0)
- b 값 조정: 문서 길이 정규화 강도 (0.75 → 0.5)
청크 크기 최적화
- minWords 증가: 더 큰 컨텍스트, 느린 검색
- minWords 감소: 정확한 매칭, 빠른 검색
🔒 보안 고려사항
- 파일 권한: 문서 디렉토리에 적절한 읽기 권한 설정
- 환경 변수: 민감한 설정은 환경 변수로 관리
- 네트워크: 필요시 방화벽 규칙 설정
📝 환경 변수 설정
🆘 문제 해결
문제 발생 시 확인 순서:
- 로그 확인:
npm run dev
출력 메시지 - 설정 파일:
config.json
문법 오류 확인 - 문서 폴더:
docs/
디렉토리와.md
파일 확인 - Claude Desktop: 설정 파일 경로 및 재시작
💡 핵심 요약
즉시 사용을 위한 체크리스트
자동 설치 사용시:
./run.sh
(또는run.bat
) 실행- 스크립트가 출력하는 Claude Desktop 설정 복사
- Claude Desktop 재시작
- 테스트 질문으로 작동 확인
수동 설치 사용시:
npm install && npm run build && cp config.example.json config.json
docs/
폴더에 마크다운 파일 추가- Claude Desktop 설정 파일에 프로젝트 경로 지정
- Claude Desktop 재시작
- 테스트 질문으로 작동 확인
주요 명령어
- 개발:
npm run dev
- 빌드:
npm run build
- 실행:
npm start
- 테스트:
npm test
MIT 라이선스 | 개발 중에는 npm run dev
사용 권장
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A BM25-based MCP server that enables document search and retrieval across structured domains of knowledge content, allowing Claude to search and reference documentation when answering questions.
Related MCP Servers
- -securityFlicense-qualityAn MCP server that integrates with Claude to provide smart documentation search capabilities across multiple AI/ML libraries, allowing users to retrieve and process technical information through natural language queries.Last updated -Python
- -securityAlicense-qualityA Claude Desktop MCP server that provides knowledge base search and chat functionality for Volcengine knowledge bases, allowing users to search and chat with their external knowledge repositories.Last updated -PythonMIT License
- -securityFlicense-qualityAn MCP server that enables searching and retrieving content from Confluence documentation systems, providing capabilities for both document searches and full page content retrieval.Last updated -Python
- -securityFlicense-qualityAn MCP server that enables Claude to generate, search, and manage documentation for codebases using vector embeddings and semantic search, providing tools for creating user guides, technical documentation, code explanations, and architectural diagrams.Last updated -2TypeScript