docs-mcp-server MCP 서버

타사 패키지 문서를 가져오고 검색하기 위한 MCP 서버입니다.

✨ 주요 특징

• 🌐 다양한 스크래핑: 웹사이트, GitHub, npm, PyPI 또는 로컬 파일 등 다양한 소스에서 문서를 가져옵니다.
• 🧠 지능형 처리: 콘텐츠를 의미적으로 자동 분할하고 선택한 모델(OpenAI, Google Gemini, Azure OpenAI, AWS Bedrock, Ollama 등)을 사용하여 임베딩을 생성합니다.
• 💾 최적화된 저장소: 효율적인 벡터 저장을 위해 sqlite-vec 와 SQLite를 활용하고, 강력한 전체 텍스트 검색을 위해 FTS5를 활용합니다.
• 🔍 강력한 하이브리드 검색: 다양한 라이브러리 버전에서 벡터 유사성과 전체 텍스트 검색을 결합하여 관련성이 높은 결과를 제공합니다.
• ⚙️ 비동기 작업 처리: 백그라운드 작업 대기열과 MCP/CLI 도구를 사용하여 스크래핑 및 인덱싱 작업을 효율적으로 관리합니다.
• 🐳 간단한 배포: Docker나 npx를 사용하여 빠르게 시작하고 실행할 수 있습니다.

개요

이 프로젝트는 다양한 소프트웨어 라이브러리 및 패키지에 대한 문서를 스크래핑, 처리, 색인 및 검색하도록 설계된 모델 컨텍스트 프로토콜(MCP) 서버를 제공합니다. 지정된 URL에서 콘텐츠를 가져오고, 의미론적 분할 기법을 사용하여 의미 있는 청크로 분할하고, OpenAI를 사용하여 벡터 임베딩을 생성하고, SQLite 데이터베이스에 데이터를 저장합니다. 이 서버는 효율적인 벡터 유사성 검색을 위해 sqlite-vec , 전체 텍스트 검색 기능을 위해 FTS5를 활용하며, 이 두 가지를 결합하여 하이브리드 검색 결과를 제공합니다. 버전 관리를 지원하여 다양한 라이브러리 버전(버전이 지정되지 않은 콘텐츠 포함)에 대한 문서를 개별적으로 저장하고 쿼리할 수 있습니다.

서버는 다음에 대한 MCP 도구를 제공합니다.

• 스크래핑 작업 시작( scrape_docs ): jobId 즉시 반환합니다.
• 작업 상태 확인( get_job_status ): 특정 작업의 현재 상태와 진행 상황을 검색합니다.
• 활성/완료된 작업 나열( list_jobs ): 최근 및 진행 중인 작업을 표시합니다.
• 작업 취소( cancel_job ): 실행 중이거나 대기 중인 작업을 중지하려고 시도합니다.
• 문서 검색( search_docs )
• 인덱싱된 라이브러리 나열( list_libraries )
• 적절한 버전 찾기( find_version ).
• 인덱스된 문서 제거( remove_docs ).
• 단일 URL 가져오기( fetch_url ): URL을 가져와서 해당 내용을 마크다운으로 반환합니다.

구성

다음 환경 변수는 임베딩 모델 동작을 구성하는 데 지원됩니다.

임베딩 모델 구성

