MCP Server 배포 가이드

docs-mcp-server 분산 배포 (Worker + MCP + Web) + 임베딩 모델

📋 구성 요소

서비스	역할	포트
bge-m3-ko	임베딩 모델 (Text Embeddings Inference)	내부 80
docs-mcp-worker	문서 처리 (스크래핑, 인덱싱)	내부 8080
docs-mcp-server	MCP 프로토콜 엔드포인트 (AI 도구 연결)	6280
docs-mcp-web	웹 관리 인터페이스	6281

🏗️ 아키텍처

┌─────────────────────────────────────────────────────────────────┐
│                        Docker Network                           │
│                                                                 │
│   ┌─────────────────┐    ┌─────────────────┐                   │
│   │  mcp-server     │    │    mcp-web      │                   │
│   │  :6280 (공개)   │    │  :6281 (공개)   │                   │
│   └────────┬────────┘    └────────┬────────┘                   │
│            │                      │                             │
│            └──────────┬───────────┘                             │
│                       ▼                                         │
│            ┌─────────────────────┐                              │
│            │   docs-mcp-worker   │  ← 내부 전용                 │
│            │   :8080 (내부)      │                              │
│            └──────────┬──────────┘                              │
│                       │                                         │
│                       ▼                                         │
│            ┌─────────────────────┐                              │
│            │     bge-m3-ko       │  ← 내부 전용                 │
│            │   :80 (내부)        │                              │
│            └─────────────────────┘                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

🚀 빠른 시작

0단계: 임베딩 모델 준비 (외부 환경)

⚠️ 중요: 임베딩 모델 파일은 용량이 커서 프로젝트에 포함되지 않습니다. 배포 전에 외부 환경에서 준비해야 합니다.

Hugging Face에서 모델 다운로드:

# 모델 디렉토리 생성
mkdir -p models/bge-m3-ko

# Hugging Face에서 모델 다운로드
# 방법 1: git-lfs 사용
git lfs install
git clone https://huggingface.co/BAAI/bge-m3-ko models/bge-m3-ko

# 방법 2: huggingface-hub 사용
pip install huggingface-hub
huggingface-cli download BAAI/bge-m3-ko --local-dir models/bge-m3-ko

다운로드한 모델 파일을 프로젝트의 models/bge-m3-ko/ 폴더에 배치합니다.

1단계: 이미지 빌드 (외부 환경)

인터넷이 연결된 환경에서 실행:

cd mcp-server

# Linux/macOS
chmod +x build-images.sh
./build-images.sh

# Windows PowerShell
powershell -ExecutionPolicy Bypass -File build-images.ps1

생성되는 파일:

• out/docs-mcp-server.tar - MCP 서버 이미지
• out/bge-m3-ko-cpu.tar - 임베딩 모델 이미지 (CPU 버전)
• out/bge-m3-ko-gpu.tar - 임베딩 모델 이미지 (GPU 버전)

2단계: 파일 전송

폐쇄망으로 전송할 파일:

• mcp-server/ 폴더 전체 (임베딩 모델 포함)

3단계: 배포

cd mcp-server

# Linux/macOS
chmod +x deploy-mcp.sh

# CPU 버전 (GPU가 없는 서버)
./deploy-mcp.sh cpu

# GPU 버전 (NVIDIA GPU가 있는 서버)
./deploy-mcp.sh gpu

# Windows PowerShell

# CPU 버전
powershell -ExecutionPolicy Bypass -File deploy-mcp.ps1 cpu

# GPU 버전
powershell -ExecutionPolicy Bypass -File deploy-mcp.ps1 gpu

4단계: 서비스 준비 대기

서비스 시작 후 임베딩 모델이 완전히 준비될 때까지 2~3분 기다려야 합니다.

# 임베딩 모델 로그 확인 (Ready 메시지 확인)
docker compose logs -f bge-m3-ko-cpu  # 또는 bge-m3-ko-gpu

