couchbase-mcp-server 0.5.3__py3-none-any.whl → 0.6.0__py3-none-any.whl

{couchbase_mcp_server-0.5.3.dist-info → couchbase_mcp_server-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: couchbase-mcp-server
-Version: 0.5.3
+Version: 0.6.0
 Summary: Couchbase MCP Server - The Developer Data Platform for Critical Applications in Our AI World
 Project-URL: Homepage, https://github.com/Couchbase-Ecosystem/mcp-server-couchbase
 Project-URL: Documentation, https://github.com/Couchbase-Ecosystem/mcp-server-couchbase#readme
@@ -20,6 +20,7 @@ Requires-Dist: urllib3>=2.0.0
 Provides-Extra: dev
 Requires-Dist: pre-commit==4.2.0; extra == 'dev'
 Requires-Dist: pytest-asyncio==0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
 Requires-Dist: pytest==8.3.3; extra == 'dev'
 Requires-Dist: ruff==0.12.5; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -36,32 +37,49 @@ An [MCP](https://modelcontextprotocol.io/) server implementation of Couchbase th
 
 <!-- mcp-name: io.github.Couchbase-Ecosystem/mcp-server-couchbase -->
 
-## 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
-- Delete a document by ID from a specified scope and collection
-- Run a [SQL++ query](https://www.couchbase.com/sqlplusplus/) on a specified scope
-  - Queries are automatically scoped to the specified bucket and scope, so use collection names directly (e.g., use `SELECT * FROM users` instead of `SELECT * FROM bucket.scope.users`)
-  - 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
-- Query performance analysis tools:
-  - Get longest running queries by average service time
-  - Get most frequently executed queries
-  - Get queries with the largest response sizes
-  - Get queries with the largest result counts
-  - Get queries that use a primary index (potential performance concern)
-  - Get queries that don't use a covering index
-  - Get queries that are not selective (index scans return many more documents than final result)
+## Features/Tools
+### Cluster setup & health tools
+| Tool Name | Description |
+|-----------|-------------|
+| `get_server_configuration_status` | Get the status of the MCP server |
+| `test_cluster_connection` | Check the cluster credentials by connecting to the cluster |
+| `get_cluster_health_and_services` | Get cluster health status and list of all running services |
+
+### Data model & schema discovery tools
+| Tool Name | Description |
+|-----------|-------------|
+| `get_buckets_in_cluster` | Get a list of all the buckets in the cluster |
+| `get_scopes_in_bucket` | Get a list of all the scopes in the specified bucket |
+| `get_collections_in_scope` | 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_scopes_and_collections_in_bucket` | Get a list of all the scopes and collections in the specified bucket |
+| `get_schema_for_collection` | Get the structure for a collection |
+
+### Document KV operations tools
+| Tool Name | Description |
+|-----------|-------------|
+| `get_document_by_id` | Get a document by ID from a specified scope and collection |
+| `upsert_document_by_id` | Upsert a document by ID to a specified scope and collection. **Disabled by default when `CB_MCP_READ_ONLY_MODE=true`.** |
+| `insert_document_by_id` | Insert a new document by ID (fails if document exists). **Disabled by default when `CB_MCP_READ_ONLY_MODE=true`.** |
+| `replace_document_by_id` | Replace an existing document by ID (fails if document doesn't exist). **Disabled by default when `CB_MCP_READ_ONLY_MODE=true`.** |
+| `delete_document_by_id` | Delete a document by ID from a specified scope and collection. **Disabled by default when `CB_MCP_READ_ONLY_MODE=true`.** |
+
+### Query and indexing tools
+| Tool Name | Description |
+|-----------|-------------|
+| `list_indexes` | List all indexes in the cluster with their definitions, with optional filtering by bucket, scope, collection and index name. |
+| `get_index_advisor_recommendations` | Get index recommendations from Couchbase Index Advisor for a given SQL++ query to optimize query performance |
+| `run_sql_plus_plus_query` | Run a [SQL++ query](https://www.couchbase.com/sqlplusplus/) on a specified scope.<br><br>Queries are automatically scoped to the specified bucket and scope, so use collection names directly (e.g., `SELECT * FROM users` instead of `SELECT * FROM bucket.scope.users`).<br><br>`CB_MCP_READ_ONLY_MODE` is `true` by default, which means that **all write operations (KV and Query)** are disabled. When enabled, KV write tools are not loaded and SQL++ queries that modify data are blocked. |
+
+### Query performance analysis tools
+| Tool Name | Description |
+|-----------|-------------|
+| `get_longest_running_queries` | Get longest running queries by average service time |
+| `get_most_frequent_queries` | Get most frequently executed queries |
+| `get_queries_with_largest_response_sizes` | Get queries with the largest response sizes |
+| `get_queries_with_large_result_count` | Get queries with the largest result counts |
+| `get_queries_using_primary_index` | Get queries that use a primary index (potential performance concern) |
+| `get_queries_not_using_covering_index` | Get queries that don't use a covering index |
+| `get_queries_not_selective` | Get queries that are not selective (index scans return many more documents than final result) |
 
 ## Prerequisites
 
@@ -170,21 +188,135 @@ The server can be configured using environment variables or command line argumen
 | `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_READ_ONLY_MODE` | `--read-only-mode` | Prevent all data modifications (KV and Query). When enabled, KV write tools are not loaded. | `true` |
+| `CB_MCP_READ_ONLY_QUERY_MODE` | `--read-only-query-mode` | **[DEPRECATED]** Prevent queries that modify data. Note that data modification would still be possible via document operations tools. Use `CB_MCP_READ_ONLY_MODE` instead. | `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` |
+| `CB_MCP_DISABLED_TOOLS` | `--disabled-tools` | Tools to disable (see [Disabling Tools](#disabling-tools)) | None |
+
+#### Read-Only Mode Configuration
+
+The MCP server provides two configuration options for controlling write operations:
+
+**`CB_MCP_READ_ONLY_MODE`** (Recommended)
+- When `true` (default): All write operations are disabled. KV write tools (upsert, insert, replace, delete) are **not loaded** and will not be available to the LLM.
+- When `false`: KV write tools are loaded and available.
+
+**`CB_MCP_READ_ONLY_QUERY_MODE`** (Deprecated)
+- This option only controls SQL++ query-based writes but does not prevent KV write operations.
+- **Deprecated**: Use `CB_MCP_READ_ONLY_MODE` instead for comprehensive protection.
+
+**Mode Behavior Truth Table:**
+
+| `READ_ONLY_MODE` | `READ_ONLY_QUERY_MODE` | Result |
+|------------------|------------------------|--------|
+| `true` | `true` | Read-only KV and Query operations. All writes disabled. |
+| `true` | `false` | Read-only KV and Query operations. All writes disabled. |
+| `false` | `true` | Only Query writes disabled. KV writes allowed. |
+| `false` | `false` | All KV and Query operations allowed. |
+
+> **Important**: When `READ_ONLY_MODE` is `true`, it takes precedence and disables all write operations regardless of `READ_ONLY_QUERY_MODE` setting. This is the recommended safe default to prevent inadvertent data modifications by LLMs.
 
 > 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.
 
+### Disabling Tools
+
+You can disable specific tools to prevent them from being loaded and exposed to the MCP client. Disabled tools will not appear in the tool discovery and cannot be invoked by the LLM.
+
+#### Supported Formats
+
+**Comma-separated list:**
+
+```bash
+# Environment variable
+CB_MCP_DISABLED_TOOLS="upsert_document_by_id, delete_document_by_id"
+
+# Command line
+uvx couchbase-mcp-server --disabled-tools upsert_document_by_id, delete_document_by_id
+```
+
+**File path (one tool name per line):**
+
+```bash
+# Environment variable
+CB_MCP_DISABLED_TOOLS=disabled_tools.txt
+
+# Command line
+uvx couchbase-mcp-server --disabled-tools disabled_tools.txt
+```
+
+**File format (e.g., `disabled_tools.txt`):**
+
+```text
+# Write operations
+upsert_document_by_id
+delete_document_by_id
+
+# Index advisor
+get_index_advisor_recommendations
+```
+
+Lines starting with `#` are treated as comments and ignored.
+
+#### MCP Client Configuration Examples
+
+**Using comma-separated list:**
+
+```json
+{
+  "mcpServers": {
+    "couchbase": {
+      "command": "uvx",
+      "args": ["couchbase-mcp-server"],
+      "env": {
+        "CB_CONNECTION_STRING": "couchbases://connection-string",
+        "CB_USERNAME": "username",
+        "CB_PASSWORD": "password",
+        "CB_MCP_DISABLED_TOOLS": "upsert_document_by_id,delete_document_by_id"
+      }
+    }
+  }
+}
+```
+
+**Using file path (recommended for many tools):**
+
+```json
+{
+  "mcpServers": {
+    "couchbase": {
+      "command": "uvx",
+      "args": ["couchbase-mcp-server"],
+      "env": {
+        "CB_CONNECTION_STRING": "couchbases://connection-string",
+        "CB_USERNAME": "username",
+        "CB_PASSWORD": "password",
+        "CB_MCP_DISABLED_TOOLS": "/path/to/disabled_tools.txt"
+      }
+    }
+  }
+}
+```
+
+#### Important Security Note
+
+> **Warning:** Disabling tools alone does not guarantee that certain operations cannot be performed. The underlying database user's RBAC (Role-Based Access Control) permissions are the authoritative security control.
+>
+> For example, even if you disable `upsert_document_by_id` and `delete_document_by_id`, data modifications can still occur via the `run_sql_plus_plus_query` tool using SQL++ DML statements (INSERT, UPDATE, DELETE, MERGE) unless:
+> - The `CB_MCP_READ_ONLY_MODE` is set to `true` (default), OR
+> - The database user lacks the necessary RBAC permissions for data modification
+>
+> **Best Practice:** Always configure appropriate RBAC permissions on your Couchbase user credentials as the primary security measure. Use tool disabling as an additional layer to guide LLM behavior and reduce the attack surface, not as the sole security control.
+
 You can also check the version of the server using:
 
 ```bash
 uvx couchbase-mcp-server --version
 ```
 
-#### Client Specific Configuration
+### Client Specific Configuration
 
 <details>
 <summary>Claude Desktop</summary>
@@ -259,6 +391,60 @@ For more details about MCP integration with Windsurf Editor, refer to the offici
 
 </details>
 
+<details>
+<summary>VS Code</summary>
+
+Follow the steps below to use the Couchbase MCP server with [VS Code](https://code.visualstudio.com/).
+1. Install [VS Code](https://code.visualstudio.com/)
+2. Following are a couple of ways to configure the MCP server.
+    * For a Workspace server configuration
+      - Create a new file in workspace as .vscode/mcp.json.
+      - Add the [configuration](#configuration) and save the file.
+    * For the Global server configuration:
+      - Run **MCP: Open User Configuration** in the Command Pallete(`Ctrl+Shift+P` or `Cmd+Shift+P`)
+      - Add the [configuration](#configuration) and save the file.
+    * **Note**: VS Code uses `servers` as the top-level JSON property in mcp.json files to define MCP (Model Context Protocol) servers, while Cursor uses `mcpServers` for the equivalent configuration. Check the [VS Code client configurations](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for any further changes or details. An example VS Code configuration is provided below.
+      ```json
+        {
+          "servers": {
+            "couchbase": {
+              "command": "uvx",
+              "args": ["couchbase-mcp-server"],
+              "env": {
+                "CB_CONNECTION_STRING": "couchbases://connection-string",
+                "CB_USERNAME": "username",
+                "CB_PASSWORD": "password"
+              }
+            }
+          }
+        }
+        ```
+3. Once you save the file, the server starts and a small action list appears with `Running|Stop|n Tools|More..`.
+4. Click on the options from the option list to `Start`/`Stop`/manage the server.
+5. You can now use the Couchbase MCP server in VS Code to query your Couchbase cluster using natural language and perform CRUD operations on documents.
+
+Logs:
+In the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`),
+- run **MCP: List Servers** command and pick the couchbase server
+- choose “Show Output” to see its logs in the Output tab.
+</details>
+
+<details>
+<summary>JetBrains IDEs</summary>
+
+Follow the steps below to use the Couchbase MCP server with [JetBrains IDEs](https://www.jetbrains.com/)
+1. Install any one of the [JetBrains IDEs](https://www.jetbrains.com/)
+2. Install any one of the JetBrains plugins - [AI Assistant](https://www.jetbrains.com/help/ai-assistant/getting-started-with-ai-assistant.html) or [Junie](https://www.jetbrains.com/help/junie/get-started-with-junie.html)
+3. Navigate to **Settings > Tools > AI Assistant or Junie > MCP Server**
+4. Click "+" to add the Couchbase MCP [configuration](#configuration) and click Save.
+5. You will see the Couchbase MCP server added to the list of servers. Once you click Apply, the Couchbase MCP server starts and on-hover of status, it shows all the tools available.
+6. You can now use the Couchbase MCP server in JetBrains IDEs to query your Couchbase cluster using natural language and perform CRUD operations on documents.
+
+Logs:
+The log file can be explored at **Help > Show Log in Finder (Explorer) > mcp > couchbase**
+
+</details>
+
 ## Streamable HTTP Transport Mode
 
 The MCP Server can be run in [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) transport mode which allows multiple clients to connect to the same server instance via HTTP.
@@ -275,7 +461,7 @@ uvx couchbase-mcp-server \
   --connection-string='<couchbase_connection_string>' \
   --username='<database_username>' \
   --password='<database_password>' \
-  --read-only-query-mode=true \
+  --read-only-mode=true \
   --transport=http
 ```
 
@@ -308,7 +494,7 @@ uvx couchbase-mcp-server \
   --connection-string='<couchbase_connection_string>' \
   --username='<database_username>' \
   --password='<database_password>' \
-  --read-only-query-mode=true \
+  --read-only-mode=true \
   --transport=sse
 ```
 

couchbase_mcp_server-0.6.0.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=mI5Z_d1VTIdZnFirslUJW3UQnW8Ci-0RFyD90VyHhUg,6828
+tools/__init__.py,sha256=7HNspBZLCpz5WwQkPg7p0irPYyrD3AouDUb6H0uzhvQ,3830
+tools/index.py,sha256=cCBr0ptFBVc-HN5SoCauQAh2DsAP_Is8NPUSa6QcLM0,6682
+tools/kv.py,sha256=ZRb7ixq3zCqiyPwJTtt4plNl9tCC_0kRDDqlUAh_apc,4938
+tools/query.py,sha256=sOmn45nrysKlKavBymLSu-7sbwtFHBo0GwLcV-gmbDg,11552
+tools/server.py,sha256=c5m_6GkwTaRwEelrQE4IHcs2aKZKd_X-BjnseMjkjMo,6734
+utils/__init__.py,sha256=lV5QqPzMlHqInev9Nw_k3ToI9ABEZDfcqvE4p7cPLbU,1415
+utils/config.py,sha256=4jIbE0dYHGidwlZVoLALNMLz_wBQ_J8XX5hvJPpu_BM,2730
+utils/connection.py,sha256=NtAU4pmHMZubSJcs_X_lai9o8dih5mW0RyrRdmyp1Po,2892
+utils/constants.py,sha256=w0zvQ1zMzJBg44Yl3aQW8KfaaRPn0BgPOLEe8xLeLSE,487
+utils/context.py,sha256=q0eCe_I72rAEPWtSnf4qBEv5BuLHnko9qqCs4KTMW6g,2788
+utils/index_utils.py,sha256=W0rvoBXU_2aB9m-HDlLChZoMzvlIX6FUWF6RTsYGfYM,10910
+couchbase_mcp_server-0.6.0.dist-info/METADATA,sha256=3lUXRwa_fmDiXNHDj59oZaFePfsE5SzVFOTeESeJUEA,31086
+couchbase_mcp_server-0.6.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+couchbase_mcp_server-0.6.0.dist-info/entry_points.txt,sha256=iU5pF4kIMTnNhoMPHhdH-k8o1Fmxb_iM9qJHCZcL6Ak,57
+couchbase_mcp_server-0.6.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+couchbase_mcp_server-0.6.0.dist-info/RECORD,,

mcp_server.py

@@ -10,7 +10,7 @@ import click
 from mcp.server.fastmcp import FastMCP
 
 # Import tools
-from tools import ALL_TOOLS
+from tools import get_tools
 
 # Import utilities
 from utils import (
@@ -25,6 +25,7 @@ from utils import (
     NETWORK_TRANSPORTS_SDK_MAPPING,
     AppContext,
     get_settings,
+    parse_disabled_tools,
 )
 
 # Configure logging
@@ -41,14 +42,20 @@ async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
     """Initialize the MCP server context without establishing database connections."""
     # Get configuration from Click context
     settings = get_settings()
+    read_only_mode = settings.get("read_only_mode", True)
     read_only_query_mode = settings.get("read_only_query_mode", True)
 
     # Note: We don't validate configuration here to allow tool discovery
     # Configuration will be validated when tools are actually used
-    logger.info("MCP server initialized in lazy mode for tool discovery.")
+    logger.info(
+        f"MCP server initialized in lazy mode for tool discovery. "
+        f"Modes: (read_only_mode={read_only_mode}, read_only_query_mode={read_only_query_mode})"
+    )
     app_context = None
     try:
-        app_context = AppContext(read_only_query_mode=read_only_query_mode)
+        app_context = AppContext(
+            read_only_mode=read_only_mode, read_only_query_mode=read_only_query_mode
+        )
         yield app_context
 
     except Exception as e:
@@ -95,6 +102,13 @@ async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
     default=None,
     help="Path to the client certificate key file used for mTLS authentication.",
 )
+@click.option(
+    "--read-only-mode",
+    envvar="CB_MCP_READ_ONLY_MODE",
+    type=bool,
+    default=DEFAULT_READ_ONLY_MODE,
+    help="Enable read-only mode. When True (default), all write operations (KV and Query) are disabled and KV write tools are not loaded. Set to False to enable write operations.",
+)
 @click.option(
     "--read-only-query-mode",
     envvar=[
@@ -102,8 +116,9 @@ async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
         "READ_ONLY_QUERY_MODE",  # Deprecated
     ],
     type=bool,
+    deprecated=True,
     default=DEFAULT_READ_ONLY_MODE,
-    help="Enable read-only query mode. Set to True (default) to allow only read-only queries. Can be set to False to allow data modification queries.",
+    help="[DEPRECATED: Use --read-only-mode instead] Enable read-only query mode. Set to True (default) to allow only read-only queries. Can be set to False to allow data modification queries.",
 )
 @click.option(
     "--transport",
@@ -127,6 +142,13 @@ async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
     default=DEFAULT_PORT,
     help="Port to run the server on (default: 8000)",
 )
+@click.option(
+    "--disabled-tools",
+    "disabled_tools",
+    envvar="CB_MCP_DISABLED_TOOLS",
+    help="Tools to disable. Accepts comma-separated tool names (e.g., 'tool_1,tool_2') "
+    "or a file path containing one tool name per line.",
+)
 @click.version_option(package_name="couchbase-mcp-server")
 @click.pass_context
 def main(
@@ -137,10 +159,12 @@ def main(
     ca_cert_path,
     client_cert_path,
     client_key_path,
+    read_only_mode,
     read_only_query_mode,
     transport,
     host,
     port,
+    disabled_tools,
 ):
     """Couchbase MCP Server"""
     # Store configuration in context
@@ -151,12 +175,29 @@ def main(
         "ca_cert_path": ca_cert_path,
         "client_cert_path": client_cert_path,
         "client_key_path": client_key_path,
+        "read_only_mode": read_only_mode,
         "read_only_query_mode": read_only_query_mode,
         "transport": transport,
         "host": host,
         "port": port,
     }
 
+    # Get tools based on mode settings
+    # When read_only_mode is True, KV write tools are not loaded
+    tools = get_tools(read_only_mode=read_only_mode)
+
+    # Parse and validate disabled tools from CLI/environment variable
+    all_tool_names = {tool.__name__ for tool in tools}
+    disabled_tool_names = parse_disabled_tools(disabled_tools, all_tool_names)
+
+    if disabled_tool_names:
+        logger.info(
+            f"Disabled {len(disabled_tool_names)} tool(s): {sorted(disabled_tool_names)}"
+        )
+
+    # Filter out disabled tools
+    enabled_tools = [tool for tool in tools if tool.__name__ not in disabled_tool_names]
+
     # Map user-friendly transport names to SDK transport names
     sdk_transport = NETWORK_TRANSPORTS_SDK_MAPPING.get(transport, transport)
 
@@ -172,10 +213,17 @@ def main(
 
     mcp = FastMCP(MCP_SERVER_NAME, lifespan=app_lifespan, **config)
 
-    # Register all tools
-    for tool in ALL_TOOLS:
+    logger.info(
+        f"Registering {len(enabled_tools)} tool(s) with modes (read_only_mode={read_only_mode}, "
+        f"read_only_query_mode={read_only_query_mode})"
+    )
+
+    # Register only enabled tools
+    for tool in enabled_tools:
         mcp.add_tool(tool)
 
+    logger.info(f"Registered {len(enabled_tools)} tool(s)")
+
     # Run the server
     mcp.run(transport=sdk_transport)  # type: ignore
 

tools/__init__.py

@@ -2,8 +2,14 @@
 Couchbase MCP Tools
 
 This module contains all the MCP tools for Couchbase operations.
+
+Tool Categories:
+- READ_ONLY_TOOLS: Tools that only read data (always available)
+- KV_WRITE_TOOLS: KV tools that modify data (disabled when READ_ONLY_MODE=True)
 """
 
+from collections.abc import Callable
+
 # Index tools
 from .index import get_index_advisor_recommendations, list_indexes
 
@@ -11,6 +17,8 @@ from .index import get_index_advisor_recommendations, list_indexes
 from .kv import (
     delete_document_by_id,
     get_document_by_id,
+    insert_document_by_id,
+    replace_document_by_id,
     upsert_document_by_id,
 )
 
@@ -38,22 +46,25 @@ from .server import (
     test_cluster_connection,
 )
 
-# List of all tools for easy registration
-ALL_TOOLS = [
+# Read-only tools - always available regardless of mode settings
+READ_ONLY_TOOLS = [
+    # Server/Cluster management 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_cluster_health_and_services,
+    # KV read tool
     get_document_by_id,
-    upsert_document_by_id,
-    delete_document_by_id,
+    # Query tools (read operations)
     get_schema_for_collection,
-    run_sql_plus_plus_query,
+    run_sql_plus_plus_query,  # Write protection handled at runtime via read_only_query_mode
+    # Index tools
     get_index_advisor_recommendations,
     list_indexes,
-    get_cluster_health_and_services,
+    # Query performance analysis tools
     get_queries_not_selective,
     get_queries_not_using_covering_index,
     get_queries_using_primary_index,
@@ -63,6 +74,33 @@ ALL_TOOLS = [
     get_most_frequent_queries,
 ]
 
+# KV write tools - disabled when READ_ONLY_MODE is True
+KV_WRITE_TOOLS = [
+    upsert_document_by_id,
+    insert_document_by_id,
+    replace_document_by_id,
+    delete_document_by_id,
+]
+
+# List of all tools for easy registration (kept for backward compatibility)
+ALL_TOOLS = READ_ONLY_TOOLS + KV_WRITE_TOOLS
+
+
+def get_tools(read_only_mode: bool = True) -> list[Callable]:
+    """Get the list of tools based on the mode settings.
+
+    This function determines which tools should be loaded based on the
+    READ_ONLY_MODE setting. When read_only_mode is True, write tools are excluded.
+    """
+    tools = list(READ_ONLY_TOOLS)
+
+    if not read_only_mode:
+        # KV write tools are only loaded when READ_ONLY_MODE is False
+        tools.extend(KV_WRITE_TOOLS)
+
+    return tools
+
+
 __all__ = [
     # Individual tools
     "get_server_configuration_status",
@@ -73,6 +111,8 @@ __all__ = [
     "get_buckets_in_cluster",
     "get_document_by_id",
     "upsert_document_by_id",
+    "insert_document_by_id",
+    "replace_document_by_id",
     "delete_document_by_id",
     "get_schema_for_collection",
     "run_sql_plus_plus_query",
@@ -86,6 +126,10 @@ __all__ = [
     "get_queries_with_largest_response_sizes",
     "get_longest_running_queries",
     "get_most_frequent_queries",
+    # Tool categories
+    "READ_ONLY_TOOLS",
+    "KV_WRITE_TOOLS",
     # Convenience
     "ALL_TOOLS",
+    "get_tools",
 ]

tools/kv.py

@@ -1,7 +1,12 @@
 """
 Tools for key-value operations.
 
-This module contains tools for getting a document by its ID, upserting a document by its ID, and deleting a document by its ID.
+This module contains tools for document operations by ID:
+- get: Retrieve a document
+- upsert: Insert or update a document (creates if not exists, updates if exists)
+- insert: Create a document only if it does NOT exist (fails if exists)
+- replace: Update a document only if it exists (fails if missing)
+- delete: Remove a document
 """
 
 import logging
@@ -46,6 +51,12 @@ def upsert_document_by_id(
     document_content: dict[str, Any],
 ) -> bool:
     """Insert or update a document by its ID.
+
+    IMPORTANT: Only use this tool when the user explicitly requests an 'upsert' operation
+    or explicitly states they want to 'insert or update' a document.
+
+    DO NOT use this as a fallback when insert_document_by_id or replace_document_by_id fails.
+
     Returns True on success, False on failure."""
     cluster = get_cluster_connection(ctx)
     bucket = connect_to_bucket(cluster, bucket_name)
@@ -78,3 +89,55 @@ def delete_document_by_id(
     except Exception as e:
         logger.error(f"Error deleting document {document_id}: {e}")
         return False
+
+
+def insert_document_by_id(
+    ctx: Context,
+    bucket_name: str,
+    scope_name: str,
+    collection_name: str,
+    document_id: str,
+    document_content: dict[str, Any],
+) -> bool:
+    """Insert a new document by its ID. This operation will FAIL if the document already exists.
+
+    IMPORTANT: If this operation fails, DO NOT automatically try replace or upsert.
+    Report the failure to the user. They can choose to 'replace' or 'upsert' if desired.
+
+    Returns True on success, False on failure (including if document already exists)."""
+    cluster = get_cluster_connection(ctx)
+    bucket = connect_to_bucket(cluster, bucket_name)
+    try:
+        collection = bucket.scope(scope_name).collection(collection_name)
+        collection.insert(document_id, document_content)
+        logger.info(f"Successfully inserted document {document_id}")
+        return True
+    except Exception as e:
+        logger.error(f"Error inserting document {document_id}: {e}")
+        return False
+
+
+def replace_document_by_id(
+    ctx: Context,
+    bucket_name: str,
+    scope_name: str,
+    collection_name: str,
+    document_id: str,
+    document_content: dict[str, Any],
+) -> bool:
+    """Replace an existing document by its ID. This operation will FAIL if the document does not exist.
+
+    IMPORTANT: If this operation fails, DO NOT automatically try insert or upsert.
+    Report the failure to the user. They can choose to 'insert' or 'upsert' if desired.
+
+    Returns True on success, False on failure (including if document does not exist)."""
+    cluster = get_cluster_connection(ctx)
+    bucket = connect_to_bucket(cluster, bucket_name)
+    try:
+        collection = bucket.scope(scope_name).collection(collection_name)
+        collection.replace(document_id, document_content)
+        logger.info(f"Successfully replaced document {document_id}")
+        return True
+    except Exception as e:
+        logger.error(f"Error replacing document {document_id}: {e}")
+        return False

tools/query.py

@@ -53,15 +53,20 @@ def run_sql_plus_plus_query(
     bucket = connect_to_bucket(cluster, bucket_name)
 
     app_context = ctx.request_context.lifespan_context
+    read_only_mode = app_context.read_only_mode
     read_only_query_mode = app_context.read_only_query_mode
-    logger.info(f"Running SQL++ queries in read-only mode: {read_only_query_mode}")
+
+    # Block query writes if either read_only_mode OR read_only_query_mode is True
+    # READ_ONLY_MODE takes precedence and blocks all writes (KV and Query)
+    # READ_ONLY_QUERY_MODE (deprecated) only blocks query writes
+    block_query_writes = read_only_mode or read_only_query_mode
 
     try:
         scope = bucket.scope(scope_name)
 
         results = []
         # If read-only mode is enabled, check if the query is a data or structure modification query
-        if read_only_query_mode:
+        if block_query_writes:
             parsed_query = parse_sqlpp(query)
             data_modification_query = modifies_data(parsed_query)
             structure_modification_query = modifies_structure(parsed_query)

tools/server.py

@@ -29,6 +29,7 @@ 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"),
+        "read_only_mode": settings.get("read_only_mode", True),
         "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")),

utils/__init__.py

@@ -7,6 +7,7 @@ This module contains utility functions for configuration, connection, and contex
 # Configuration utilities
 from .config import (
     get_settings,
+    parse_disabled_tools,
 )
 
 # Connection utilities
@@ -45,6 +46,7 @@ from .index_utils import (
 __all__ = [
     # Config
     "get_settings",
+    "parse_disabled_tools",
     # Connection
     "connect_to_couchbase_cluster",
     "connect_to_bucket",

utils/config.py

@@ -1,4 +1,5 @@
 import logging
+from pathlib import Path
 
 import click
 
@@ -11,3 +12,78 @@ def get_settings() -> dict:
     """Get settings from Click context."""
     ctx = click.get_current_context()
     return ctx.obj or {}
+
+
+def _parse_file(file_path: Path, valid_tool_names: set[str]) -> set[str]:
+    """Parse tool names from a file (one tool per line)."""
+    tools: set[str] = set()
+    invalid_count = 0
+    try:
+        with open(file_path) as f:
+            for raw_line in f:
+                name = raw_line.strip()
+                if not name or name.startswith("#"):
+                    continue
+                if name in valid_tool_names:
+                    tools.add(name)
+                else:
+                    invalid_count += 1
+        if invalid_count > 0:
+            logger.warning(
+                f"Ignored {invalid_count} invalid tool name(s) from file: {file_path}"
+            )
+        logger.debug(f"Loaded {len(tools)} disabled tools from file: {file_path}")
+    except OSError as e:
+        logger.warning(f"Failed to read disabled tools file {file_path}: {e}")
+    return tools
+
+
+def _parse_comma_separated(value: str, valid_tool_names: set[str]) -> set[str]:
+    """Parse comma-separated tool names."""
+    tools: set[str] = set()
+    invalid_count = 0
+    for part in value.split(","):
+        name = part.strip()
+        if name:
+            if name in valid_tool_names:
+                tools.add(name)
+            else:
+                invalid_count += 1
+    if invalid_count > 0:
+        logger.warning(
+            f"Ignored {invalid_count} invalid tool name(s) from comma-separated input"
+        )
+    logger.debug(f"Parsed disabled tools from comma-separated string: {tools}")
+    return tools
+
+
+def parse_disabled_tools(
+    disabled_tools_input: str | None,
+    valid_tool_names: set[str],
+) -> set[str]:
+    """
+    Parse disabled tools from CLI argument or environment variable.
+
+    Supported formats:
+    1. Comma-separated string: "tool_1,tool_2"
+    2. File path containing one tool name per line: "disabled_tools.txt"
+
+    Args:
+        disabled_tools_input: Comma-separated tools or file path
+        valid_tool_names: Set of valid tool names to validate against
+
+    Returns:
+        Set of tool names to disable
+    """
+    if not disabled_tools_input:
+        return set()
+
+    value = disabled_tools_input.strip()
+
+    # Check if it's a file path
+    potential_path = Path(value)
+    if potential_path.exists() and potential_path.is_file():
+        return _parse_file(potential_path, valid_tool_names)
+
+    # Otherwise, treat as comma-separated
+    return _parse_comma_separated(value, valid_tool_names)

utils/context.py

@@ -13,9 +13,19 @@ logger = logging.getLogger(f"{MCP_SERVER_NAME}.utils.context")
 
 @dataclass
 class AppContext:
-    """Context for the MCP server."""
+    """Context for the MCP server.
+
+    Attributes:
+        cluster: The Couchbase cluster connection (lazily initialized).
+        read_only_mode: When True, all write operations (KV and Query) are disabled
+                       and KV write tools are not loaded.
+                       This is the recommended mode for safety. Default is True.
+        read_only_query_mode: When True, query-based write operations are disabled.
+                             DEPRECATED: Use read_only_mode instead.
+    """
 
     cluster: Cluster | None = None
+    read_only_mode: bool = True
     read_only_query_mode: bool = True
 
 

couchbase_mcp_server-0.5.3.dist-info/RECORD

@@ -1,19 +0,0 @@
-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=72DlDEv1j_IpZTp9rL1fA5QGFXp5eburCDObGqpPuFc,2462
-tools/index.py,sha256=cCBr0ptFBVc-HN5SoCauQAh2DsAP_Is8NPUSa6QcLM0,6682
-tools/kv.py,sha256=NGUs43iuXElj9rYe4RCyCStqoh5y1fUgbg1oWuU4WeQ,2493
-tools/query.py,sha256=5fYrMm6ReXuDn7uu1QdVxoCtUnaqaIFPcAWBNhiTa4Y,11303
-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.3.dist-info/METADATA,sha256=-UqmmCTDyeujZ_sDWuPEsngT0ufZ4iAJaQUiPBjD3ls,22182
-couchbase_mcp_server-0.5.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-couchbase_mcp_server-0.5.3.dist-info/entry_points.txt,sha256=iU5pF4kIMTnNhoMPHhdH-k8o1Fmxb_iM9qJHCZcL6Ak,57
-couchbase_mcp_server-0.5.3.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-couchbase_mcp_server-0.5.3.dist-info/RECORD,,