• DOCS_MCP_EMBEDDING_MODEL : 선택 사항입니다. 형식: provider:model_name 또는 model_name (기본값: text-embedding-3-small ). 지원되는 공급자 및 필수 환경 변수는 다음과 같습니다.
  • openai (기본값): OpenAI의 임베딩 모델을 사용합니다.
    • OPENAI_API_KEY : 필수. OpenAI API 키입니다.
    • OPENAI_ORG_ID : 선택 사항. OpenAI 조직 ID입니다.
    • OPENAI_API_BASE : 선택 사항. OpenAI 호환 API(예: Ollama, Azure OpenAI)에 대한 사용자 지정 기본 URL입니다.
  • vertex : Google Cloud Vertex AI 임베딩을 사용합니다.
    • GOOGLE_APPLICATION_CREDENTIALS : 필수. 서비스 계정 JSON 키 파일 경로입니다.
  • gemini : Google Generative AI(제미니) 임베딩을 사용합니다.
    • GOOGLE_API_KEY : 필수. Google API 키입니다.
  • aws : AWS Bedrock 임베딩을 사용합니다
    • AWS_ACCESS_KEY_ID : 필수. AWS 액세스 키
    • AWS_SECRET_ACCESS_KEY : 필수. AWS 비밀 키
    • AWS_REGION 또는 BEDROCK_AWS_REGION : 필수. Bedrock용 AWS 리전입니다.
  • microsoft : Azure OpenAI 임베딩 사용
    • AZURE_OPENAI_API_KEY : 필수. Azure OpenAI API 키
    • AZURE_OPENAI_API_INSTANCE_NAME : 필수. Azure 인스턴스 이름입니다.
    • AZURE_OPENAI_API_DEPLOYMENT_NAME : 필수. Azure 배포 이름입니다.
    • AZURE_OPENAI_API_VERSION : 필수. Azure API 버전입니다.

벡터 차원

데이터베이스 스키마는 벡터 임베딩에 1536의 고정된 차원을 사용합니다. 차원 축소를 지원하는 특정 제공자(예: Gemini)를 제외하고, 차원이 1536 이하인 벡터를 생성하는 모델만 지원됩니다.

OpenAI 호환 API(예: Ollama)의 경우 엔드포인트를 가리키는 OPENAI_API_BASE 와 함께 openai 공급자를 사용하세요.

이러한 변수는 서버를 실행하는 방법(Docker, npx 또는 소스)에 관계없이 설정할 수 있습니다.

MCP 서버 실행

docs-mcp-server를 실행하는 방법은 두 가지가 있습니다.

옵션 1: Docker 사용(권장)

이 방법은 대부분의 사용자에게 권장됩니다. 쉽고 직관적이며 Node.js를 설치할 필요가 없습니다.

1. Docker가 설치되어 실행 중인지 확인하세요.
2. MCP 설정을 구성하세요.Claude/Cline/Roo 구성 예: 다음 구성 블록을 MCP 설정 파일에 추가합니다(필요에 따라 경로를 조정).지엑스피1"sk-proj-..." 실제 OpenAI API 키로 바꾸고 애플리케이션을 다시 시작하세요.
3. 이제 AI 비서가 서버를 사용할 수 있습니다.

Docker 컨테이너 설정:

• -i : STDIN을 열어두는 것은 stdio를 통한 MCP 통신에 필수적입니다.
• --rm : 컨테이너가 종료될 때 자동으로 제거합니다.
• -e OPENAI_API_KEY : 필수. OpenAI API 키를 설정하세요.
• -v docs-mcp-data:/data : 지속성을 위해 필수입니다. docs-mcp-data 라는 이름의 Docker 볼륨을 마운트하여 데이터베이스를 저장합니다. 원하는 경우 특정 호스트 경로로 바꿀 수 있습니다(예: -v /path/on/host:/data ).

모든 구성 환경 변수(위의 구성 참조)는 -e 플래그를 사용하여 컨테이너에 전달할 수 있습니다. 예:

옵션 2: npx 사용

로컬 파일 접근이 필요할 때(예: 로컬 파일 시스템에서 문서 인덱싱) 이 방법이 권장됩니다. Docker 컨테이너에 경로를 마운트하여 접근할 수도 있지만, npx를 사용하는 것이 더 간단하지만 Node.js 설치가 필요합니다.

