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

certs/capella_root_ca.pem

@@ -0,0 +1,19 @@
+-----BEGIN CERTIFICATE-----
+MIIDFTCCAf2gAwIBAgIRANLVkgOvtaXiQJi0V6qeNtswDQYJKoZIhvcNAQELBQAw
+JDESMBAGA1UECgwJQ291Y2hiYXNlMQ4wDAYDVQQLDAVDbG91ZDAeFw0xOTEyMDYy
+MjEyNTlaFw0yOTEyMDYyMzEyNTlaMCQxEjAQBgNVBAoMCUNvdWNoYmFzZTEOMAwG
+A1UECwwFQ2xvdWQwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCfvOIi
+enG4Dp+hJu9asdxEMRmH70hDyMXv5ZjBhbo39a42QwR59y/rC/sahLLQuNwqif85
+Fod1DkqgO6Ng3vecSAwyYVkj5NKdycQu5tzsZkghlpSDAyI0xlIPSQjoORA/pCOU
+WOpymA9dOjC1bo6rDyw0yWP2nFAI/KA4Z806XeqLREuB7292UnSsgFs4/5lqeil6
+rL3ooAw/i0uxr/TQSaxi1l8t4iMt4/gU+W52+8Yol0JbXBTFX6itg62ppb/Eugmn
+mQRMgL67ccZs7cJ9/A0wlXencX2ohZQOR3mtknfol3FH4+glQFn27Q4xBCzVkY9j
+KQ20T1LgmGSngBInAgMBAAGjQjBAMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYE
+FJQOBPvrkU2In1Sjoxt97Xy8+cKNMA4GA1UdDwEB/wQEAwIBhjANBgkqhkiG9w0B
+AQsFAAOCAQEARgM6XwcXPLSpFdSf0w8PtpNGehmdWijPM3wHb7WZiS47iNen3oq8
+m2mm6V3Z57wbboPpfI+VEzbhiDcFfVnK1CXMC0tkF3fnOG1BDDvwt4jU95vBiNjY
+xdzlTP/Z+qr0cnVbGBSZ+fbXstSiRaaAVcqQyv3BRvBadKBkCyPwo+7svQnScQ5P
+Js7HEHKVms5tZTgKIw1fbmgR2XHleah1AcANB+MAPBCcTgqurqr5G7W2aPSBLLGA
+fRIiVzm7VFLc7kWbp7ENH39HVG6TZzKnfl9zJYeiklo5vQQhGSMhzBsO70z4RRzi
+DPFAN/4qZAgD5q3AFNIq2WWADFQGSwVJhg==
+-----END CERTIFICATE-----

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

@@ -1,32 +1,32 @@
 Metadata-Version: 2.4
 Name: couchbase-mcp-server
-Version: 0.4.0rc1
+Version: 0.5.1
 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
 Project-URL: Homepage, https://github.com/Couchbase-Ecosystem/mcp-server-couchbase
 Project-URL: Documentation, https://github.com/Couchbase-Ecosystem/mcp-server-couchbase#readme
 Project-URL: Issues, https://github.com/Couchbase-Ecosystem/mcp-server-couchbase/issues
+Author-email: Nithish Raghunandanan <devadvocates@couchbase.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Database
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: click==8.2.1
-Requires-Dist: couchbase==4.4.0
-Requires-Dist: lark-sqlpp==0.0.1
-Requires-Dist: mcp[cli]==1.12.0
+Requires-Python: <3.14,>=3.10
+Requires-Dist: click<9.0.0,>=8.2.1
+Requires-Dist: couchbase<5.0.0,>=4.4.0
+Requires-Dist: lark-sqlpp>=0.0.1
+Requires-Dist: mcp[cli]<2.0.0,>=1.20.0
+Requires-Dist: urllib3>=2.0.0
 Provides-Extra: dev
-Requires-Dist: ruff==0.12.5; extra == "dev"
-Requires-Dist: pre-commit==4.2.0; extra == "dev"
-Dynamic: license-file
+Requires-Dist: pre-commit==4.2.0; extra == 'dev'
+Requires-Dist: ruff==0.12.5; extra == 'dev'
+Description-Content-Type: text/markdown
 
 # Couchbase MCP Server
 
 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
