mcp-server-docy

Docy: AI가 손쉽게 이용할 수 있는 문서

기술 문서에 즉시 액세스하여 AI 비서의 역량을 강화하세요.

Docy는 AI가 필요한 기술 문서에 필요한 순간에 바로 접근할 수 있도록 지원합니다. 더 이상 오래된 정보, 깨진 링크, 속도 제한 없이, 더욱 정밀한 코딩 지원을 위한 정확하고 실시간 문서 접근만 가능합니다.

왜 Docy를 선택해야 할까요?

• 즉각적인 문서 액세스 : React, Python, crawl4ai 및 사용하는 다른 기술 스택의 문서에 직접 액세스
• 핫 리로드 지원 : 재시작 없이 바로 새로운 문서 소스를 추가하세요. .docy.urls 파일만 편집하면 됩니다!
• 지능형 캐싱 : 최신 콘텐츠를 유지하면서 대기 시간과 외부 요청을 줄입니다.
• 자체 호스팅 제어 : 보안 경계 내에서 문서 액세스를 유지하세요
• 원활한 MCP 통합 : Claude, VS Code 및 기타 MCP 지원 AI 도구와 손쉽게 연동

참고 : Claude는 기본적으로 Docy 대신 내장된 WebFetchTool을 사용할 수 있습니다. Docy 기능을 명시적으로 요청하려면 "Docy를 사용하여..."와 같은 콜아웃을 사용하세요.

Docy MCP 서버

문서 접근 기능을 제공하는 모델 컨텍스트 프로토콜(Model Context Protocol) 서버입니다. 이 서버를 통해 LLM은 crawl4ai를 사용하여 문서 웹사이트의 콘텐츠를 스크래핑하여 검색하고 가져올 수 있습니다. FastMCP v2로 구축되었습니다.

Docy 사용하기

다음은 Docy가 일반적인 문서화 작업에 어떻게 도움을 줄 수 있는지에 대한 예입니다.

지엑스피1

Claude Code는 Docy를 사용하여 구성된 소스의 문서에 직접 액세스하고 분석할 수 있으므로, 정확하고 문서 기반의 지침을 제공하는 데 더 효과적입니다.

Claude Code가 문서화 관련 작업에 대해 Docy를 우선시하도록 하려면 프로젝트의 CLAUDE.md 파일에 다음 지침을 추가하세요.

이러한 지침을 CLAUDE.md 파일에 추가하면 Claude Code가 문서 작업 시 내장된 웹 가져오기 기능 대신 Docy를 일관되게 사용하는 데 도움이 됩니다.

사용 가능한 도구

• list_documentation_sources_tool - 사용 가능한 모든 문서 소스를 나열합니다.
  • 매개변수가 필요하지 않습니다
• fetch_documentation_page - URL을 통해 문서 페이지의 내용을 마크다운으로 가져옵니다.
  • url (문자열, 필수): 콘텐츠를 가져올 URL
• fetch_document_links - 문서 페이지에서 모든 링크를 가져옵니다.
  • url (문자열, 필수): 링크를 가져올 URL

프롬프트

• 문서_소스
  • 사용 가능한 모든 문서 소스를 URL 및 유형과 함께 나열합니다.
  • 인수가 필요하지 않습니다
• 설명서 페이지
  • 특정 URL의 문서 페이지 전체 내용을 마크다운으로 가져옵니다.
  • 인수:
    • url (문자열, 필수): 가져올 특정 문서 페이지의 URL
• 설명서 링크
  • 문서 페이지에서 모든 링크를 가져와 관련 콘텐츠를 검색합니다.
  • 인수:
    • url (문자열, 필수): 링크를 가져올 문서 페이지의 URL

설치

uv 사용(권장)

uv 사용하면 별도의 설치가 필요하지 않습니다. uvx 사용하여 mcp-server-docy를 직접 실행합니다.

PIP 사용

또는 pip를 통해 mcp-server-docy 설치할 수 있습니다.

설치 후 다음을 사용하여 스크립트로 실행할 수 있습니다.

Docker 사용하기

Docker 이미지를 사용할 수도 있습니다.

글로벌 서버 설정

팀 또는 여러 프로젝트 개발의 경우, 여러 프로젝트에서 공유 가능한 영구 SSE 서버를 실행하는 방법은 server/README.md 파일을 참조하세요. 이 설정을 사용하면 공유 문서 URL과 캐시를 사용하여 단일 Docy 인스턴스를 유지할 수 있습니다.

구성

Claude.app에 대한 구성

Claude 설정에 추가:

VS Code에 대한 구성

수동 설치의 경우, VS Code의 사용자 설정(JSON) 파일에 다음 JSON 블록을 추가하세요. Ctrl + Shift + P 를 누르고 Preferences: Open User Settings (JSON) 입력하면 됩니다.

원하는 경우, 작업 공간의 .vscode/mcp.json 파일에 추가할 수 있습니다. 이렇게 하면 다른 사용자와 구성을 공유할 수 있습니다.

