MaxKB 지식 베이스 검색 MCP

MaxKB Admin API 기반 MCP 서비스로, 사용자 질문에 따라 지식 베이스 세그먼트를 검색합니다. 벡터 검색, 하이브리드 검색, 전체 검색을 지원합니다. 기본 Top K는 10, 검색 모드는 벡터 검색입니다.

기본적으로 Streamable HTTP로 서비스를 제공합니다:

• MCP 주소: http://<호스트>:8000/mcp

• 헬스 체크: http://<호스트>:8000/health

기능

search_mode(도구에서 지정하지 않으면 환경 변수 사용, 기본값은 벡터 검색):

• 벡터 / 벡터 검색 / embedding

• 혼합 / 혼합 검색 / blend

• 전체 / 전체 검색 / keywords

• auto: 혼합 검색 → 벡터 검색 → 전체 텍스트 검색, 히트할 때까지

knowledge_ids를 지정하지 않으면 현재 워크스페이스의 모든 벡터 모델이 구성된 지식 베이스에서 검색합니다.

Related MCP server: mcp-rag-bridge

환경 변수

샘플 파일을 복사한 후 실제 환경에 맞게 수정하세요:

cp .env.example .env

search_knowledge 호출 시 top_n 또는 search_mode를 전달하면 서버 기본값을 덮어씁니다.

로컬 시작

Python 3.10+ 및 uv 필요.

cp .env.example .env
uv sync
uv run maxkb-mcp

시작 후:

• MCP: http://127.0.0.1:8000/mcp

• 헬스 체크: http://127.0.0.1:8000/health

• 로그 파일: logs/mcp.log(일 단위 롤링, 기본 7일 보관)

클라이언트 연동 예시:

{
  "mcpServers": {
    "maxkb-knowledge": {
      "transport": "streamable_http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "你的 MaxKB API Key"
      },
      "disabled": false
    }
  }
}

Authorization는 원본 Key 또는 Bearer <key> 형식일 수 있습니다.

stdio 모드가 필요하면:

MCP_TRANSPORT=stdio uv run maxkb-mcp

Docker 이미지 패키징

Docker 20.10+ 필요.

docker build -t maxkb-mcp:latest .

국내 네트워크에서는 PyPI 미러를 지정하는 것을 권장:

docker build \
  --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
  -t maxkb-mcp:latest .

이미지 레지스트리에 푸시(선택 사항):

docker tag maxkb-mcp:latest <registry>/<namespace>/maxkb-mcp:0.1.0
docker push <registry>/<namespace>/maxkb-mcp:0.1.0

Docker 배포

docker-compose.yml은 이미지를 빌드하지 않고 기존 이미지로만 시작합니다. 배포 전에 로컬 빌드를 완료하거나 레지스트리에서 이미지를 가져오세요.

cp .env.example .env
docker-compose up -d
docker-compose logs -f maxkb-mcp

원격 이미지 사용 시:

MAXKB_MCP_IMAGE=<registry>/<namespace>/maxkb-mcp:0.1.0 docker-compose up -d

시작 후:

• MCP: http://<호스트>:8000/mcp

• 헬스 체크: http://<호스트>:8000/health

• 로그 디렉터리: 호스트 ./logs(컨테이너 내부 /app/logs)

HTTPS 리버스 프록시를 거친 경우 클라이언트 url을 https://your-domain/mcp로 변경하세요.

MaxKB가 호스트에 배포된 경우 MAXKB_BASE_URL을 http://host.docker.internal:<포트>로 설정하세요.

서비스 중지:

docker-compose down

로그

모든 HTTP 요청과 MCP 도구 호출은 로컬 로그에 기록되며 Authorization은 마스킹됩니다.

• 파일: {MAXKB_LOG_DIR}/mcp.log, 매일 mcp.log.YYYY-MM-DD로 롤링

• 시작 시 만료 파일 1회 정리, 이후 6시간마다 정리

• MAXKB_LOG_RETENTION_DAYS(기본 7일)를 초과한 로그는 삭제

자주 묻는 질문

• API Key 미제공: 클라이언트 headers.Authorization에 MaxKB 사용자 Key를 전달하거나 .env에서 MAXKB_API_KEY를 설정하세요.

• 빌드 느림 또는 타임아웃: 패키징 시 --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple 추가

• 컨테이너에서 MaxKB에 접근 불가: MAXKB_BASE_URL, 네트워크, host.docker.internal 필요 여부 확인

• 인증서 검증 실패: MAXKB_VERIFY_SSL=false 설정