Couchbase Guru MCP Server

MCP 클라이언트에서 LLM이 Couchbase 문서를 검색할 수 있게 해주는 MCP 서버입니다. 단일 도구인 ask_couchbase_docs를 제공하며, 이 도구는 질문을 호스팅된 검색 증강 생성(RAG) 문서 에이전트에 전달하고 소스 링크와 함께 답변을 반환합니다.

Couchbase 클러스터나 자격 증명이 필요하지 않습니다. 서버는 문서 에이전트 백엔드하고만 통신하며, 사용자의 데이터에는 접근하지 않습니다.

도구

완전하고 독립적인 질문을 하세요. 백엔드에는 대화 기록이 없으므로 관련된 경우 제품, 버전, 언어를 포함하세요(예: "Couchbase Server 7.6에서 Python SDK로 기본 인덱스를 만들려면 어떻게 해야 하나요?").

Related MCP server: docrag

사전 요구 사항

• Python 3.10 이상.

• 서버를 실행하려면 uv가 설치되어 있어야 합니다.

• Claude Desktop, Cursor, VS Code 등의 MCP 클라이언트가 필요합니다.

구성

서버는 사전 빌드된 PyPI 패키지에서 또는 uv를 사용하여 소스에서 실행할 수 있습니다. 구성 없이도 작동하며, 기본적으로 공개 문서 에이전트가 사용됩니다.

PyPI에서 실행하기

{
  "mcpServers": {
    "couchbase-guru": {
      "command": "uvx",
      "args": ["couchbase-guru"]
    }
  }
}

이미 다른 MCP 서버를 구성한 경우 이 항목을 기존 mcpServers 객체에 추가하세요.

소스에서 실행하기

리포지토리를 클론합니다:

git clone https://github.com/Couchbase-Ecosystem/couchbase-guru.git

그런 다음 MCP 클라이언트가 이를 가리키도록 설정합니다:

{
  "mcpServers": {
    "couchbase-guru": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/cloned/repo/couchbase-guru/",
        "run",
        "src/mcp_server.py"
      ]
    }
  }
}

path/to/cloned/repo/couchbase-guru/는 사용자 머신에서 클론한 리포지토리의 경로여야 합니다. 끝에 오는 슬래시를 잊지 마세요.

옵션

모든 옵션은 선택 사항이며 CLI 인수 또는 환경 변수로 설정할 수 있습니다:

설치된 버전을 확인합니다:

uvx couchbase-guru --version

문서 에이전트 자체 호스팅

기본적으로 서버는 공유된 공개 문서 에이전트를 사용하므로 대부분의 사용자는 설정이 필요 없습니다. 자체 에이전트 백엔드를 실행하는 경우 서버가 이를 가리키도록 설정하세요:

uvx couchbase-guru --agent-base-url https://your-agent.example.com

속도 제한 및 개인정보 보호

공개 에이전트는 공정 사용 속도 제한을 적용합니다. 이를 지원하기 위해 서버는 가명 장치 식별자를 백엔드로 전송합니다(User-Agent 헤더에 포함).

• stdio: 한 번 생성되어 사용자 머신의 사용자별 파일에 저장되는 무작위 ID입니다.

• HTTP: 연결 IP의 솔트 처리된 단방향 해시입니다. 원본 주소는 절대 전송되지 않습니다.

MCP 서버 자체는 질문 내용이나 개인 데이터를 저장하지 않습니다. 속도 제한 신호를 공유하고 싶지 않다면 에이전트를 자체 호스팅하세요(위 참조).

클라이언트별 구성

1. 구성 파일을 편집합니다(MCP 빠른 시작 가이드 참조):

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 구성을 mcpServers 섹션에 추가합니다.

3. Claude Desktop을 다시 시작합니다.

로그: ~/Library/Logs/Claude(macOS) 또는 %APPDATA%\Claude\Logs(Windows).

1. Cursor에서 Cursor Settings > Tools & Integrations > MCP Tools로 이동합니다.

2. 구성을 수동으로 추가하거나 한 번의 클릭으로 설치하는 Install in Cursor 링크를 사용합니다.

3. 저장한 후 새로고침하여 서버가 활성화되었는지 확인합니다.

로그: 하단 패널에서 Output을 클릭하고 드롭다운에서 Cursor MCP를 선택합니다.

1. Command Palette > Windsurf MCP Configuration Panel을 엽니다(또는 Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers).

2. Add Server > Add custom server를 클릭하고 구성을 추가합니다.

3. 저장한 후 새로고침하여 서버가 활성화되었는지 확인합니다.

자세한 내용은 Windsurf MCP 문서를 참조하세요.

1. 작업 영역에 .vscode/mcp.json을 생성합니다(또는 전역 구성을 위해 MCP: Open User Configuration을 실행합니다).