mcp.json 파일을 사용하려면 mcp 키가 필요합니다.

구성 옵션

환경 변수를 사용하여 애플리케이션을 구성할 수 있습니다.

• DOCY_DOCUMENTATION_URLS (문자열): 포함할 문서 사이트의 URL을 쉼표로 구분하여 나열한 목록(예: " https://docs.crawl4ai.com/,https://react.dev/ ")
• DOCY_DOCUMENTATION_URLS_FILE (문자열): 한 줄에 하나씩 문서 URL이 포함된 파일의 경로(기본값: ".docy.urls")
• DOCY_CACHE_TTL (정수): 캐시 수명(초)(기본값: 432000)
• DOCY_CACHE_DIRECTORY (문자열): 캐시 디렉토리 경로(기본값: ".docy.cache")
• DOCY_USER_AGENT (문자열): HTTP 요청에 대한 사용자 정의 사용자 에이전트 문자열
• DOCY_DEBUG (부울): 디버그 로깅을 활성화합니다("true", "1", "yes" 또는 "y")
• DOCY_SKIP_CRAWL4AI_SETUP (부울): 시작 시 crawl4ai-setup 명령 실행을 건너뜁니다("true", "1", "yes" 또는 "y")
• DOCY_TRANSPORT (문자열): 사용할 전송 프로토콜(옵션: "sse" 또는 "stdio", 기본값: "stdio")
• DOCY_HOST (문자열): 서버를 바인딩할 호스트 주소(기본값: "127.0.0.1")
• DOCY_PORT (정수): 서버를 실행할 포트(기본값: 8000)

환경 변수는 직접 또는 .env 파일을 통해 설정할 수 있습니다.

URL 구성 파일

DOCY_DOCUMENTATION_URLS 환경 변수를 설정하는 것 외에도 프로젝트 디렉토리에 한 줄에 URL이 하나씩 있는 .docy.urls 파일을 만들 수 있습니다.

이 접근 방식은 특히 다음과 같은 경우에 유용합니다.

• 팀과 문서 소스를 공유하려는 프로젝트
• 버전 제어에 URL을 저장하는 것이 유용한 저장소
• 긴 환경 변수 값을 피하고 싶은 상황

서버는 먼저 DOCY_DOCUMENTATION_URLS 환경 변수에서 URL을 확인하고, 아무것도 발견되지 않으면 .docy.urls 파일을 찾습니다.

URL 파일에 대한 핫 리로드

문서 소스에 .docy.urls 파일을 사용할 때, 서버는 URL을 캐싱하는 대신 각 요청 시 파일을 읽는 핫 리로드 메커니즘을 구현합니다. 즉, 다음과 같은 작업이 가능합니다.

1. 서버가 실행되는 동안 .docy.urls 파일에서 문서 URL을 추가, 제거 또는 수정합니다.
2. 이후 list_documentation_sources_tool 또는 기타 문서 도구 호출 시 해당 변경 사항이 즉시 반영되는 것을 확인하세요.
3. 문서 소스를 수정할 때 서버를 다시 시작하지 마십시오.

이 기능은 특히 개발 중이거나 실행 중인 서버에 새로운 문서 소스를 빠르게 추가해야 할 때 유용합니다.

문서 URL 모범 사례

구성하는 URL은 이상적으로 다음이 포함된 문서 인덱스 또는 소개 페이지를 가리켜야 합니다.

• 목차
• 항해 구조
• 내부 및 외부 링크 모음

이를 통해 LLM은 다음을 수행할 수 있습니다.

1. 상위 수준 문서 페이지에서 시작하세요
2. 링크를 통해 관련 하위 페이지를 찾아보세요
3. 필요에 따라 특정 문서로 이동하세요

잘 구성된 하위 페이지가 있는 문서 사이트를 사용하는 것이 좋습니다. 그 이유는 다음과 같습니다.

• LLM이 관련 섹션에 집중할 수 있도록 하여 컨텍스트 사용을 최소화합니다.
• 문서화를 통해 탐색 효율성을 향상시킵니다.
• 자연스러운 방식으로 정보를 탐색하고 찾을 수 있는 방법을 제공합니다.
• 전체 문서 세트를 한 번에 로드해야 하는 필요성이 줄어듭니다.

예를 들어, 전체 문서 사이트를 로드하는 대신 LLM은 인덱스 페이지에서 시작하여 관련 섹션을 식별한 다음 필요에 따라 특정 하위 페이지로 이동할 수 있습니다.

캐싱 동작

MCP 서버는 성능을 개선하기 위해 문서 콘텐츠를 자동으로 캐시합니다.

