Docs MCP Server는 AI 코딩 어시스턴트를 위해 항상 최신 상태를 유지하는 개인용 문서 인덱스를 제공함으로써 AI의 환각 (Hallucination) 및 오래된 지식 문제를 해결합니다. 이 도구는 웹사이트, GitHub, npm, PyPI 및 로컬 파일에서 공식 문서를 가져와, 사용 중인 정확한 버전에 대해 AI가 질의할 수 있도록 합니다.

Context7, Nia, 그리고 Ref.Tools를 대체할 수 있는 오픈 소스 대안입니다.

• ✅ 최신 컨텍스트 (Up-to-Date Context): 필요할 때 공식 소스에서 문서를 직접 가져옵니다. - 🎯 버전 특정 (Version-Specific): 프로젝트 내의 정확한 라이브러리 버전을 대상으로 질의합니다. - 💡 환각 감소 (Reduces Hallucinations): LLM (대규모 언어 모델)을 실제 문서에 기반하도록 근거를 제공합니다. - 🔒 프라이빗 및 로컬 (Private & Local): 완전히 사용자의 기기에서 실행되며, 코드는 네트워크를 벗어나지 않습니다. - 🧩 폭넓은 호환성 (Broad Compatibility): 모든 MCP 호환 클라이언트 (Claude, Cline 등)와 작동합니다. - 📁 다양한 소스 (Multiple Sources): 웹사이트, GitHub 저장소, 로컬 폴더 및 zip 아카이브를 인덱싱합니다. - 📄 풍부한 파일 지원 (Rich File Support): HTML, Markdown, PDF, Office 문서 (Word, Excel, PowerPoint), OpenDocument, RTF, EPUB, Jupyter Notebooks 및 90개 이상의 소스 코드 언어를 처리합니다.

카테고리	형식
문서 (Documents)	PDF, Word (.docx/.doc), Excel (.xlsx/.xls), PowerPoint (.pptx/.ppt), OpenDocument (.odt/.ods/.odp), RTF, EPUB, FictionBook, Jupyter Notebooks
아카이브 (Archives)	ZIP, TAR, gzipped TAR (콘텐츠는 개별적으로 추출 및 처리됨)
웹 (Web)	HTML, XHTML
마크업 (Markup)	Markdown, MDX, reStructuredText, AsciiDoc, Org Mode, Textile, R Markdown
소스 코드 (Source Code)	TypeScript, JavaScript, Python, Go, Rust, C/C++, Java, Kotlin, Ruby, PHP, Swift, C# 및 기타 다수
데이터 (Data)	JSON, YAML, TOML, CSV, XML, SQL, GraphQL, Protocol Buffers
설정 (Config)	Dockerfile, Makefile, Terraform/HCL, INI, dotenv, Bazel

MIME 유형 및 처리 세부 정보를 포함한 전체 참조는 **지원되는 형식 (Supported Formats)**을 확인하세요.

에이전트 및 스크립트의 경우, CLI (명령줄 인터페이스)가 Grounded Docs를 사용하는 가장 간단한 방법입니다.

1. 문서 인덱싱 (Node.js 22 이상 필요):

npx @arabold/docs-mcp-server@latest scrape react https://react.dev/reference/react

해시 라우팅 (hash-routed) 방식의 SPA 문서 사이트의 경우, 해시 보존 (hash preservation)을 명시적으로 활성화하십시오:

npx @arabold/docs-mcp-server@latest scrape my-spa https://docs.example.com/#/guide --preserve-hashes

2. 인덱스 쿼리 (Query the index):

npx @arabold/docs-mcp-server@latest search react "useEffect cleanup" --output yaml

3. 단일 페이지를 Markdown으로 가져오기 (Fetch a single page as Markdown):

npx @arabold/docs-mcp-server@latest fetch-url https://react.dev/reference/react/useEffect

• 구조화된 명령 (Structured commands)은 비대화형 실행 (non-interactive runs) 시 표준 출력 (stdout)에 깔끔한 JSON 형태로 출력되는 것이 기본값입니다.
• 구조화된 형식을 선택하려면 --output json|yaml|toon을 사용하십시오.
• fetch-url과 같은 일반 텍스트 명령은 텍스트 페이로드 (text payload)를 표준 출력 (stdout)에 유지합니다.
• 진단 정보 (Diagnostics)는 공유 로거 (shared logger)를 통해 전달되며, 비대화형 실행 시 표준 출력 (stdout)에는 출력되지 않습니다.
• 에러가 아닌 진단 정보를 억제하려면 --quiet를 사용하거나, 디버그 출력 (debug output)을 활성화하려면 --verbose를 사용하십시오.

skills/ 디렉토리에는 AI 코딩 어시스턴트에게 CLI 사용법을 가르치는 에이전트 스킬 (Agent Skills)이 포함되어 있으며, 여기에는 문서 검색, 인덱스 관리 및 URL 가져오기가 포함됩니다.

Claude, Cline, Copilot, Gemini CLI 또는 기타 MCP 클라이언트를 위해 장기 실행되는 MCP 엔드포인트 (endpoint)를 원하는 경우:

1. 서버 시작:

npx @arabold/docs-mcp-server@latest