2. VS Code는 mcpServers가 아닌 servers를 최상위 키로 사용합니다:

   {
     "servers": {
       "couchbase-guru": {
         "command": "uvx",
         "args": ["couchbase-guru"]
       }
     }
   }

3. 저장한 후 인라인 작업 목록을 사용하여 서버를 Start/Stop/관리할 수 있습니다.

자세한 내용은 VS Code MCP 문서를 참조하세요.

1. AI Assistant 또는 Junie 플러그인을 설치합니다.

2. Settings > Tools > AI Assistant or Junie > MCP Server로 이동합니다.

3. "+"를 클릭하고 구성을 추가한 다음 Save를 클릭하고 Apply를 클릭합니다.

로그: Help > Show Log in Finder (Explorer) > mcp > couchbase-guru.

Streamable HTTP 전송 모드

서버는 Streamable HTTP 모드로 실행할 수 있으므로 여러 클라이언트가 하나의 인스턴스에 연결할 수 있습니다. 먼저 MCP 클라이언트가 이 전송을 지원하는지 확인하세요.

uvx couchbase-guru --transport=http --port=8000

서버는 http://localhost:8000/mcp에서 사용할 수 있습니다:

{
  "mcpServers": {
    "couchbase-guru-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

이 모드에는 인증 지원이 포함되지 않습니다.

Docker

이미지를 빌드합니다:

docker build -t couchbase-guru .

실행합니다(기본값은 stdio이며 자격 증명이 필요하지 않습니다):

{
  "mcpServers": {
    "couchbase-guru-docker": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "couchbase-guru"]
    }
  }
}

HTTP 전송의 경우 포트를 게시하고 전송을 설정합니다:

docker run --rm -i \
  -e CB_MCP_TRANSPORT=http \
  -e CB_MCP_HOST=0.0.0.0 \
  -e CB_MCP_PORT=8000 \
  -p 8000:8000 \
  couchbase-guru

LLM 관련 위험

• 대규모 언어 모델 및 유사 기술의 사용에는 부정확하거나 유해한 출력이 발생할 가능성을 포함한 위험이 수반됩니다.

• Couchbase는 이러한 출력의 품질이나 정확성을 검토하거나 평가하지 않으며, 이러한 출력이 Couchbase의 견해를 반영하지 않을 수 있습니다.

• 대규모 언어 모델 및 관련 기술의 사용 여부를 결정하고, 적용 가능한 라이선스 조건, 이용 약관, 조직의 정책을 준수할 책임은 전적으로 사용자에게 있습니다.

문제 해결

• uv/uvx가 설치되어 있고 PATH에 있는지 확인하세요. command 필드에 uv/uvx의 절대 경로를 제공해야 할 수 있습니다.

• 검색 시간이 초과되면 문서 백엔드가 사용 중일 수 있습니다. 잠시 후 다시 시도하세요.

• 공개 백엔드 문제를 배제하려면 --agent-base-url을 사용하여 자체 에이전트를 대상으로 실행하세요.

• 리포지토리를 업데이트한 후 소스에서 실행하는 경우 uv sync를 실행하여 종속성을 새로 고치세요.

• 오류가 있는지 MCP 클라이언트의 로그(앞서 언급한 위치)를 확인하세요.

테스트

단위 테스트는 오프라인으로 실행됩니다(백엔드가 모킹됨):

uv sync --extra dev
uv run pytest tests/

통합 테스트는 실제 에이전트 백엔드를 대상으로 도구를 종단 간 테스트하며, 옵트인 방식입니다:

CB_MCP_RUN_INTEGRATION=1 uv run pytest tests/test_docs_tools.py

기본적으로 공개 에이전트를 사용하며, 다른 백엔드를 대상으로 하려면 CB_AGENT_BASE_URL을 설정하세요.

👩💻 기여

기여는 언제나 환영합니다! 버그를 신고하거나, 기능을 요청하거나, 개선 사항을 기여하려면 GitHub 이슈를 열어주세요.

개발자 설정(uv 환경, Ruff를 사용한 린팅/포맷팅, pre-commit 훅, 프로젝트 구조)은 CONTRIBUTING.md를 참조하세요.

# Clone and set up
git clone https://github.com/Couchbase-Ecosystem/couchbase-guru.git
cd couchbase-guru

# Install with development dependencies
uv sync --extra dev

# Install pre-commit hooks
uv run pre-commit install

📢 지원 정책

이 프로젝트에 관심을 가져주셔서 감사합니다! 이 프로젝트는 Couchbase 커뮤니티 유지 관리 프로젝트로, 지원 팀의 공식 지원을 받지 않습니다. 당사 엔지니어가 이 리포지토리를 모니터링하고 유지 관리하며 최선을 다해 문제를 해결하려고 노력합니다. 모든 문의는 GitHub 내에서 부탁드립니다.