Grounded Docs: AI를 위한 최신 문서 전문가

Docs MCP Server는 AI 코딩 어시스턴트를 위한 개인용 최신 문서 인덱스를 제공하여 AI의 환각 현상과 오래된 지식 문제를 해결합니다. 웹사이트, GitHub, npm, PyPI 및 로컬 파일에서 공식 문서를 가져와 AI가 사용 중인 정확한 버전을 쿼리할 수 있도록 합니다.

✨ 왜 Grounded Docs MCP Server인가요?

Context7, Nia, Ref.Tools의 오픈 소스 대안입니다.

• ✅ 최신 컨텍스트: 공식 소스에서 직접 문서를 요청 시 가져옵니다.

• 🎯 버전별 지원: 프로젝트에서 사용하는 정확한 라이브러리 버전을 대상으로 쿼리합니다.

• 💡 환각 현상 감소: LLM이 실제 문서에 기반하도록 합니다.

• 🔒 개인 및 로컬: 전적으로 사용자 기기에서 실행되며, 코드가 네트워크 외부로 유출되지 않습니다.

• 🧩 폭넓은 호환성: 모든 MCP 호환 클라이언트(Claude, Cline 등)와 작동합니다.

• 📁 다양한 소스: 웹사이트, GitHub 저장소, 로컬 폴더 및 zip 아카이브를 인덱싱합니다.

• 📄 풍부한 파일 지원: HTML, Markdown, PDF, Office 문서(Word, Excel, PowerPoint), OpenDocument, RTF, EPUB, Jupyter Notebook 및 90개 이상의 소스 코드 언어를 처리합니다.

Related MCP server: Documentation Search MCP Server

📄 지원되는 형식

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

🚀 빠른 시작

CLI 우선

에이전트 및 스크립트의 경우, CLI가 Grounded Docs를 사용하는 가장 간단한 방법입니다.

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

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

해시 라우팅된 SPA 문서 사이트의 경우, 해시 보존을 명시적으로 활성화하세요:

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

2. 인덱스 쿼리:

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

3. 단일 페이지를 Markdown으로 가져오기:

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

출력 동작

• 구조화된 명령은 비대화형 실행 시 stdout에서 기본적으로 깔끔한 JSON을 출력합니다.

• --output json|yaml|toon을 사용하여 구조화된 형식을 선택하세요.

• fetch-url과 같은 일반 텍스트 명령은 텍스트 페이로드를 stdout에 유지합니다.

• 진단 정보는 공유 로거를 통해 전달되며 비대화형 실행 시 stdout에서 제외됩니다.

• 오류가 아닌 진단 정보를 억제하려면 --quiet를 사용하고, 디버그 출력을 활성화하려면 --verbose를 사용하세요.

에이전트 스킬

skills/ 디렉토리에는 AI 코딩 어시스턴트에게 문서 검색, 인덱스 관리 및 URL 가져오기 방법을 가르치는 Agent Skills가 포함되어 있습니다.

MCP 서버

Claude, Cline, Copilot, Gemini CLI 또는 기타 MCP 클라이언트를 위한 장기 실행 MCP 엔드포인트가 필요한 경우:

1. 서버 시작:

npx @arabold/docs-mcp-server@latest

2. http://localhost:6280에서 웹 UI를 열어 문서를 추가합니다.

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

{
  "mcpServers": {
    "docs-mcp-server": {
      "type": "sse",
      "url": "http://localhost:6280/sse"
    }
  }
}

VS Code(Cline, Roo) 및 기타 설정 옵션은 **클라이언트 연결**을 참조하세요.

scrape_docs는 해시 기반 클라이언트 측 라우팅을 사용하는 문서 사이트를 위해 preserveHashes: true도 허용합니다. 해시 라우팅된 SPA에만 사용하세요. 일반 사이트는 일반적으로 페이지 내 앵커에 해시 조각을 사용합니다.

docker run --rm \
  -v docs-mcp-data:/data \
  -v docs-mcp-config:/config \
  -p 6280:6280 \
  ghcr.io/arabold/docs-mcp-server:latest \
  --protocol http --host 0.0.0.0 --port 6280

🧠 임베딩 모델 구성 (권장)

임베딩 모델 사용은 선택 사항이지만, 의미론적 벡터 검색을 활성화하여 검색 품질을 크게 향상시킵니다.

예: OpenAI 임베딩 활성화

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

Ollama, Gemini, Azure 등을 구성하는 방법은 **임베딩 모델**을 참조하세요.

📚 문서

시작하기

• 설치: Docker, Node.js (npx) 및 임베디드 모드에 대한 상세 설정 가이드.

• 클라이언트 연결: Claude, VS Code (Cline/Roo) 및 기타 MCP 클라이언트를 연결하는 방법.

• 기본 사용법: 웹 UI, CLI 사용 및 로컬 파일 스크랩 방법.

• 구성: 설정 파일 및 환경 변수에 대한 전체 참조.

• 지원되는 형식: 전체 파일 형식 및 MIME 유형 참조.

• 임베딩 모델: OpenAI, Ollama, Gemini 및 기타 제공업체 구성 방법.

해시 라우팅된 SPA

• #/guide와 같은 URL로 라우팅되는 문서 사이트에 대해서만 --preserve-hashes, MCP preserveHashes 또는 웹 UI의 "Preserve Hash Routes" 체크박스를 사용하세요.

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

• 새로 고침은 기본적으로 저장된 preserveHashes 설정을 재사용하며, CLI/웹 새로 고침 진입점에서 이를 명시적으로 재정의할 수 있습니다.

핵심 개념 및 아키텍처

• 배포 모드: 독립형 vs 분산형 (Docker Compose).

• 인증: OAuth2/OIDC로 서버 보안 강화.

• 텔레메트리: 개인정보 보호 우선 사용 데이터 수집.

• 아키텍처: 시스템 설계에 대한 심층 분석.

🤝 기여

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

라이선스

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