• 시작 시 서버는 DOCY_DOCUMENTATION_URLS 에서 구성된 모든 문서 URL을 미리 가져와 캐시합니다.
• 캐시 TTL(수명)은 DOCY_CACHE_TTL 환경 변수를 통해 구성할 수 있습니다.
• 접속된 각각의 새 사이트는 트래픽을 줄이고 응답 시간을 개선하기 위해 자동으로 캐시에 로드됩니다.
• 캐시된 콘텐츠는 diskcache 라이브러리를 사용하여 영구 디스크 기반 캐시에 저장됩니다.
• 캐시 위치는 DOCY_CACHE_DIRECTORY 환경 변수를 통해 구성할 수 있습니다(기본값: ".docy.cache")
• 캐시는 서버를 다시 시작할 때마다 유지되므로 자주 액세스하는 문서에 대한 성능이 향상됩니다.

캐싱에 대한 예외

대부분의 콘텐츠는 성능을 위해 캐시되지만 다음과 같은 특정 예외가 있습니다.

• 문서 URL 목록 : .docy.urls 파일을 사용하는 경우 문서 소스 목록은 캐시되지 않습니다. 대신 URL의 핫 리로딩을 지원하기 위해 각 요청 시 파일을 다시 읽습니다.
• 페이지 콘텐츠 : 문서 페이지의 실제 콘텐츠는 구성된 TTL에 따라 계속 캐시됩니다.

이러한 하이브리드 방식은 콘텐츠 액세스에 대한 성능상의 이점과 문서 소스 관리에 대한 유연성을 모두 제공합니다.

지역 개발

• 개발 모드에서 실행: fastmcp dev src/mcp_server_docy/__main__.py --with-editable .
• API에 접속하려면 http://127.0.0.1:6274 로 접속하세요.
• MCP 검사기로 실행: uv run --with fastmcp --with-editable /Users/oliverborchers/Desktop/Code.nosync/mcp-server-docy --with crawl4ai --with loguru --with diskcache --with pydantic-settings fastmcp run src/mcp_server_docy/__main__.py

디버깅

MCP 검사기를 사용하여 서버를 디버깅할 수 있습니다. UVX 설치의 경우:

또는 특정 디렉토리에 패키지를 설치했거나 해당 디렉토리에서 개발 중인 경우:

문제 해결: Claude Code CLI에서 "도구를 찾을 수 없습니다" 오류 발생

Claude Code CLI에서 "mcp__docy__fetch_documentation_page에 대한 오류 도구를 찾을 수 없습니다"와 같은 오류가 발생하면 다음 단계를 따르세요.

1. 현재 디렉토리에 문서 URL이 포함된 .docy.urls 파일을 만듭니다.

2. SSE 전송 프로토콜을 사용하여 Docker를 사용하여 서버를 실행하고 URL 파일을 마운트합니다.

3. SSE 엔드포인트를 사용하도록 Claude Code .mcp.json 구성하세요.

이 구성:

• 환경 변수 대신 문서 소스에 마운트된 .docy.urls 파일을 사용합니다.
• 기본 stdio 모드에서 SSE(Server-Sent Events) 프로토콜로 전환합니다.
• 컨테이너 외부에서 서버에 접근할 수 있게 합니다.
• HTTP 액세스를 위해 포트 8000에서 서버를 노출합니다.

HTTP를 통해 액세스해야 하는 독립 실행형 서비스로 서버를 실행할 경우 SSE 전송이 권장되며, 이는 특히 Docker 배포에 유용합니다.

릴리스 프로세스

이 프로젝트에서는 자동화된 릴리스를 위해 GitHub Actions를 사용합니다.

1. pyproject.toml 에서 버전을 업데이트하세요
2. git tag vX.YZ 로 새 태그를 만듭니다(예: git tag v0.1.0 )
3. git push --tags 로 태그를 푸시합니다.

이렇게 하면 자동으로 다음이 수행됩니다.

• pyproject.toml 의 버전이 태그와 일치하는지 확인하세요.
• 테스트 및 린트 검사 실행
• PyPI에 빌드하고 게시
• oborchers/mcp-server-docy:latest 및 oborchers/mcp-server-docy:XYZ 로 Docker Hub에 빌드하고 게시합니다.

기여하다

mcp-server-docy의 확장 및 개선을 위한 여러분의 기여를 기다립니다. 새로운 기능 추가, 기존 기능 개선, 문서 개선 등 어떤 목적이든 여러분의 의견은 소중합니다.

다른 MCP 서버 및 구현 패턴의 예는 https://github.com/modelcontextprotocol/servers를 참조하세요.

풀 리퀘스트를 환영합니다! mcp-server-docy를 더욱 강력하고 유용하게 만들기 위한 새로운 아이디어, 버그 수정, 개선 사항을 자유롭게 공유해 주세요.

특허

mcp-server-docy는 MIT 라이선스에 따라 라이선스가 부여됩니다. 즉, MIT 라이선스의 조건에 따라 소프트웨어를 자유롭게 사용, 수정 및 배포할 수 있습니다. 자세한 내용은 프로젝트 저장소의 LICENSE 파일을 참조하세요.