1. Node.js가 설치되어 있는지 확인하세요.
2. MCP 설정을 구성하세요.Claude/Cline/Roo 구성 예: MCP 설정 파일에 다음 구성 블록을 추가합니다.
   { "mcpServers": { "docs-mcp-server": { "command": "npx", "args": ["-y", "--package=@arabold/docs-mcp-server", "docs-server"], "env": { "OPENAI_API_KEY": "sk-proj-..." // Required: Replace with your key }, "disabled": false, "autoApprove": [] } } }
   "sk-proj-..." 실제 OpenAI API 키로 바꾸고 애플리케이션을 다시 시작하세요.
3. 이제 AI 비서가 서버를 사용할 수 있습니다.

CLI 사용

Docker 또는 npx를 통해 CLI를 사용하여 문서를 직접 관리할 수 있습니다. 중요: 동일한 색인 문서에 대한 액세스를 보장하려면 서버와 CLI 모두에 동일한 방법(Docker 또는 npx)을 사용하세요.

Docker CLI 사용

Docker로 서버를 실행하는 경우 CLI에도 Docker를 사용하세요.

서버에 사용한 것과 동일한 볼륨 이름(이 예에서는 docs-mcp-data )을 사용해야 합니다. 모든 구성 환경 변수(위의 구성 참조)는 서버와 마찬가지로 -e 플래그를 사용하여 전달할 수 있습니다.

npx CLI 사용

npx로 서버를 실행하는 경우 CLI에도 npx를 사용하세요.

npx 방식은 시스템의 기본 데이터 디렉터리(일반적으로 홈 디렉터리)를 사용하여 서버와 CLI 간의 일관성을 보장합니다.

(사용 가능한 명령과 옵션은 아래의 "CLI 명령 참조"를 참조하세요.)

CLI 명령 참조

docs-cli 문서 색인을 관리하는 명령을 제공합니다. Docker( docker run -v docs-mcp-data:/data ghcr.io/arabold/docs-mcp-server:latest docs-cli ... ) 또는 npx ( npx -y --package=@arabold/docs-mcp-server docs-cli ... )를 통해 액세스할 수 있습니다.

일반 도움말:

명령어별 도움말: (전역적으로 설치되지 않은 경우 docs-cli npx... 명령어로 바꾸세요)

단일 URL 가져오기( fetch-url )

단일 URL을 가져와서 해당 내용을 마크다운으로 변환합니다. scrape 와 달리, 이 명령은 링크를 크롤링하거나 내용을 저장하지 않습니다.

옵션:

• --no-follow-redirects : HTTP 리디렉션을 따르지 않습니다(기본값: 리디렉션을 따릅니다)

예:

문서 스크래핑( scrape )

특정 도서관에 대한 문서를 주어진 URL에서 스크래핑하고 인덱싱합니다.

옵션:

• -v, --version <string> : 스크래핑된 문서와 연결할 특정 버전입니다.
  • 전체 버전( 1.2.3 ), 사전 릴리스 버전( 1.2.3-beta.1 ) 또는 부분 버전( 1 , 1.2``1.0.0 , 1.2.0 으로 확장됨))을 허용합니다.
  • 생략하면 문서는 버전 없음 으로 색인됩니다.
• -p, --max-pages <number> : 스크래핑할 최대 페이지 수(기본값: 1000).
• -d, --max-depth <number> : 최대 탐색 깊이(기본값: 3).
• -c, --max-concurrency <number> : 최대 동시 요청 수(기본값: 3).
• --ignore-errors : 스크래핑 중 오류를 무시합니다(기본값: true).

예:

문서 검색( search )

라이브러리에 대한 색인된 문서를 검색하고, 선택적으로 버전별로 필터링합니다.

옵션:

• -v, --version <string> : 검색할 대상 버전 또는 범위입니다.
  • 정확한 버전( 18.0.0 ), 부분 버전( 18 ) 또는 범위( 18.x )를 지원합니다.
  • 생략하면 사용 가능한 최신 인덱스 버전을 검색합니다.
  • 특정 버전/범위가 일치하지 않으면 대상보다 오래된 최신 인덱스 버전으로 대체됩니다.
  • 버전이 지정되지 않은 문서만 검색하려면 --version "" 같이 빈 문자열을 명시적으로 전달하세요. (참고: --version 옵션을 생략하면 최신 버전을 검색하게 되며, 다른 버전이 없는 경우 버전이 지정되지 않은 최신 버전 일 수 있습니다 .)
• -l, --limit <number> : 최대 결과 수(기본값: 5).
• -e, --exact-match : 지정된 버전과 정확하게 일치합니다(폴백 및 범위 일치 비활성화)(기본값: false).

예:

사용 가능한 버전 찾기( find-version )

대상을 기반으로 라이브러리에 가장 잘 맞는 버전을 찾기 위해 인덱스를 확인하고, 버전이 지정되지 않은 문서가 있는지 여부를 나타냅니다.

옵션:

• -v, --version <string> : 대상 버전 또는 범위입니다. 생략하면 사용 가능한 최신 버전을 찾습니다.

예:

라이브러리 목록( list )

현재 저장소에 색인된 모든 라이브러리를 나열합니다.

문서 제거( remove )

특정 라이브러리 및 버전에 대한 색인된 문서를 제거합니다.

옵션:

• -v, --version <string> : 제거할 특정 버전입니다. 생략하면 라이브러리의 버전이 지정되지 않은 문서가 제거됩니다.

예:

버전 처리 요약

• 스크래핑: 특정 유효 버전( XYZ , XYZ-pre , XY , X )이 필요하거나 버전이 없는 문서의 경우 버전이 필요하지 않습니다. 범위( Xx )는 스크래핑에 사용할 수 없습니다.
• 검색/찾기: 특정 버전, 부분 또는 범위( XYZ , XY , X , Xx )를 허용합니다. 대상이 일치하지 않으면 최신 이전 버전으로 돌아갑니다. 버전을 생략하면 사용 가능한 최신 버전을 대상으로 합니다. --version "" 옵션을 명시적으로 사용하면 버전이 지정되지 않은 문서를 대상으로 합니다.
• 버전이 지정되지 않은 문서: 라이브러리는 특정 버전 없이 문서를 저장할 수 있습니다(스크래핑 시 --version 옵션 생략). --version "" 옵션을 사용하여 명시적으로 검색할 수 있습니다. find-version 명령은 버전이 지정되지 않은 문서와 semver 일치 항목이 있는지도 알려줍니다.

개발 및 고급 설정

이 섹션에서는 개발 목적으로 소스 코드에서 직접 서버/CLI를 실행하는 방법을 다룹니다. 현재 주요 사용 방법은 "방법 2"에서 설명한 대로 공개 Docker 이미지를 사용하는 것입니다.

소스에서 실행(개발)

이는 격리된 환경을 제공하고 HTTP 엔드포인트를 통해 서버를 노출합니다.

1. 저장소를 복제합니다.
   git clone https://github.com/arabold/docs-mcp-server.git # Replace with actual URL if different cd docs-mcp-server
2. .env 파일을 만듭니다. 예시를 복사하고 OpenAI 키를 추가합니다(아래 "환경 설정" 참조).
   cp .env.example .env # Edit .env and add your OPENAI_API_KEY
3. Docker 이미지를 빌드합니다.
   docker build -t docs-mcp-server .
4. Docker 컨테이너를 실행합니다.
   # Option 1: Using a named volume (recommended) # Docker automatically creates the volume 'docs-mcp-data' if it doesn't exist on first run. docker run -i --env-file .env -v docs-mcp-data:/data --name docs-mcp-server docs-mcp-server # Option 2: Mapping to a host directory # docker run -i --env-file .env -v /path/on/your/host:/data --name docs-mcp-server docs-mcp-server
   • -i : STDIN을 연결하지 않아도 열어 둡니다. stdio를 통해 서버와 상호 작용할 때 필수적입니다.
   • --env-file .env : 로컬 .env 파일에서 환경 변수(예: OPENAI_API_KEY )를 로드합니다.
   • -v docs-mcp-data:/data 또는 -v /path/on/your/host:/data : 지속성에 필수적입니다. 이 옵션은 Docker에서 명명된 볼륨(Docker는 필요한 경우 docs-mcp-data 자동으로 생성합니다) 또는 호스트 디렉터리를 컨테이너 내부의 /data 디렉터리에 마운트합니다. /data 디렉터리는 서버가 documents.db 파일을 저장하는 위치입니다(Dockerfile의 DOCS_MCP_STORE_PATH 설정에 따라). 이렇게 하면 컨테이너가 중지되거나 제거되더라도 색인된 문서가 유지됩니다.
   • --name docs-mcp-server : 컨테이너에 편리한 이름을 지정합니다.

   컨테이너 내부의 서버는 이제 Node.js를 사용하여 직접 실행되고 stdio를 통해 통신합니다.

이 방법은 프로젝트에 기여하거나 공개되지 않은 버전을 실행하는 데 유용합니다.

1. 저장소를 복제합니다.
   git clone https://github.com/arabold/docs-mcp-server.git # Replace with actual URL if different cd docs-mcp-server
2. 종속성 설치:
   npm install
3. 프로젝트 빌드: TypeScript를 JavaScript로 컴파일하여 dist/ 디렉토리에 저장합니다.
   npm run build
4. 환경 설정: 아래 "환경 설정"에 설명된 대로 .env 파일을 만들고 구성하세요. 이는 OPENAI_API_KEY 제공하는 데 필수적입니다.
5. 달리다:
   • 서버(개발 모드): npm run dev:server (빌드, 감시 및 재시작)
   • 서버(프로덕션 모드): npm run start (미리 빌드된 코드 실행)
   • CLI: npm run cli -- <command> [options] 또는 node dist/cli.js <command> [options]

환경 설정(소스/Docker용)

참고: 이 .env 파일 설정은 주로 서버를 소스에서 실행하거나 Docker 방식을 사용할 때 필요합니다. npx 통합 방식을 사용하는 경우, OPENAI_API_KEY 는 MCP 구성 파일에 직접 설정됩니다.

1. .env.example 기반으로 .env 파일을 만듭니다.
   cp .env.example .env
2. .env 에서 OpenAI API 키를 업데이트하세요.
   # Required: Your OpenAI API key for generating embeddings. OPENAI_API_KEY=your-api-key-here # Optional: Your OpenAI Organization ID (handled automatically by LangChain if set) OPENAI_ORG_ID= # Optional: Custom base URL for OpenAI API (e.g., for Azure OpenAI or compatible APIs) OPENAI_API_BASE= # Optional: Embedding model name (defaults to "text-embedding-3-small") # Examples: text-embedding-3-large, text-embedding-ada-002 DOCS_MCP_EMBEDDING_MODEL= # Optional: Specify a custom directory to store the SQLite database file (documents.db). # If set, this path takes precedence over the default locations. # Default behavior (if unset): # 1. Uses './.store/' in the project root if it exists (legacy). # 2. Falls back to OS-specific data directory (e.g., ~/Library/Application Support/docs-mcp-server on macOS). # DOCS_MCP_STORE_PATH=/path/to/your/desired/storage/directory

디버깅(소스에서)

MCP 서버는 Node.js를 통해 직접 실행할 경우 stdio를 통해 통신하므로 디버깅이 어려울 수 있습니다. 빌드 후 패키지 스크립트로 제공되는 MCP Inspector를 사용하는 것이 좋습니다.

검사기는 브라우저에서 디버깅 도구에 액세스할 수 있는 URL을 제공합니다.

출시

이 프로젝트에서는 semantic-release 와 Conventional Commits을 사용하여 릴리스 프로세스를 자동화합니다.

작동 원리:

1. 커밋 메시지: main 브랜치에 병합된 모든 커밋은 기존 커밋 사양을 따라야 합니다 .
2. 수동 트리거: 새 릴리스를 만들 준비가 되면 작업 탭에서 "릴리스" GitHub Actions 워크플로를 수동으로 트리거할 수 있습니다.
3. semantic-release 작업: 버전을 확인하고, CHANGELOG.md 및 package.json 업데이트하고, 커밋하고, 태그를 지정하고, npm에 게시하고, GitHub 릴리스를 만듭니다.

당신이 해야 할 일:

• 기존 커밋을 사용하세요.
• main 에 대한 변경 사항을 병합합니다.
• 준비가 되면 GitHub의 작업 탭에서 수동으로 릴리스를 트리거합니다.

자동화 핸들: 변경 로그, 버전 범프, 태그, npm 게시, GitHub 릴리스.

건축학

프로젝트의 아키텍처와 디자인 원칙에 대한 자세한 내용은 ARCHITECTURE.md를 참조하세요.

특히, 이 프로젝트 코드의 대부분은 AI 비서 클라인에 의해 생성되었으며, 바로 이 MCP 서버의 기능을 활용했습니다.