@@ -43,6 +46,9 @@ An [MCP](https://modelcontextprotocol.io/) server implementation of Couchbase th
   - There is an option in the MCP server, `CB_MCP_READ_ONLY_QUERY_MODE` that is set to true by default to disable running SQL++ queries that change the data or the underlying collection structure. Note that the documents can still be updated by ID.
 - Get the status of the MCP server
 - Check the cluster credentials by connecting to the cluster
+- List all indexes in the cluster with their definitions, with optional filtering by bucket, scope, collection and index name.
+- Get index recommendations from Couchbase Index Advisor for a given SQL++ query to optimize query performance
+- Get cluster health status and list of all running services
 
 ## Prerequisites
 
@@ -53,7 +59,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 +67,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 +78,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 +135,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 +149,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 +258,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 +291,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 +371,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 +399,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 +424,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.1.dist-info/RECORD

@@ -0,0 +1,19 @@
+certs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+certs/capella_root_ca.pem,sha256=SuSjgKclcQQg0kheTRd3dg6B0FUsUy717T5n3xcAU_E,1131
+mcp_server.py,sha256=dvHQR-55JhuXX_bj2hLU0ek411qPp0qHEKqAmPdwjKU,4991
+tools/__init__.py,sha256=otQd8IiEILtl1jgorEO1E9KqL_2xBBlqwnVHejoCPE0,1668
+tools/index.py,sha256=cCBr0ptFBVc-HN5SoCauQAh2DsAP_Is8NPUSa6QcLM0,6682
+tools/kv.py,sha256=NGUs43iuXElj9rYe4RCyCStqoh5y1fUgbg1oWuU4WeQ,2493
+tools/query.py,sha256=fSSG7XuxnND1lHwI-r8y_M3h6f82vCXxCwB_A2wHN-M,3598
+tools/server.py,sha256=4krPjBoQmUHUmOE03T0CcCGFJtoaeHVS91oOrYj8JsA,6670
+utils/__init__.py,sha256=Fcbp-VIK0Gwwy7hl1AjV9NBKZsscmOV2vYdTBam5M3A,1361
+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
+utils/index_utils.py,sha256=W0rvoBXU_2aB9m-HDlLChZoMzvlIX6FUWF6RTsYGfYM,10910
+couchbase_mcp_server-0.5.1.dist-info/METADATA,sha256=ufeqvKJPZcWL_b0uki8UqGMuU34c2R2--aNnP1211MY,20964
+couchbase_mcp_server-0.5.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+couchbase_mcp_server-0.5.1.dist-info/entry_points.txt,sha256=iU5pF4kIMTnNhoMPHhdH-k8o1Fmxb_iM9qJHCZcL6Ak,57
+couchbase_mcp_server-0.5.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+couchbase_mcp_server-0.5.1.dist-info/RECORD,,

{couchbase_mcp_server-0.4.0rc1.dist-info → couchbase_mcp_server-0.5.1.dist-info}/WHEEL

@@ -1,5 +1,4 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py3-none-any
-

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,
@@ -148,7 +165,6 @@ def main(
         {
             "host": host,
             "port": port,
-            "transport": sdk_transport,
         }
         if transport in NETWORK_TRANSPORTS
         else {}

tools/__init__.py

@@ -4,6 +4,9 @@ Couchbase MCP Tools
 This module contains all the MCP tools for Couchbase operations.
 """
 
+# Index tools
+from .index import get_index_advisor_recommendations, list_indexes
+
 # Key-Value tools
 from .kv import (
     delete_document_by_id,
@@ -19,21 +22,31 @@ from .query import (
 
 # Server tools
 from .server import (
+    get_buckets_in_cluster,
+    get_cluster_health_and_services,
+    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,
     get_schema_for_collection,
     run_sql_plus_plus_query,
+    get_index_advisor_recommendations,
+    list_indexes,
+    get_cluster_health_and_services,
 ]
 
 __all__ = [
@@ -41,11 +54,17 @@ __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",
     "get_schema_for_collection",
     "run_sql_plus_plus_query",
+    "get_index_advisor_recommendations",
+    "list_indexes",
+    "get_cluster_health_and_services",
     # Convenience
     "ALL_TOOLS",
 ]

tools/index.py

@@ -0,0 +1,172 @@
+"""
+Tools for index operations.
+
+This module contains tools for listing and managing indexes in the Couchbase cluster and getting index recommendations using the Couchbase Index Advisor.
+"""
+
+import logging
+from typing import Any
+
+from mcp.server.fastmcp import Context
+
+from tools.query import run_sql_plus_plus_query
+from utils.config import get_settings
+from utils.constants import MCP_SERVER_NAME
+from utils.index_utils import (
+    fetch_indexes_from_rest_api,
+    process_index_data,
+    validate_connection_settings,
+    validate_filter_params,
+)
+
+logger = logging.getLogger(f"{MCP_SERVER_NAME}.tools.index")
+
+
+def get_index_advisor_recommendations(
+    ctx: Context, bucket_name: str, scope_name: str, query: str
+) -> dict[str, Any]:
+    """Get index recommendations from Couchbase Index Advisor for a given SQL++ query.
+
+    The Index Advisor analyzes the query and provides recommendations for optimal indexes.
+    This tool works with SELECT, UPDATE, DELETE, or MERGE queries.
+    The queries will be run on the specified scope in the specified bucket.
+
+    Returns a dictionary with:
+    - current_used_indexes: Array of currently used indexes (if any)
+    - recommended_indexes: Array of recommended secondary indexes (if any)
+    - recommended_covering_indexes: Array of recommended covering indexes (if any)
+
+    Each index object contains:
+    - index: The CREATE INDEX SQL++ command
+    - statements: Array of statement objects with the query and run count
+    """
+    try:
+        # Build the ADVISOR query
+        advisor_query = f"SELECT ADVISOR('{query}') AS advisor_result"
+
+        logger.info("Running Index Advisor for the provided query")
+
+        # Execute the ADVISOR function at cluster level using run_sql_plus_plus_query
+        advisor_results = run_sql_plus_plus_query(
+            ctx, bucket_name, scope_name, advisor_query
+        )
+
+        if not advisor_results:
+            return {
+                "message": "No recommendations available",
+                "current_used_indexes": [],
+                "recommended_indexes": [],
+                "recommended_covering_indexes": [],
+            }
+
+        # The result is wrapped in advisor_result key
+        advisor_data = advisor_results[0].get("advisor_result", {})
+
+        # Extract the relevant fields with defaults
+        response = {
+            "current_used_indexes": advisor_data.get("current_used_indexes", []),
+            "recommended_indexes": advisor_data.get("recommended_indexes", []),
+            "recommended_covering_indexes": advisor_data.get(
+                "recommended_covering_indexes", []
+            ),
+        }
+
+        # Add summary information for better user experience
+        response["summary"] = {
+            "current_indexes_count": len(response["current_used_indexes"]),
+            "recommended_indexes_count": len(response["recommended_indexes"]),
+            "recommended_covering_indexes_count": len(
+                response["recommended_covering_indexes"]
+            ),
+            "has_recommendations": bool(
+                response["recommended_indexes"]
+                or response["recommended_covering_indexes"]
+            ),
+        }
+
+        logger.info(
+            f"Index Advisor completed. Found {response['summary']['recommended_indexes_count']} recommended indexes"
+        )
+
+        return response
+
+    except Exception as e:
+        logger.error(f"Error running Index Advisor: {e!s}", exc_info=True)
+        raise
+
+
+def list_indexes(
+    ctx: Context,
+    bucket_name: str | None = None,
+    scope_name: str | None = None,
+    collection_name: str | None = None,
+    index_name: str | None = None,
+    include_raw_index_stats: bool = False,
+) -> list[dict[str, Any]]:
+    """List all indexes in the cluster with optional filtering by bucket, scope, collection, and index name.
+    Returns a list of indexes with their names and CREATE INDEX definitions.
+    Uses the Index Service REST API (/getIndexStatus) to retrieve index information directly.
+
+    Args:
+        ctx: MCP context for cluster connection
+        bucket_name: Optional bucket name to filter indexes
+        scope_name: Optional scope name to filter indexes (requires bucket_name)
+        collection_name: Optional collection name to filter indexes (requires bucket_name and scope_name)
+        index_name: Optional index name to filter indexes (requires bucket_name, scope_name, and collection_name)
+        include_raw_index_stats: If True, include raw index stats (as-is from API) in addition
+                              to cleaned-up version. Default is False.
+
+    Returns:
+        List of dictionaries with keys:
+        - name (str): Index name
+        - definition (str): Cleaned-up CREATE INDEX statement
+        - status (str): Current status of the index (e.g., "Ready", "Building", "Deferred")
+        - isPrimary (bool): Whether this is a primary index
+        - bucket (str): Bucket name where the index exists
+        - scope (str): Scope name where the index exists
+        - collection (str): Collection name where the index exists
+        - raw_index_stats (dict, optional): Complete raw index status object from API including metadata,
+                                           state, keyspace info, etc. (only if include_raw_index_stats=True)
+    """
+    try:
+        # Validate parameters
+        validate_filter_params(bucket_name, scope_name, collection_name, index_name)
+
+        # Get and validate connection settings
+        settings = get_settings()
+        validate_connection_settings(settings)
+
+        # Fetch indexes from REST API
+        logger.info(
+            f"Fetching indexes from REST API for bucket={bucket_name}, "
+            f"scope={scope_name}, collection={collection_name}, index={index_name}"
+        )
+
+        raw_indexes = fetch_indexes_from_rest_api(
+            settings["connection_string"],
+            settings["username"],
+            settings["password"],
+            bucket_name=bucket_name,
+            scope_name=scope_name,
+            collection_name=collection_name,
+            index_name=index_name,
+            ca_cert_path=settings.get("ca_cert_path"),
+        )
+
+        # Process and format the results
+        indexes = [
+            processed
+            for idx in raw_indexes
+            if (processed := process_index_data(idx, include_raw_index_stats))
+            is not None
+        ]
+
+        logger.info(
+            f"Found {len(indexes)} indexes from REST API "
+            f"(include_raw_index_stats={include_raw_index_stats})"
+        )
+        return indexes
+
+    except Exception as e:
+        logger.error(f"Error listing indexes: {e}", exc_info=True)
+        raise

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)