2. Web UI를 http://localhost:6280 에서 열어 문서를 추가하십시오.

3. MCP 설정(예: claude_desktop_config.json)에 다음을 추가하여 AI 클라이언트를 연결하십시오:

{
"mcpServers": {
"docs-mcp-server": {
...

VS Code (Cline, Roo) 및 기타 설정 옵션에 대해서는 **클라이언트 연결 (Connecting Clients)**을 참조하십시오.

scrape_docs는 해시 기반 클라이언트 사이드 라우팅 (client-side routing)을 사용하는 문서 사이트를 위해 preserveHashes: true 옵션도 허용합니다. 이는 해시 라우팅되는 SPA에만 사용하십시오. 일반적인 사이트는 보통 페이지 내 앵커 (anchors)를 위해 해시 프래그먼트 (hash fragments)를 사용합니다.

대안: Docker로 실행

docker run --rm \
-v docs-mcp-data:/data \
-v docs-mcp-config:/config \
...

임베딩 모델 (Embedding model)을 사용하는 것은 선택 사항이지만, 시맨틱 벡터 검색 (Semantic vector search)을 가능하게 하여 검색 품질을 획기적으로 향상시킵니다.

예시: OpenAI Embeddings 활성화

OPENAI_API_KEY="sk-proj-..." npx @arabold/docs-mcp-server@latest

Ollama, Gemini, Azure 및 기타 모델을 구성하려면 Embedding Models 섹션을 참조하세요.

설치 (Installation): Docker, Node.js (npx), 및 임베디드 모드 (Embedded mode)에 대한 상세 설정 가이드.
클라이언트 연결 (Connecting Clients): Claude, VS Code (Cline/Roo) 및 기타 MCP 클라이언트를 연결하는 방법.
기본 사용법 (Basic Usage): Web UI, CLI 및 로컬 파일 스크래핑 (Scraping) 사용법.
설정 (Configuration): 설정 파일 및 환경 변수에 대한 전체 레퍼런스.
지원 형식 (Supported Formats): 파일 형식 및 MIME 타입 전체 레퍼런스.
임베딩 모델 (Embedding Models): OpenAI, Ollama, Gemini 및 기타 제공업체 구성.
검색 품질 벤치마크 (Search Quality Benchmark): IR 지표 및 LLM 판정 점수를 통한 검색 품질 측정; 전제 조건, 실행 방법, 결과 해석 방법.

• #/guide와 같이 해시(Hash)가 포함된 URL로 라우팅되는 문서 사이트의 경우에만 --preserve-hashes, MCP preserveHashes, 또는 Web UI의 "Preserve Hash Routes" 체크박스를 사용하세요.

• scrapeMode=fetch와 함께 활성화하면, 일반적인 fetch는 클라이언트 측 해시 라우트를 평가할 수 없기 때문에 스크래퍼가 자동으로 작업을 Playwright로 업그레이드합니다.

• 새로고침 (Refresh) 시 기본적으로 저장된 preserveHashes 설정을 재사용하며, CLI/Web 새로고침 엔트리포인트(Entrypoint)에서 이를 명시적으로 재정의할 수 있습니다.

• Web 스크래핑 및 새로고침 시, 일반적인 크롤링 (Crawling)을 수행하기 전에 문서 하위 경로 및 사이트 루트에서 llms.txt를 자동으로 탐색합니다. llms.txt가 발견되면, 큐레이션된 링크들이 추가적인 크롤링 시드 (Crawl seeds)가 되며, 이 방식으로 발견된 페이지들은 원래 페이지로 돌아가기 전에 /guide/index.html.md 또는 /page.html.md와 같은 .md URL 변형을 우선적으로 탐색합니다.

• Web 요청은 Accept: text/markdown, text/html;q=0.9, */*;q=0.8 헤더를 전송합니다.

기본적으로 Cloudflare Markdown for Agents를 포함하여 Markdown 콘텐츠 협상 (Content Negotiation)을 지원하는 서버는 Markdown을 직접 반환할 수 있으므로, 스크레이퍼 (Scraper)가 더 깔끔한 출력을 위해 HTML-to-Markdown 변환 과정을 건너뛸 수 있습니다. 이러한 동작은 자동으로 이루어지며 별도의 설정이 필요하지 않습니다. 사용자 정의 Accept 헤더가 제공되는 경우 해당 헤더는 그대로 유지됩니다.

배포 모드 (Deployment Modes): 단독형 (Standalone) vs 분산형 (Distributed, Docker Compose).
인증 (Authentication): OAuth2/OIDC를 통한 서버 보안.
보안 (Security): 신뢰 경계 (Trust boundaries), 배포 강화 (Deployment hardening), 그리고 아웃바운드 액세스 제어.
텔레메트리 (Telemetry): 개인정보 보호를 우선시하는 사용 데이터 수집.
아키텍처 (Architecture): 시스템 설계에 대한 심층 분석.

기여를 환영합니다! 개발 가이드라인 및 설정 지침은 CONTRIBUTING.md를 참조해 주세요.

이 프로젝트는 MIT 라이선스 하에 라이선스가 부여됩니다. 자세한 내용은 LICENSE를 참조하세요.