# Ready 메시지가 나오면 정상 작동 중입니다
# 예: {"level":"INFO","message":"Ready","target":"text_embeddings_router::http::server"}

참고: Worker는 임베딩 모델이 준비될 때까지 자동으로 재시도하므로, Ready 메시지가 나오면 자동으로 연결됩니다.

📁 디렉토리 구조

mcp-server/
├── docker-compose.yml       # Docker Compose 설정 파일
├── docs-mcp-server-1.36.0/  # docs-mcp-server 소스 (빌드용)
├── build-images.sh          # 이미지 빌드 스크립트 (외부망)
├── build-images.ps1         # 이미지 빌드 스크립트 (Windows)
├── deploy-mcp.sh            # 배포 스크립트 (폐쇄망)
├── deploy-mcp.ps1           # 배포 스크립트 (Windows)
├── README.md                # 이 문서
├── docs/                    # 문서 파일 (임베딩 대상)
├── models/                  # 임베딩 모델 파일
│   └── bge-m3-ko/           # bge-m3-ko 모델
└── out/                     # 빌드된 이미지 파일
    ├── docs-mcp-server.tar
    ├── bge-m3-ko-cpu.tar
    └── bge-m3-ko-gpu.tar

🖥️ CPU vs GPU 비교

	CPU 버전	GPU 버전
명령어	--profile cpu	--profile gpu
하드웨어	일반 서버	NVIDIA GPU 필요
메모리	~8GB RAM	~4GB VRAM
속도	느림	5-10배 빠름
이미지	bge-m3-ko:cpu	bge-m3-ko:gpu

🔧 설정

클라이언트 연결

Cursor 또는 Claude Desktop에서 MCP 서버 연결:

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

웹 UI 접속

브라우저에서 http://서버IP:6281 접속

문서 적재 및 임베딩

1. 문서 준비: 문서 파일을 docs/ 폴더에 넣습니다.

2. 웹 UI에서 임베딩:

   • 브라우저에서 http://서버IP:6281 접속
   • 다음 정보를 입력하여 임베딩:
     • URL: file:///docs
     • Library Name: test-docs (또는 원하는 이름)
     • Version: 1 (또는 비워둠)

3. 임베딩 완료 후: MCP 서버를 통해 문서 검색 및 질의가 가능합니다.

📊 운영 명령어

# 서비스 상태 확인
docker compose ps

# 로그 확인
docker compose logs -f

# 특정 서비스 로그 확인
docker compose logs -f docs-mcp-worker

# 서비스 재시작
docker compose --profile cpu restart   # 또는 --profile gpu

# 서비스 중지
docker compose --profile cpu down      # 또는 --profile gpu

# 서비스 시작
docker compose --profile cpu up -d     # 또는 --profile gpu

⚠️ 주의사항

절대 하면 안 되는 것

# ❌ 볼륨까지 삭제되어 인덱싱된 데이터가 모두 사라집니다!
docker compose down -v

안전한 명령어

# ✅ 컨테이너만 중지, 볼륨 유지
docker compose --profile cpu down

# ✅ 재시작
docker compose --profile cpu up -d

🔍 문제 해결

임베딩 모델이 시작되지 않을 때

# 로그 확인
docker compose logs bge-m3-ko

# 모델 파일 확인
ls -la models/bge-m3-ko/

# CPU 버전의 경우 WSL 메모리 충분한지 확인
# ~/.wslconfig 파일 수정 후 WSL 재시작:
# [wsl2]
# memory=10GB

Worker가 임베딩 모델에 연결되지 않을 때

# Worker 로그 확인
docker compose logs docs-mcp-worker

# 네트워크 연결 테스트
docker exec docs-mcp-worker curl -s http://bge-m3-ko:80/health

MCP 서버에 연결되지 않을 때

# MCP 서버 상태 확인
docker compose logs docs-mcp-server

📝 버전 정보

• docs-mcp-server: 1.36.0
• text-embeddings-inference: cpu-1.8 / 1.8 (GPU)
• 임베딩 모델: bge-m3-ko