
Knowledge Retrieval Server
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.
README
MCP Knowledge Retrieval Server
BM25 기반 문서 검색 및 검색을 위한 MCP(Model Context Protocol) 서버입니다.
- 참고한 토스결제연동 MCP 기술블로그. https://toss.tech/article/tosspayments-mcp
🚀 즉시 시작하기
🎯 초간단 설치 (권장)
# macOS/Linux
./run.sh
# Windows
run.bat
이 스크립트들이 자동으로 처리합니다:
- ✅ Node.js 버전 확인
- ✅ 의존성 설치 (
npm install
) - ✅ 프로젝트 빌드 (
npm run build
) - ✅ 설정 파일 생성 (
config.json
) - ✅ 예시 문서 생성 (
docs/
폴더) - ✅ Claude Desktop 설정 가이드 출력
- ✅ MCP 서버 실행
수동 설치
# 단계별 설치
npm install && npm run build && cp config.example.json config.json
# 서버 실행
npm start
개발 모드
npm run dev
📋 기본 설정
config.json (자동 생성됨)
{
"serverName": "knowledge-retrieval",
"serverVersion": "1.0.0",
"documentSource": {
"type": "local",
"basePath": "./docs",
"domains": [
{
"name": "company",
"path": "company",
"category": "회사정보"
},
{
"name": "customer",
"path": "customer",
"category": "고객서비스"
},
{
"name": "product",
"path": "product",
"category": "제품정보"
},
{
"name": "technical",
"path": "technical",
"category": "기술문서"
}
]
},
"bm25": {
"k1": 1.2,
"b": 0.75
},
"chunk": {
"minWords": 30,
"contextWindowSize": 1
},
"logLevel": "info"
}
주요 설정 항목
- 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
설정 내용 (절대 경로)
{
"mcpServers": {
"knowledge-retrieval": {
"command": "node",
"args": ["<프로젝트_경로>/dist/index.js"],
"env": {
"NODE_ENV": "production"
}
}
}
}
중요: <프로젝트_경로>
를 실제 프로젝트 폴더의 절대 경로로 바꾸세요!
권장 설정 (작업 디렉토리 지정)
{
"mcpServers": {
"knowledge-retrieval": {
"command": "npm",
"args": ["start"],
"cwd": "<프로젝트_경로>"
}
}
}
📁 문서 구조
문서는 다음과 같은 구조로 구성되어야 합니다:
docs/
├── company/ # 회사 정보
│ ├── about.md
│ └── team.md
├── customer/ # 고객 서비스
│ ├── support.md
│ └── sla.md
├── product/ # 제품 정보
│ ├── ai-platform.md
│ └── web-app.md
└── technical/ # 기술 문서
├── api-guide.md
└── deployment.md
지원 파일 형식
.md
(Markdown).mdx
(MDX).markdown
🛠 사용 가능한 MCP 도구들
1. search-documents
문서 검색을 수행합니다.
파라미터:
keywords
: 검색할 키워드 배열maxResults
: 최대 결과 수 (기본값: 10)domain
: 특정 도메인으로 검색 제한 (선택사항)
예시:
// Claude Desktop에서 사용할 때
"AI 플랫폼의 가격 정책을 알려줘"
2. get-document-by-id
특정 문서 ID로 전체 문서를 가져옵니다.
파라미터:
documentId
: 문서 ID
3. list-domains
사용 가능한 모든 도메인과 문서 수를 조회합니다.
4. get-chunk-with-context
특정 청크와 그 주변 컨텍스트를 가져옵니다.
파라미터:
chunkId
: 청크 IDcontextSize
: 컨텍스트 윈도우 크기 (선택사항)
🧪 테스트 및 검증
1. 서버 작동 확인
npm run dev
✅ 성공시 출력 예시:
Initializing knowledge-retrieval v1.0.0...
Loaded 8 documents
Initialized repository with 36 chunks from 8 documents
MCP server started successfully
2. Claude Desktop에서 즉시 테스트
Claude Desktop 재시작 후 다음 질문들로 테스트:
우리 회사의 비전과 미션이 뭐야?
AI 플랫폼의 가격 정책을 알려줘
API 인증 방법을 설명해줘
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 감소: 정확한 매칭, 빠른 검색
🔒 보안 고려사항
- 파일 권한: 문서 디렉토리에 적절한 읽기 권한 설정
- 환경 변수: 민감한 설정은 환경 변수로 관리
- 네트워크: 필요시 방화벽 규칙 설정
📝 환경 변수 설정
export MCP_SERVER_NAME="my-knowledge-server"
export DOCS_BASE_PATH="./my-docs"
export BM25_K1="1.5"
export BM25_B="0.8"
export CHUNK_MIN_WORDS="50"
export LOG_LEVEL="debug"
🆘 문제 해결
문제 발생 시 확인 순서:
- 로그 확인:
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
사용 권장
Recommended Servers
playwright-mcp
A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.
Magic Component Platform (MCP)
An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.
Audiense Insights MCP Server
Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

VeyraX MCP
Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.
graphlit-mcp-server
The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.
Kagi MCP Server
An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

E2B
Using MCP to run code via e2b.
Neon Database
MCP server for interacting with Neon Management API and databases
Exa Search
A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.
Qdrant Server
This repository is an example of how to create a MCP server for Qdrant, a vector search engine.