{"id":29885551,"url":"https://github.com/cskwork/keyword-rag-mcp","last_synced_at":"2026-05-31T04:04:56.493Z","repository":{"id":302585750,"uuid":"1012939722","full_name":"cskwork/keyword-rag-mcp","owner":"cskwork","description":"MCP Knowledge Retrieval Server: 토스 결제연동 MCP 프로젝트를 참고하여 BM25 알고리즘 기반으로 마크다운 문서를 검색하고 지식 검색을 제공하는 MCP 서버입니다.","archived":false,"fork":false,"pushed_at":"2025-07-23T05:30:42.000Z","size":505,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-23T07:22:29.501Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cskwork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-03T05:56:01.000Z","updated_at":"2025-07-23T05:30:45.000Z","dependencies_parsed_at":"2025-07-03T07:20:24.043Z","dependency_job_id":"1912fff3-3439-4c80-832a-f849d313cc9c","html_url":"https://github.com/cskwork/keyword-rag-mcp","commit_stats":null,"previous_names":["cskwork/keyword-rag-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cskwork/keyword-rag-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fkeyword-rag-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fkeyword-rag-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fkeyword-rag-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fkeyword-rag-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cskwork","download_url":"https://codeload.github.com/cskwork/keyword-rag-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fkeyword-rag-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33718496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-31T16:02:05.949Z","updated_at":"2026-05-31T04:04:56.484Z","avatar_url":"https://github.com/cskwork.png","language":"TypeScript","funding_links":[],"categories":["Knowledge \u0026 Memory"],"sub_categories":["How to Submit"],"readme":"# MCP Knowledge Retrieval Server\n\nBM25 기반 문서 검색 및 검색을 위한 MCP(Model Context Protocol) 서버입니다.\n- 참고한 토스결제연동 MCP 기술블로그. https://toss.tech/article/tosspayments-mcp\n\n## 🚀 즉시 시작하기\n\n### 🎯 초간단 설치 (권장)\n```bash\n# macOS/Linux\n./run.sh\n\n# Windows\nrun.bat\n```\n\n이 스크립트들이 자동으로 처리합니다:\n- ✅ Node.js 버전 확인\n- ✅ 의존성 설치 (`npm install`)\n- ✅ 프로젝트 빌드 (`npm run build`)\n- ✅ 설정 파일 생성 (`config.json`)\n- ✅ 예시 문서 생성 (`docs/` 폴더)\n- ✅ Claude Desktop 설정 가이드 출력\n- ✅ MCP 서버 실행\n\n### 수동 설치\n```bash\n# 단계별 설치\nnpm install \u0026\u0026 npm run build \u0026\u0026 cp config.example.json config.json\n\n# 서버 실행\nnpm start\n```\n\n### 개발 모드\n```bash\nnpm run dev\n```\n\n## 📋 기본 설정\n\n### config.json (자동 생성됨)\n```json\n{\n  \"serverName\": \"knowledge-retrieval\",  \n  \"serverVersion\": \"1.0.0\",\n  \"documentSource\": {\n    \"type\": \"local\",\n    \"basePath\": \"./docs\",\n    \"domains\": [\n      {\n        \"name\": \"company\",\n        \"path\": \"company\",\n        \"category\": \"회사정보\"\n      },\n      {\n        \"name\": \"customer\", \n        \"path\": \"customer\",\n        \"category\": \"고객서비스\"\n      },\n      {\n        \"name\": \"product\",\n        \"path\": \"product\", \n        \"category\": \"제품정보\"\n      },\n      {\n        \"name\": \"technical\",\n        \"path\": \"technical\",\n        \"category\": \"기술문서\"\n      }\n    ]\n  },\n  \"bm25\": {\n    \"k1\": 1.2,\n    \"b\": 0.75\n  },\n  \"chunk\": {\n    \"minWords\": 30,\n    \"contextWindowSize\": 1\n  },\n  \"logLevel\": \"info\"\n}\n```\n\n### 주요 설정 항목\n- **documentSource.basePath**: 문서 파일들이 위치한 기본 경로\n- **domains**: 검색할 도메인들의 설정\n- **bm25.k1**: BM25 알고리즘의 term frequency saturation 파라미터 (기본값: 1.2)\n- **bm25.b**: BM25 알고리즘의 field length normalization 파라미터 (기본값: 0.75)\n- **chunk.minWords**: 청크의 최소 단어 수 (기본값: 30)\n\n## 🔧 Claude Desktop 연동\n\n### 설정 파일 위치\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`\n\n### 설정 내용 (절대 경로)\n```json\n{\n  \"mcpServers\": {\n    \"knowledge-retrieval\": {\n      \"command\": \"node\",\n      \"args\": [\"\u003c프로젝트_경로\u003e/dist/index.js\"],\n      \"env\": {\n        \"NODE_ENV\": \"production\"\n      }\n    }\n  }\n}\n```\n\n**중요**: `\u003c프로젝트_경로\u003e`를 실제 프로젝트 폴더의 절대 경로로 바꾸세요!\n\n### 권장 설정 (작업 디렉토리 지정)\n```json\n{\n  \"mcpServers\": {\n    \"knowledge-retrieval\": {\n      \"command\": \"npm\",\n      \"args\": [\"start\"],\n      \"cwd\": \"\u003c프로젝트_경로\u003e\"\n    }\n  }\n}\n```\n\n## 📁 문서 구조\n\n문서는 다음과 같은 구조로 구성되어야 합니다:\n\n```\ndocs/\n├── company/           # 회사 정보\n│   ├── about.md\n│   └── team.md\n├── customer/          # 고객 서비스\n│   ├── support.md\n│   └── sla.md\n├── product/           # 제품 정보\n│   ├── ai-platform.md\n│   └── web-app.md\n└── technical/         # 기술 문서\n    ├── api-guide.md\n    └── deployment.md\n```\n\n### 지원 파일 형식\n- `.md` (Markdown)\n- `.mdx` (MDX)\n- `.markdown`\n\n## 🛠 사용 가능한 MCP 도구들\n\n### 1. search-documents\n문서 검색을 수행합니다.\n\n**파라미터:**\n- `keywords`: 검색할 키워드 배열\n- `maxResults`: 최대 결과 수 (기본값: 10)\n- `domain`: 특정 도메인으로 검색 제한 (선택사항)\n\n**예시:**\n```typescript\n// Claude Desktop에서 사용할 때\n\"AI 플랫폼의 가격 정책을 알려줘\"\n```\n\n### 2. get-document-by-id  \n특정 문서 ID로 전체 문서를 가져옵니다.\n\n**파라미터:**\n- `documentId`: 문서 ID\n\n### 3. list-domains\n사용 가능한 모든 도메인과 문서 수를 조회합니다.\n\n### 4. get-chunk-with-context\n특정 청크와 그 주변 컨텍스트를 가져옵니다.\n\n**파라미터:**\n- `chunkId`: 청크 ID\n- `contextSize`: 컨텍스트 윈도우 크기 (선택사항)\n\n## 🧪 테스트 및 검증\n\n### 1. 서버 작동 확인\n```bash\nnpm run dev\n```\n✅ 성공시 출력 예시:\n```\nInitializing knowledge-retrieval v1.0.0...\nLoaded 8 documents\nInitialized repository with 36 chunks from 8 documents\nMCP server started successfully\n```\n\n### 2. Claude Desktop에서 즉시 테스트\nClaude Desktop 재시작 후 다음 질문들로 테스트:\n\n```\n우리 회사의 비전과 미션이 뭐야?\nAI 플랫폼의 가격 정책을 알려줘\nAPI 인증 방법을 설명해줘\n```\n\n### 3. 빠른 문제 해결\n| 문제 | 해결 방법 |\n|------|-----------|\n| 서버 시작 실패 | `npm install \u0026\u0026 npm run build` |\n| 문서 로드 실패 | `docs/` 폴더와 `.md` 파일 확인 |\n| Claude Desktop 연결 실패 | 설정 파일 경로 확인 후 Claude Desktop 재시작 |\n\n## 📊 성능 최적화\n\n### BM25 파라미터 튜닝\n- **k1 값 증가**: 단어 빈도의 영향 증가 (1.2 → 2.0)\n- **b 값 조정**: 문서 길이 정규화 강도 (0.75 → 0.5)\n\n### 청크 크기 최적화\n- **minWords 증가**: 더 큰 컨텍스트, 느린 검색\n- **minWords 감소**: 정확한 매칭, 빠른 검색\n\n## 🔒 보안 고려사항\n\n1. **파일 권한**: 문서 디렉토리에 적절한 읽기 권한 설정\n2. **환경 변수**: 민감한 설정은 환경 변수로 관리\n3. **네트워크**: 필요시 방화벽 규칙 설정\n\n## 📝 환경 변수 설정\n\n```bash\nexport MCP_SERVER_NAME=\"my-knowledge-server\"\nexport DOCS_BASE_PATH=\"./my-docs\"\nexport BM25_K1=\"1.5\"\nexport BM25_B=\"0.8\"\nexport CHUNK_MIN_WORDS=\"50\"\nexport LOG_LEVEL=\"debug\"\n```\n\n## 🆘 문제 해결\n\n문제 발생 시 확인 순서:\n1. 로그 확인: `npm run dev` 출력 메시지\n2. 설정 파일: `config.json` 문법 오류 확인\n3. 문서 폴더: `docs/` 디렉토리와 `.md` 파일 확인\n4. Claude Desktop: 설정 파일 경로 및 재시작\n\n## 💡 핵심 요약\n\n### 즉시 사용을 위한 체크리스트\n**자동 설치 사용시:**\n- [ ] `./run.sh` (또는 `run.bat`) 실행\n- [ ] 스크립트가 출력하는 Claude Desktop 설정 복사\n- [ ] Claude Desktop 재시작\n- [ ] 테스트 질문으로 작동 확인\n\n**수동 설치 사용시:**\n- [ ] `npm install \u0026\u0026 npm run build \u0026\u0026 cp config.example.json config.json`\n- [ ] `docs/` 폴더에 마크다운 파일 추가\n- [ ] Claude Desktop 설정 파일에 프로젝트 경로 지정\n- [ ] Claude Desktop 재시작\n- [ ] 테스트 질문으로 작동 확인\n\n### 주요 명령어\n- **개발**: `npm run dev`\n- **빌드**: `npm run build`\n- **실행**: `npm start`\n- **테스트**: `npm test`\n\n---\n\n**MIT 라이선스** | **개발 중에는 `npm run dev` 사용 권장**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcskwork%2Fkeyword-rag-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcskwork%2Fkeyword-rag-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcskwork%2Fkeyword-rag-mcp/lists"}