couchbase-mcp-server 0.4.0rc1__py3-none-any.whl → 0.5.0__py3-none-any.whl

{couchbase_mcp_server-0.4.0rc1.dist-info → couchbase_mcp_server-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: couchbase-mcp-server
-Version: 0.4.0rc1
+Version: 0.5.0
 Summary: Couchbase MCP Server - The Developer Data Platform for Critical Applications in Our AI World
 Author-email: Nithish Raghunandanan <devadvocates@couchbase.com>
 License-Expression: Apache-2.0
@@ -26,7 +26,7 @@ Dynamic: license-file
 
 An [MCP](https://modelcontextprotocol.io/) server implementation of Couchbase that allows LLMs to directly interact with Couchbase clusters.
 
-[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) [![PyPI version](https://badge.fury.io/py/couchbase-mcp-server.svg)](https://pypi.org/project/couchbase-mcp-server/) [![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/13fce476-0e74-4b1e-ab82-1df2a3204809)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) [![PyPI version](https://badge.fury.io/py/couchbase-mcp-server.svg)](https://pypi.org/project/couchbase-mcp-server/) [![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/13fce476-0e74-4b1e-ab82-1df2a3204809) [![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/Couchbase-Ecosystem/mcp-server-couchbase)](https://archestra.ai/mcp-catalog/couchbase-ecosystem__mcp-server-couchbase)
 
 <a href="https://glama.ai/mcp/servers/@Couchbase-Ecosystem/mcp-server-couchbase">
   <img width="380" height="200" src="https://glama.ai/mcp/servers/@Couchbase-Ecosystem/mcp-server-couchbase/badge" alt="Couchbase Server MCP server" />
@@ -34,7 +34,10 @@ An [MCP](https://modelcontextprotocol.io/) server implementation of Couchbase th
 
 ## Features
 
+- Get a list of all the buckets in the cluster
 - Get a list of all the scopes and collections in the specified bucket
+- Get a list of all the scopes in the specified bucket
+- Get a list of all the collections in a specified scope and bucket. Note that this tool requires the cluster to have Query service.
 - Get the structure for a collection
 - Get a document by ID from a specified scope and collection
 - Upsert a document by ID to a specified scope and collection
@@ -53,7 +56,7 @@ An [MCP](https://modelcontextprotocol.io/) server implementation of Couchbase th
 
 ## Configuration
 
-The MCP server can be run either from the pre built PyPI package or the source using uv.
+The MCP server can be run either from the prebuilt PyPI package or the source using uv.
 
 ### Running from PyPI
 
@@ -61,6 +64,8 @@ We publish a pre built [PyPI package](https://pypi.org/project/couchbase-mcp-ser
 
 #### Server Configuration using Pre built Package for MCP Clients
 
+#### Basic Authentication
+
 ```json
 {
   "mcpServers": {
@@ -70,8 +75,27 @@ We publish a pre built [PyPI package](https://pypi.org/project/couchbase-mcp-ser
       "env": {
         "CB_CONNECTION_STRING": "couchbases://connection-string",
         "CB_USERNAME": "username",
-        "CB_PASSWORD": "password",
-        "CB_BUCKET_NAME": "bucket_name"
+        "CB_PASSWORD": "password"
+      }
+    }
+  }
+}
+```
+
+or
+
+#### mTLS
+
+```json
+{
+  "mcpServers": {
+    "couchbase": {
+      "command": "uvx",
+      "args": ["couchbase-mcp-server"],
+      "env": {
+        "CB_CONNECTION_STRING": "couchbases://connection-string",
+        "CB_CLIENT_CERT_PATH": "/path/to/client-certificate.pem",
+        "CB_CLIENT_KEY_PATH": "/path/to/client.key"
       }
     }
   }
@@ -108,8 +132,7 @@ This is the common configuration for the MCP clients such as Claude Desktop, Cur
       "env": {
         "CB_CONNECTION_STRING": "couchbases://connection-string",
         "CB_USERNAME": "username",
-        "CB_PASSWORD": "password",
-        "CB_BUCKET_NAME": "bucket_name"
+        "CB_PASSWORD": "password"
       }
     }
   }
@@ -123,17 +146,21 @@ This is the common configuration for the MCP clients such as Claude Desktop, Cur
 ### Additional Configuration for MCP Server
 
 The server can be configured using environment variables or command line arguments:
-
-| Environment Variable          | CLI Argument             | Description                                | Default      |
-| ----------------------------- | ------------------------ | ------------------------------------------ | ------------ |
-| `CB_CONNECTION_STRING`        | `--connection-string`    | Connection string to the Couchbase cluster | **Required** |
-| `CB_USERNAME`                 | `--username`             | Username with bucket access                | **Required** |
-| `CB_PASSWORD`                 | `--password`             | Password for authentication                | **Required** |
-| `CB_BUCKET_NAME`              | `--bucket-name`          | Name of the bucket to access               | **Required** |
-| `CB_MCP_READ_ONLY_QUERY_MODE` | `--read-only-query-mode` | Prevent data modification queries          | `true`       |
-| `CB_MCP_TRANSPORT`            | `--transport`            | Transport mode: `stdio`, `http`, `sse`     | `stdio`      |
-| `CB_MCP_HOST`                 | `--host`                 | Host for HTTP/SSE transport modes          | `127.0.0.1`  |
-| `CB_MCP_PORT`                 | `--port`                 | Port for HTTP/SSE transport modes          | `8000`       |
+| Environment Variable | CLI Argument | Description | Default |
+|--------------------------------|--------------------------|---------------------------------------------------------------------------------------------|------------------------------------------|
+| `CB_CONNECTION_STRING` | `--connection-string` | Connection string to the Couchbase cluster | **Required** |
+| `CB_USERNAME` | `--username` | Username with access to required buckets for basic authentication | **Required (or Client Certificate and Key needed for mTLS)** |
+| `CB_PASSWORD` | `--password` | Password for basic authentication | **Required (or Client Certificate and Key needed for mTLS)** |
+| `CB_CLIENT_CERT_PATH` | `--client-cert-path` | Path to the client certificate file for mTLS authentication| **Required if using mTLS (or Username and Password required)** |
+| `CB_CLIENT_KEY_PATH` | `--client-key-path` | Path to the client key file for mTLS authentication| **Required if using mTLS (or Username and Password required)** |
+| `CB_CA_CERT_PATH` | `--ca-cert-path` | Path to server root certificate for TLS if server is configured with a self-signed/untrusted certificate. This will not be required if you are connecting to Capella | |
+| `CB_MCP_READ_ONLY_QUERY_MODE` | `--read-only-query-mode` | Prevent data modification queries | `true` |
+| `CB_MCP_TRANSPORT` | `--transport` | Transport mode: `stdio`, `http`, `sse` | `stdio` |
+| `CB_MCP_HOST` | `--host` | Host for HTTP/SSE transport modes | `127.0.0.1` |
+| `CB_MCP_PORT` | `--port` | Port for HTTP/SSE transport modes | `8000` |
+
+> Note: For authentication, you need either the Username and Password or the Client Certificate and key paths. Optionally, you can specify the CA root certificate path that will be used to validate the server certificates.
+> If both the Client Certificate & key path and the username and password are specified, the client certificates will be used for authentication.
 
 You can also check the version of the server using:
 
@@ -228,7 +255,12 @@ Check if your [MCP client](https://modelcontextprotocol.io/clients) supports str
 By default, the MCP server will run on port 8000 but this can be configured using the `--port` or `CB_MCP_PORT` environment variable.
 
 ```bash
-uvx couchbase-mcp-server --connection-string='<couchbase_connection_string>' --username='<database_username>' --password='<database_password>' --bucket-name='<couchbase_bucket_to_use>' --read-only-query-mode=true --transport=streamable-http
+uvx couchbase-mcp-server \
+  --connection-string='<couchbase_connection_string>' \
+  --username='<database_username>' \
+  --password='<database_password>' \
+  --read-only-query-mode=true \
+  --transport=http
 ```
 
 The server will be available on http://localhost:8000/mcp. This can be used in MCP clients supporting streamable http transport mode such as Cursor.
@@ -256,7 +288,12 @@ There is an option to run the MCP server in [Server-Sent Events (SSE)](https://m
 By default, the MCP server will run on port 8000 but this can be configured using the `--port` or `CB_MCP_PORT` environment variable.
 
 ```bash
- uvx couchbase-mcp-server --connection-string='<couchbase_connection_string>' --username='<database_username>' --password='<database_password>' --bucket-name='<couchbase_bucket_to_use>' --read-only-query-mode=true --transport=sse
+uvx couchbase-mcp-server \
+  --connection-string='<couchbase_connection_string>' \
+  --username='<database_username>' \
+  --password='<database_password>' \
+  --read-only-query-mode=true \
+  --transport=sse
 ```
 
 The server will be available on http://localhost:8000/sse. This can be used in MCP clients supporting SSE transport mode such as Cursor.
@@ -331,7 +368,6 @@ docker run --rm -i \
   -e CB_CONNECTION_STRING='<couchbase_connection_string>' \
   -e CB_USERNAME='<database_user>' \
   -e CB_PASSWORD='<database_password>' \
-  -e CB_BUCKET_NAME='<bucket_name>' \
   -e CB_MCP_TRANSPORT='<http|sse|stdio>' \
   -e CB_MCP_READ_ONLY_QUERY_MODE='<true|false>' \
   -e CB_MCP_PORT=9001 \
@@ -360,8 +396,6 @@ The Docker image can be used in `stdio` transport mode with the following config
         "CB_USERNAME=<database_user>",
         "-e",
         "CB_PASSWORD=<database_password>",
-        "-e",
-        "CB_BUCKET_NAME=<bucket_name>",
         "mcp/couchbase"
       ]
     }
@@ -387,11 +421,11 @@ The Couchbase MCP server can also be used as a managed server in your agentic ap
 ## Troubleshooting Tips
 
 - Ensure the path to your MCP server repository is correct in the configuration if running from source.
-- Verify that your Couchbase connection string, database username, password and bucket name are correct.
+- Verify that your Couchbase connection string, database username, password or the path to the certificates are correct.
 - If using Couchbase Capella, ensure that the cluster is [accessible](https://docs.couchbase.com/cloud/clusters/allow-ip-address.html) from the machine where the MCP server is running.
-- Check that the database user has proper permissions to access the specified bucket.
-- Confirm that the uv package manager is properly installed and accessible. You may need to provide absolute path to uv/uvx in the `command` field in the configuration.
-- Check the logs for any errors or warnings that may indicate issues with the MCP server. The server logs are under the name, `mcp-server-couchbase.log`.
+- Check that the database user has proper permissions to access at least one bucket.
+- Confirm that the `uv` package manager is properly installed and accessible. You may need to provide absolute path to `uv`/`uvx` in the `command` field in the configuration.
+- Check the logs for any errors or warnings that may indicate issues with the MCP server. The location of the logs depend on your MCP client.
 - If you are observing issues running your MCP server from source after updating your local MCP server repository, try running `uv sync` to update the [dependencies](https://docs.astral.sh/uv/concepts/projects/sync/#syncing-the-environment).
 
 ---

couchbase_mcp_server-0.5.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+mcp_server.py,sha256=QGKbHL5fnQQnFkZZvK89eEWR6HcmF_0JqV_E6lke3M8,5031
+couchbase_mcp_server-0.5.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+tools/__init__.py,sha256=1FRntOrRYPiITHteCiEu0DrIBEesNgpeeLkvzFpRNv4,1355
+tools/kv.py,sha256=NGUs43iuXElj9rYe4RCyCStqoh5y1fUgbg1oWuU4WeQ,2493
+tools/query.py,sha256=fSSG7XuxnND1lHwI-r8y_M3h6f82vCXxCwB_A2wHN-M,3598
+tools/server.py,sha256=iv_UH4OiBnlPYSSEt1rs3LFeYmIZb_c5mEEYBToS8gU,5188
+utils/__init__.py,sha256=eVRW08PAfJXrB3cYbmHIj3v6kfa1-a9dlNXsEOB0igU,1223
+utils/config.py,sha256=B6H_JYDn6uxtu9juM924zdvNQgSaHh_u6rYME3_0_xQ,268
+utils/connection.py,sha256=NtAU4pmHMZubSJcs_X_lai9o8dih5mW0RyrRdmyp1Po,2892
+utils/constants.py,sha256=w0zvQ1zMzJBg44Yl3aQW8KfaaRPn0BgPOLEe8xLeLSE,487
+utils/context.py,sha256=XZL4M70BMdFBptJ9sT0zxhEey-EvvoSKZJrP_sb7q-A,2286
+couchbase_mcp_server-0.5.0.dist-info/METADATA,sha256=G_R6LVJ0LqtBhF4v58z1-qRms3YgHjDpLLDfGwlEI3Q,20630
+couchbase_mcp_server-0.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+couchbase_mcp_server-0.5.0.dist-info/entry_points.txt,sha256=iU5pF4kIMTnNhoMPHhdH-k8o1Fmxb_iM9qJHCZcL6Ak,57
+couchbase_mcp_server-0.5.0.dist-info/top_level.txt,sha256=cQeSKgjLtHXStynG6fJkj8o4tBep9OkDai_4h5bf_4I,23
+couchbase_mcp_server-0.5.0.dist-info/RECORD,,

mcp_server.py

@@ -78,9 +78,22 @@ async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
     help="Couchbase database password (required for operations)",
 )
 @click.option(
-    "--bucket-name",
-    envvar="CB_BUCKET_NAME",
-    help="Couchbase bucket name (required for operations)",
+    "--ca-cert-path",
+    envvar="CB_CA_CERT_PATH",
+    default=None,
+    help="Path to the server trust store (CA certificate) file. The certificate at this path is used to verify the server certificate during the authentication process.",
+)
+@click.option(
+    "--client-cert-path",
+    envvar="CB_CLIENT_CERT_PATH",
+    default=None,
+    help="Path to the client certificate file used for mTLS authentication.",
+)
+@click.option(
+    "--client-key-path",
+    envvar="CB_CLIENT_KEY_PATH",
+    default=None,
+    help="Path to the client certificate key file used for mTLS authentication.",
 )
 @click.option(
     "--read-only-query-mode",
@@ -121,7 +134,9 @@ def main(
     connection_string,
     username,
     password,
-    bucket_name,
+    ca_cert_path,
+    client_cert_path,
+    client_key_path,
     read_only_query_mode,
     transport,
     host,
@@ -133,7 +148,9 @@ def main(
         "connection_string": connection_string,
         "username": username,
         "password": password,
-        "bucket_name": bucket_name,
+        "ca_cert_path": ca_cert_path,
+        "client_cert_path": client_cert_path,
+        "client_key_path": client_key_path,
         "read_only_query_mode": read_only_query_mode,
         "transport": transport,
         "host": host,

tools/__init__.py

@@ -19,16 +19,22 @@ from .query import (
 
 # Server tools
 from .server import (
+    get_buckets_in_cluster,
+    get_collections_in_scope,
     get_scopes_and_collections_in_bucket,
+    get_scopes_in_bucket,
     get_server_configuration_status,
     test_cluster_connection,
 )
 
 # List of all tools for easy registration
 ALL_TOOLS = [
+    get_buckets_in_cluster,
     get_server_configuration_status,
     test_cluster_connection,
     get_scopes_and_collections_in_bucket,
+    get_collections_in_scope,
+    get_scopes_in_bucket,
     get_document_by_id,
     upsert_document_by_id,
     delete_document_by_id,
@@ -41,6 +47,9 @@ __all__ = [
     "get_server_configuration_status",
     "test_cluster_connection",
     "get_scopes_and_collections_in_bucket",
+    "get_collections_in_scope",
+    "get_scopes_in_bucket",
+    "get_buckets_in_cluster",
     "get_document_by_id",
     "upsert_document_by_id",
     "delete_document_by_id",

tools/kv.py

@@ -9,18 +9,25 @@ from typing import Any
 
 from mcp.server.fastmcp import Context
 
+from utils.connection import connect_to_bucket
 from utils.constants import MCP_SERVER_NAME
-from utils.context import ensure_bucket_connection
+from utils.context import get_cluster_connection
 
 logger = logging.getLogger(f"{MCP_SERVER_NAME}.tools.kv")
 
 
 def get_document_by_id(
-    ctx: Context, scope_name: str, collection_name: str, document_id: str
+    ctx: Context,
+    bucket_name: str,
+    scope_name: str,
+    collection_name: str,
+    document_id: str,
 ) -> dict[str, Any]:
     """Get a document by its ID from the specified scope and collection.
     If the document is not found, it will raise an exception."""
-    bucket = ensure_bucket_connection(ctx)
+
+    cluster = get_cluster_connection(ctx)
+    bucket = connect_to_bucket(cluster, bucket_name)
     try:
         collection = bucket.scope(scope_name).collection(collection_name)
         result = collection.get(document_id)
@@ -32,6 +39,7 @@ def get_document_by_id(
 
 def upsert_document_by_id(
     ctx: Context,
+    bucket_name: str,
     scope_name: str,
     collection_name: str,
     document_id: str,
@@ -39,7 +47,8 @@ def upsert_document_by_id(
 ) -> bool:
     """Insert or update a document by its ID.
     Returns True on success, False on failure."""
-    bucket = ensure_bucket_connection(ctx)
+    cluster = get_cluster_connection(ctx)
+    bucket = connect_to_bucket(cluster, bucket_name)
     try:
         collection = bucket.scope(scope_name).collection(collection_name)
         collection.upsert(document_id, document_content)
@@ -51,11 +60,16 @@ def upsert_document_by_id(
 
 
 def delete_document_by_id(
-    ctx: Context, scope_name: str, collection_name: str, document_id: str
+    ctx: Context,
+    bucket_name: str,
+    scope_name: str,
+    collection_name: str,
+    document_id: str,
 ) -> bool:
     """Delete a document by its ID.
     Returns True on success, False on failure."""
-    bucket = ensure_bucket_connection(ctx)
+    cluster = get_cluster_connection(ctx)
+    bucket = connect_to_bucket(cluster, bucket_name)
     try:
         collection = bucket.scope(scope_name).collection(collection_name)
         collection.remove(document_id)

tools/query.py

@@ -10,22 +10,23 @@ from typing import Any
 from lark_sqlpp import modifies_data, modifies_structure, parse_sqlpp
 from mcp.server.fastmcp import Context
 
+from utils.connection import connect_to_bucket
 from utils.constants import MCP_SERVER_NAME
-from utils.context import ensure_bucket_connection
+from utils.context import get_cluster_connection
 
 logger = logging.getLogger(f"{MCP_SERVER_NAME}.tools.query")
 
 
 def get_schema_for_collection(
-    ctx: Context, scope_name: str, collection_name: str
+    ctx: Context, bucket_name: str, scope_name: str, collection_name: str
 ) -> dict[str, Any]:
     """Get the schema for a collection in the specified scope.
     Returns a dictionary with the collection name and the schema returned by running INFER query on the Couchbase collection.
     """
     schema = {"collection_name": collection_name, "schema": []}
     try:
-        query = f"INFER {collection_name}"
-        result = run_sql_plus_plus_query(ctx, scope_name, query)
+        query = f"INFER `{collection_name}`"
+        result = run_sql_plus_plus_query(ctx, bucket_name, scope_name, query)
         # Result is a list of list of schemas. We convert it to a list of schemas.
         if result:
             schema["schema"] = result[0]
@@ -36,10 +37,13 @@ def get_schema_for_collection(
 
 
 def run_sql_plus_plus_query(
-    ctx: Context, scope_name: str, query: str
+    ctx: Context, bucket_name: str, scope_name: str, query: str
 ) -> list[dict[str, Any]]:
     """Run a SQL++ query on a scope and return the results as a list of JSON objects."""
-    bucket = ensure_bucket_connection(ctx)
+    cluster = get_cluster_connection(ctx)
+
+    bucket = connect_to_bucket(cluster, bucket_name)
+
     app_context = ctx.request_context.lifespan_context
     read_only_query_mode = app_context.read_only_query_mode
     logger.info(f"Running SQL++ queries in read-only mode: {read_only_query_mode}")
@@ -75,3 +79,20 @@ def run_sql_plus_plus_query(
     except Exception as e:
         logger.error(f"Error running query: {e!s}", exc_info=True)
         raise
+
+
+# Don't expose this function to the MCP server until we have a use case
+def run_cluster_query(ctx: Context, query: str, **kwargs: Any) -> list[dict[str, Any]]:
+    """Run a query on the cluster object and return the results as a list of JSON objects."""
+
+    cluster = get_cluster_connection(ctx)
+    results = []
+
+    try:
+        result = cluster.query(query, **kwargs)
+        for row in result:
+            results.append(row)
+        return results
+    except Exception as e:
+        logger.error(f"Error running query: {e}")
+        raise

tools/server.py

@@ -1,7 +1,7 @@
 """
 Tools for server operations.
 
-This module contains tools for getting the server status, testing the connection, and getting the scopes and collections in the bucket.
+This module contains tools for getting the server status, testing the connection, and getting the buckets in the cluster, the scopes and collections in the bucket.
 """
 
 import logging
@@ -9,9 +9,11 @@ from typing import Any
 
 from mcp.server.fastmcp import Context
 
+from tools.query import run_cluster_query
 from utils.config import get_settings
+from utils.connection import connect_to_bucket
 from utils.constants import MCP_SERVER_NAME
-from utils.context import ensure_bucket_connection
+from utils.context import get_cluster_connection
 
 logger = logging.getLogger(f"{MCP_SERVER_NAME}.tools.server")
 
@@ -26,15 +28,16 @@ def get_server_configuration_status(ctx: Context) -> dict[str, Any]:
     configuration = {
         "connection_string": settings.get("connection_string", "Not set"),
         "username": settings.get("username", "Not set"),
-        "bucket_name": settings.get("bucket_name", "Not set"),
         "read_only_query_mode": settings.get("read_only_query_mode", True),
         "password_configured": bool(settings.get("password")),
+        "ca_cert_path_configured": bool(settings.get("ca_cert_path")),
+        "client_cert_path_configured": bool(settings.get("client_cert_path")),
+        "client_key_path_configured": bool(settings.get("client_key_path")),
     }
 
     app_context = ctx.request_context.lifespan_context
     connection_status = {
         "cluster_connected": app_context.cluster is not None,
-        "bucket_connected": app_context.bucket is not None,
     }
 
     return {
@@ -45,39 +48,46 @@ def get_server_configuration_status(ctx: Context) -> dict[str, Any]:
     }
 
 
-def test_cluster_connection(ctx: Context) -> dict[str, Any]:
-    """Test the connection to Couchbase cluster and bucket.
+def test_cluster_connection(
+    ctx: Context, bucket_name: str | None = None
+) -> dict[str, Any]:
+    """Test the connection to Couchbase cluster and optionally to a bucket.
     This tool verifies the connection to the Couchbase cluster and bucket by establishing the connection if it is not already established.
+    If bucket name is not provided, it will not try to connect to the bucket specified in the MCP server settings.
     Returns connection status and basic cluster information.
     """
     try:
-        bucket = ensure_bucket_connection(ctx)
-
-        # Test basic connectivity by getting bucket name
-        bucket_name = bucket.name
+        cluster = get_cluster_connection(ctx)
+        bucket = None
+        if bucket_name:
+            bucket = connect_to_bucket(cluster, bucket_name)
 
         return {
             "status": "success",
-            "cluster_connected": True,
-            "bucket_connected": True,
+            "cluster_connected": cluster.connected,
+            "bucket_connected": bucket is not None,
             "bucket_name": bucket_name,
-            "message": "Successfully connected to Couchbase cluster and bucket",
+            "message": "Successfully connected to Couchbase cluster",
         }
     except Exception as e:
         return {
             "status": "error",
             "cluster_connected": False,
             "bucket_connected": False,
+            "bucket_name": bucket_name,
             "error": str(e),
-            "message": "Failed to connect to Couchbase",
+            "message": "Failed to connect to Couchbase cluster",
         }
 
 
-def get_scopes_and_collections_in_bucket(ctx: Context) -> dict[str, list[str]]:
+def get_scopes_and_collections_in_bucket(
+    ctx: Context, bucket_name: str
+) -> dict[str, list[str]]:
     """Get the names of all scopes and collections in the bucket.
     Returns a dictionary with scope names as keys and lists of collection names as values.
     """
-    bucket = ensure_bucket_connection(ctx)
+    cluster = get_cluster_connection(ctx)
+    bucket = connect_to_bucket(cluster, bucket_name)
     try:
         scopes_collections = {}
         collection_manager = bucket.collections()
@@ -89,3 +99,41 @@ def get_scopes_and_collections_in_bucket(ctx: Context) -> dict[str, list[str]]:
     except Exception as e:
         logger.error(f"Error getting scopes and collections: {e}")
         raise
+
+
+def get_buckets_in_cluster(ctx: Context) -> list[str]:
+    """Get the names of all the accessible buckets in the cluster."""
+    cluster = get_cluster_connection(ctx)
+    bucket_manager = cluster.buckets()
+    buckets_with_settings = bucket_manager.get_all_buckets()
+
+    buckets = []
+    for bucket in buckets_with_settings:
+        buckets.append(bucket.name)
+
+    return buckets
+
+
+def get_scopes_in_bucket(ctx: Context, bucket_name: str) -> list[str]:
+    """Get the names of all scopes in the given bucket."""
+    cluster = get_cluster_connection(ctx)
+    bucket = connect_to_bucket(cluster, bucket_name)
+    try:
+        scopes = bucket.collections().get_all_scopes()
+        return [scope.name for scope in scopes]
+    except Exception as e:
+        logger.error(f"Error getting scopes in the bucket {bucket_name}: {e}")
+        raise
+
+
+def get_collections_in_scope(
+    ctx: Context, bucket_name: str, scope_name: str
+) -> list[str]:
+    """Get the names of all collections in the given scope and bucket."""
+
+    # Get the collections in the scope using system:all_keyspaces collection
+    query = "SELECT DISTINCT(name) as collection_name FROM system:all_keyspaces where `bucket`=$bucket_name and `scope`=$scope_name"
+    results = run_cluster_query(
+        ctx, query, bucket_name=bucket_name, scope_name=scope_name
+    )
+    return [result["collection_name"] for result in results]

utils/__init__.py

@@ -7,8 +7,6 @@ This module contains utility functions for configuration, connection, and contex
 # Configuration utilities
 from .config import (
     get_settings,
-    validate_connection_config,
-    validate_required_param,
 )
 
 # Connection utilities
@@ -33,7 +31,7 @@ from .constants import (
 # Context utilities
 from .context import (
     AppContext,
-    ensure_bucket_connection,
+    get_cluster_connection,
 )
 
 # Note: Individual modules create their own hierarchical loggers using:
@@ -42,14 +40,12 @@ from .context import (
 __all__ = [
     # Config
     "get_settings",
-    "validate_required_param",
-    "validate_connection_config",
     # Connection
     "connect_to_couchbase_cluster",
     "connect_to_bucket",
     # Context
     "AppContext",
-    "ensure_bucket_connection",
+    "get_cluster_connection",
     # Constants
     "MCP_SERVER_NAME",
     "DEFAULT_READ_ONLY_MODE",

utils/config.py

@@ -7,32 +7,7 @@ from .constants import MCP_SERVER_NAME
 logger = logging.getLogger(f"{MCP_SERVER_NAME}.utils.config")
 
 
-def validate_required_param(
-    ctx: click.Context, param: click.Parameter, value: str | None
-) -> str:
-    """Validate that a required parameter is not empty."""
-    if not value or value.strip() == "":
-        raise click.BadParameter(f"{param.name} cannot be empty")
-    return value
-
-
 def get_settings() -> dict:
     """Get settings from Click context."""
     ctx = click.get_current_context()
     return ctx.obj or {}
-
-
-def validate_connection_config() -> None:
-    """Validate that all required parameters for the MCP server are available when needed."""
-    settings = get_settings()
-    required_params = ["connection_string", "username", "password", "bucket_name"]
-    missing_params = []
-
-    for param in required_params:
-        if not settings.get(param):
-            missing_params.append(param)
-
-    if missing_params:
-        error_msg = f"Missing required parameters for the MCP server: {', '.join(missing_params)}"
-        logger.error(error_msg)
-        raise ValueError(error_msg)

utils/connection.py

@@ -1,7 +1,8 @@
 import logging
+import os
 from datetime import timedelta
 
-from couchbase.auth import PasswordAuthenticator
+from couchbase.auth import CertificateAuthenticator, PasswordAuthenticator
 from couchbase.cluster import Bucket, Cluster
 from couchbase.options import ClusterOptions
 
@@ -11,15 +12,40 @@ logger = logging.getLogger(f"{MCP_SERVER_NAME}.utils.connection")
 
 
 def connect_to_couchbase_cluster(
-    connection_string: str, username: str, password: str
+    connection_string: str,
+    username: str,
+    password: str,
+    ca_cert_path: str | None = None,
+    client_cert_path: str | None = None,
+    client_key_path: str | None = None,
 ) -> Cluster:
     """Connect to Couchbase cluster and return the cluster object if successful.
+    The connection can be established using the client certificate and key or the username and password. Optionally, the CA root certificate path can also be provided.
+    Either of the path to the client certificate and key or the username and password should be provided.
+    If the client certificate and key are provided, the username and password are not used.
+    If both the client certificate and key and the username and password are provided, the client certificate is used for authentication.
     If the connection fails, it will raise an exception.
     """
 
     try:
         logger.info("Connecting to Couchbase cluster...")
-        auth = PasswordAuthenticator(username, password)
+        if client_cert_path and client_key_path:
+            logger.info("Connecting to Couchbase cluster with client certificate...")
+            if not os.path.exists(client_cert_path) or not os.path.exists(
+                client_key_path
+            ):
+                raise FileNotFoundError(
+                    f"Client certificate files not found at {os.path.basename(client_cert_path)} or {os.path.basename(client_key_path)}."
+                )
+
+            auth = CertificateAuthenticator(
+                cert_path=client_cert_path,
+                key_path=client_key_path,
+                trust_store_path=ca_cert_path,
+            )
+        else:
+            logger.info("Connecting to Couchbase cluster with password...")
+            auth = PasswordAuthenticator(username, password, cert_path=ca_cert_path)
         options = ClusterOptions(auth)
         options.apply_profile("wan_development")
 
@@ -38,7 +64,6 @@ def connect_to_bucket(cluster: Cluster, bucket_name: str) -> Bucket:
     If the operation fails, it will raise an exception.
     """
     try:
-        logger.info(f"Connecting to bucket: {bucket_name}")
         bucket = cluster.bucket(bucket_name)
         return bucket
     except Exception as e:

utils/context.py

@@ -1,11 +1,11 @@
 import logging
 from dataclasses import dataclass
 
-from couchbase.cluster import Bucket, Cluster
+from couchbase.cluster import Cluster
 from mcp.server.fastmcp import Context
 
-from utils.config import get_settings, validate_connection_config
-from utils.connection import connect_to_bucket, connect_to_couchbase_cluster
+from utils.config import get_settings
+from utils.connection import connect_to_couchbase_cluster
 from utils.constants import MCP_SERVER_NAME
 
 logger = logging.getLogger(f"{MCP_SERVER_NAME}.utils.context")
@@ -16,7 +16,6 @@ class AppContext:
     """Context for the MCP server."""
 
     cluster: Cluster | None = None
-    bucket: Bucket | None = None
     read_only_query_mode: bool = True
 
 
@@ -30,51 +29,36 @@ def _set_cluster_in_lifespan_context(ctx: Context) -> None:
         connection_string = settings.get("connection_string")
         username = settings.get("username")
         password = settings.get("password")
+        ca_cert_path = settings.get("ca_cert_path")
+        client_cert_path = settings.get("client_cert_path")
+        client_key_path = settings.get("client_key_path")
+
         cluster = connect_to_couchbase_cluster(
             connection_string,  # type: ignore
             username,  # type: ignore
             password,  # type: ignore
+            ca_cert_path,
+            client_cert_path,
+            client_key_path,
         )
         ctx.request_context.lifespan_context.cluster = cluster
     except Exception as e:
         logger.error(
-            f"Failed to connect to Couchbase: {e} \n Please check your connection string, username and password"
+            "Failed to connect to Couchbase: %s\n"
+            "Verify connection string, and either:\n"
+            "- Username/password are correct, or\n"
+            "- Client certificate and key exist and match server mapping.\n"
+            "If using self-signed or custom CA, set CB_CA_CERT_PATH to the CA file.",
+            e,
         )
         raise
 
 
-def _set_bucket_in_lifespan_context(ctx: Context) -> None:
-    """Set the bucket in the lifespan context.
-    If the bucket is not set, it will try to connect to the bucket using the cluster object in the lifespan context.
+def get_cluster_connection(ctx: Context) -> Cluster:
+    """Return the cluster connection from the lifespan context.
     If the cluster is not set, it will try to connect to the cluster using the connection string, username, and password.
-    If the connection fails, it will raise an exception.
     """
-    settings = get_settings()
-    bucket_name = settings.get("bucket_name")
-
-    # If the bucket is not set, try to connect to the bucket using the cluster object in the lifespan context
-    app_context = ctx.request_context.lifespan_context
-
-    try:
-        # If the cluster is not set, try to connect to the cluster
-        if not app_context.cluster:
-            _set_cluster_in_lifespan_context(ctx)
-        cluster = app_context.cluster
-
-        # Try to connect to the bucket using the cluster object
-        bucket = connect_to_bucket(cluster, bucket_name)  # type: ignore
-        app_context.bucket = bucket
-    except Exception as e:
-        logger.error(
-            f"Failed to connect to bucket: {e} \n Please check your bucket name and credentials."
-        )
-        raise
-
-
-def ensure_bucket_connection(ctx: Context) -> Bucket:
-    """Ensure bucket connection is established and return the bucket object."""
-    validate_connection_config()
     app_context = ctx.request_context.lifespan_context
-    if not app_context.bucket:
-        _set_bucket_in_lifespan_context(ctx)
-    return app_context.bucket
+    if not app_context.cluster:
+        _set_cluster_in_lifespan_context(ctx)
+    return app_context.cluster

couchbase_mcp_server-0.4.0rc1.dist-info/RECORD

@@ -1,16 +0,0 @@
-mcp_server.py,sha256=t-TFlzAPH0qUILFjX33n6VnEvTgWAjCRy3HrKkKosWE,4416
-couchbase_mcp_server-0.4.0rc1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-tools/__init__.py,sha256=jVvVnpoSJrYFmxAnx2vkyAuKZ1-Ti1fzdIgbO0yqAcM,1097
-tools/kv.py,sha256=LDDASE4nD4oiTkDzSSYIrmvleqn7e8W-14UOql_SWK8,2199
-tools/query.py,sha256=BYpJkgiCAINqgreW22uk-6JjrKrZkswGYKRhU1l-jLI,2901
-tools/server.py,sha256=a4rDDDYO7WNTcKN8KjiQlnsIZ1_ydlAVgIy5nxxic5g,3251
-utils/__init__.py,sha256=E7Puxqate6J5xdNWSzLFU33UfsbSGE9B4aiMB696v04,1353
-utils/config.py,sha256=vCZfyhQXnbTPwcJi3YfLTXqqirCeHVTSyHui5_aGchs,1136
-utils/connection.py,sha256=2a_syAAMFE2zHEFMzsOJGz4Vhz6Tq3lgna3qfhKva0w,1520
-utils/constants.py,sha256=w0zvQ1zMzJBg44Yl3aQW8KfaaRPn0BgPOLEe8xLeLSE,487
-utils/context.py,sha256=pepc4sCUsmx0itpoJ28_TS03mSXJbQhgTZcN7NAvvTg,3013
-couchbase_mcp_server-0.4.0rc1.dist-info/METADATA,sha256=_hBu07b23dHcalDuRUAS_IM-3N_yxggsKbxGGn-WM6E,19329
-couchbase_mcp_server-0.4.0rc1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-couchbase_mcp_server-0.4.0rc1.dist-info/entry_points.txt,sha256=iU5pF4kIMTnNhoMPHhdH-k8o1Fmxb_iM9qJHCZcL6Ak,57
-couchbase_mcp_server-0.4.0rc1.dist-info/top_level.txt,sha256=cQeSKgjLtHXStynG6fJkj8o4tBep9OkDai_4h5bf_4I,23
-couchbase_mcp_server-0.4.0rc1.dist-info/RECORD,,