Couchbase Guru MCP Server

Un servidor MCP que permite a los LLMs buscar en la documentación de Couchbase desde tu cliente MCP. Expone una única herramienta, ask_couchbase_docs, que envía tu pregunta a un agente de documentación alojado con recuperación aumentada (RAG) y devuelve una respuesta con enlaces a las fuentes.

No se requiere clúster de Couchbase ni credenciales. El servidor se comunica únicamente con el backend del agente de documentación, no con tus datos.

Herramienta

Haz preguntas completas y autónomas: el backend no tiene historial de conversación, por lo que debes incluir el producto, la versión y el lenguaje cuando sea relevante (p. ej., "¿Cómo creo un índice primario con el SDK de Python en Couchbase Server 7.6?").

Related MCP server: docrag

Requisitos previos

• Python 3.10 o superior.

• uv instalado para ejecutar el servidor.

• Un cliente MCP como Claude Desktop, Cursor o VS Code.

Configuración

El servidor se puede ejecutar desde el paquete PyPI precompilado o desde el código fuente con uv. Funciona sin configuración: de forma predeterminada se usa el agente de documentación público.

Ejecución desde PyPI

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

Si ya tienes otros servidores MCP configurados, añade esta entrada al objeto mcpServers existente.

Ejecución desde el código fuente

Clona el repositorio:

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

A continuación, apunta tu cliente MCP a él:

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

path/to/cloned/repo/couchbase-guru/ debe ser la ruta al repositorio clonado en tu máquina. No olvides la barra final.

Opciones

Todas las opciones son opcionales y se pueden establecer mediante un argumento de CLI o una variable de entorno:

Comprueba la versión instalada con:

uvx couchbase-guru --version

Autoalojamiento del agente de documentación

De forma predeterminada, el servidor usa un agente de documentación público compartido, por lo que la mayoría de los usuarios no necesitan configuración. Si ejecutas tu propio backend de agente, apunta el servidor a él:

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

Límites de uso y privacidad

El agente público aplica límites de uso razonable. Para respaldar esto, el servidor envía un identificador de dispositivo seudónimo al backend (en la cabecera User-Agent):

• stdio: un id aleatorio generado una vez y almacenado en un archivo por usuario en tu máquina.

• HTTP: un hash salado unidireccional de la IP de conexión; la dirección original nunca se envía.

El propio servidor MCP no persiste el contenido de las preguntas ni datos personales. Si prefieres no compartir una señal de límite de uso, autoaloja el agente (ver arriba).

Configuración específica del cliente

1. Edita el archivo de configuración (consulta la guía de inicio rápido de MCP):

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

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

2. Añade la configuración a la sección mcpServers.

3. Reinicia Claude Desktop.

Registros: ~/Library/Logs/Claude (macOS) o %APPDATA%\Claude\Logs (Windows).

1. En Cursor, ve a Configuración de Cursor > Herramientas e integraciones > Herramientas MCP.

2. Añade la configuración manualmente o usa el enlace Instalar en Cursor de un clic.

3. Guarda y, a continuación, actualiza para confirmar que el servidor está habilitado.

Registros: en el panel inferior, haz clic en Salida y selecciona Cursor MCP en el menú desplegable.

1. Abre Paleta de comandos > Panel de configuración de MCP de Windsurf (o Configuración > Avanzado > Cascade > Servidores del Model Context Protocol (MCP)).

2. Haz clic en Añadir servidor > Añadir servidor personalizado y añade la configuración.

3. Guarda y, a continuación, actualiza para confirmar que el servidor está habilitado.

Consulta la documentación de MCP de Windsurf para obtener más detalles.

1. Crea .vscode/mcp.json en tu espacio de trabajo (o ejecuta MCP: Open User Configuration para una configuración global).

2. VS Code usa servers como clave de nivel superior (no mcpServers):

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

3. Una vez guardado, usa la lista de acciones en línea para Start/Stop/gestionar el servidor.

Consulta la documentación de MCP de VS Code para obtener más detalles.

1. Instala el complemento AI Assistant o Junie.

2. Navega a Configuración > Herramientas > AI Assistant o Junie > Servidor MCP.

3. Haz clic en "+", añade la configuración y haz clic en Guardar, luego en Aplicar.

Registros: Ayuda > Mostrar registros en Finder (Explorer) > mcp > couchbase-guru.

Modo de transporte Streamable HTTP

El servidor puede ejecutarse en modo Streamable HTTP para que varios clientes puedan conectarse a una sola instancia. Comprueba antes que tu cliente MCP soporta este transporte.

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

El servidor estará disponible en http://localhost:8000/mcp:

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

Este modo no incluye soporte de autorización.

Docker

Construye la imagen:

docker build -t couchbase-guru .

Ejecútalo (stdio por defecto; no se necesitan credenciales):

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

Para el transporte HTTP, publica el puerto y establece el transporte:

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

Riesgos asociados con los LLM

• El uso de modelos de lenguaje grandes y tecnologías similares conlleva riesgos, incluida la posibilidad de resultados inexactos o perjudiciales.

• Couchbase no revisa ni evalúa la calidad o exactitud de dichos resultados, y estos pueden no reflejar las opiniones de Couchbase.

• Eres el único responsable de decidir si usar modelos de lenguaje grandes y tecnología relacionada, y de cumplir con los términos de licencia aplicables, las condiciones de uso y las políticas de tu organización.

Solución de problemas

• Confirma que uv/uvx esté instalado y en tu PATH. Puede que necesites proporcionar una ruta absoluta a uv/uvx en el campo command.

• Si una búsqueda agota el tiempo de espera, el backend de documentación puede estar ocupado; vuelve a intentarlo en un momento.

• Para descartar el backend público, ejecuta contra tu propio agente con --agent-base-url.

• Si ejecutas desde el código fuente después de actualizar el repositorio, ejecuta uv sync para actualizar las dependencias.

• Revisa los registros de tu cliente MCP (ubicaciones arriba) para ver si hay errores.

Pruebas

Las pruebas unitarias se ejecutan sin conexión (el backend está simulado):

uv sync --extra dev
uv run pytest tests/

Las pruebas de integración ejercitan la herramienta de extremo a extremo contra un backend de agente real y son optativas:

CB_MCP_RUN_INTEGRATION=1 uv run pytest tests/test_docs_tools.py

De forma predeterminada usan el agente público; establece CB_AGENT_BASE_URL para apuntar a un backend diferente.

👩💻 Contribuciones

¡Las contribuciones son bienvenidas! Para informar de un error, solicitar una funcionalidad o aportar mejoras, abre un issue en GitHub.

Consulta CONTRIBUTING.md para la configuración de desarrollo (entorno con uv, linting/formatting con Ruff, ganchos pre-commit y estructura del proyecto).

# 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

📢 Política de soporte

¡Agradecemos tu interés en este proyecto! Está mantenido por la comunidad de Couchbase, lo que significa que no cuenta con soporte oficial de nuestro equipo de soporte. Nuestros ingenieros supervisan y mantienen este repositorio e intentarán resolver los problemas en la medida de lo posible. Por favor, mantén todas las consultas dentro de GitHub.