couchbase-mcp-server 0.5.2rc6__py3-none-any.whl → 0.5.3__py3-none-any.whl

{couchbase_mcp_server-0.5.2rc6.dist-info → couchbase_mcp_server-0.5.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: couchbase-mcp-server
-Version: 0.5.2rc6
+Version: 0.5.3
 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
@@ -19,6 +19,8 @@ Requires-Dist: mcp[cli]<2.0.0,>=1.20.0
 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==8.3.3; extra == 'dev'
 Requires-Dist: ruff==0.12.5; extra == 'dev'
 Description-Content-Type: text/markdown
 
@@ -45,12 +47,21 @@ An [MCP](https://modelcontextprotocol.io/) server implementation of Couchbase th
 - 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)
 
 ## Prerequisites
 
@@ -433,6 +444,21 @@ The Couchbase MCP server can also be used as a managed server in your agentic ap
 - 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).
 
+## Integration testing
+
+We provide high-level MCP integration tests to verify that the server exposes the expected tools and that they can be invoked against a demo Couchbase cluster.
+
+1. Export demo cluster credentials:
+   - `CB_CONNECTION_STRING`
+   - `CB_USERNAME`
+   - `CB_PASSWORD`
+   - Optional: `CB_MCP_TEST_BUCKET` (a bucket to probe during the tests)
+2. Run the tests:
+
+```bash
+uv run pytest tests/ -v
+```
+
 ---
 
 ## 👩‍💻 Contributing

{couchbase_mcp_server-0.5.2rc6.dist-info → couchbase_mcp_server-0.5.3.dist-info}/RECORD

@@ -1,10 +1,10 @@
 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/__init__.py,sha256=72DlDEv1j_IpZTp9rL1fA5QGFXp5eburCDObGqpPuFc,2462
 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/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
@@ -12,8 +12,8 @@ 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.2rc6.dist-info/METADATA,sha256=0WxUrZ50H8QFsVtw2Zy9Xp-rDvB34zVzvL3wxnai_0Q,21038
-couchbase_mcp_server-0.5.2rc6.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-couchbase_mcp_server-0.5.2rc6.dist-info/entry_points.txt,sha256=iU5pF4kIMTnNhoMPHhdH-k8o1Fmxb_iM9qJHCZcL6Ak,57
-couchbase_mcp_server-0.5.2rc6.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-couchbase_mcp_server-0.5.2rc6.dist-info/RECORD,,
+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,,

{couchbase_mcp_server-0.5.2rc6.dist-info → couchbase_mcp_server-0.5.3.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any

tools/__init__.py

@@ -16,6 +16,13 @@ from .kv import (
 
 # Query tools
 from .query import (
+    get_longest_running_queries,
+    get_most_frequent_queries,
+    get_queries_not_selective,
+    get_queries_not_using_covering_index,
+    get_queries_using_primary_index,
+    get_queries_with_large_result_count,
+    get_queries_with_largest_response_sizes,
     get_schema_for_collection,
     run_sql_plus_plus_query,
 )
@@ -47,6 +54,13 @@ ALL_TOOLS = [
     get_index_advisor_recommendations,
     list_indexes,
     get_cluster_health_and_services,
+    get_queries_not_selective,
+    get_queries_not_using_covering_index,
+    get_queries_using_primary_index,
+    get_queries_with_large_result_count,
+    get_queries_with_largest_response_sizes,
+    get_longest_running_queries,
+    get_most_frequent_queries,
 ]
 
 __all__ = [
@@ -65,6 +79,13 @@ __all__ = [
     "get_index_advisor_recommendations",
     "list_indexes",
     "get_cluster_health_and_services",
+    "get_queries_not_selective",
+    "get_queries_not_using_covering_index",
+    "get_queries_using_primary_index",
+    "get_queries_with_large_result_count",
+    "get_queries_with_largest_response_sizes",
+    "get_longest_running_queries",
+    "get_most_frequent_queries",
     # Convenience
     "ALL_TOOLS",
 ]

tools/query.py

@@ -39,7 +39,15 @@ def get_schema_for_collection(
 def run_sql_plus_plus_query(
     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."""
+    """Run a SQL++ query on a scope and return the results as a list of JSON objects.
+
+    The query will be run on the specified scope in the specified bucket.
+    The query should use collection names directly without bucket/scope prefixes, as the scope context is automatically set.
+
+    Example:
+        query = "SELECT * FROM users WHERE age > 18"
+        # Incorrect: "SELECT * FROM bucket.scope.users WHERE age > 18"
+    """
     cluster = get_cluster_connection(ctx)
 
     bucket = connect_to_bucket(cluster, bucket_name)
@@ -81,7 +89,6 @@ def run_sql_plus_plus_query(
         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."""
 
@@ -96,3 +103,258 @@ def run_cluster_query(ctx: Context, query: str, **kwargs: Any) -> list[dict[str,
     except Exception as e:
         logger.error(f"Error running query: {e}")
         raise
+
+
+def _run_query_tool_with_empty_message(
+    ctx: Context,
+    query: str,
+    *,
+    limit: int,
+    empty_message: str,
+    extra_payload: dict[str, Any] | None = None,
+    **query_kwargs: Any,
+) -> list[dict[str, Any]]:
+    """Execute a cluster query with a consistent empty-result response."""
+    results = run_cluster_query(ctx, query, limit=limit, **query_kwargs)
+
+    if results:
+        return results
+
+    payload: dict[str, Any] = {"message": empty_message, "results": []}
+    if extra_payload:
+        payload.update(extra_payload)
+    return [payload]
+
+
+def get_longest_running_queries(ctx: Context, limit: int = 10) -> list[dict[str, Any]]:
+    """Get the N longest running queries from the system:completed_requests catalog.
+
+    Args:
+        limit: Number of queries to return (default: 10)
+
+    Returns:
+        List of queries with their average service time and count
+    """
+    query = """
+    SELECT statement,
+        DURATION_TO_STR(avgServiceTime) AS avgServiceTime,
+        COUNT(1) AS queries
+    FROM system:completed_requests
+    WHERE UPPER(statement) NOT LIKE 'INFER %'
+        AND UPPER(statement) NOT LIKE 'CREATE INDEX%'
+        AND UPPER(statement) NOT LIKE 'CREATE PRIMARY INDEX%'
+        AND UPPER(statement) NOT LIKE '% SYSTEM:%'
+    GROUP BY statement
+    LETTING avgServiceTime = AVG(STR_TO_DURATION(serviceTime))
+    ORDER BY avgServiceTime DESC
+    LIMIT $limit
+    """
+
+    return _run_query_tool_with_empty_message(
+        ctx,
+        query,
+        limit=limit,
+        empty_message=(
+            "No completed queries were available to calculate longest running queries."
+        ),
+    )
+
+
+def get_most_frequent_queries(ctx: Context, limit: int = 10) -> list[dict[str, Any]]:
+    """Get the N most frequent queries from the system:completed_requests catalog.
+
+    Args:
+        limit: Number of queries to return (default: 10)
+
+    Returns:
+        List of queries with their frequency count
+    """
+    query = """
+    SELECT statement,
+        COUNT(1) AS queries
+    FROM system:completed_requests
+    WHERE UPPER(statement) NOT LIKE 'INFER %'
+        AND UPPER(statement) NOT LIKE 'CREATE INDEX%'
+        AND UPPER(statement) NOT LIKE 'CREATE PRIMARY INDEX%'
+        AND UPPER(statement) NOT LIKE 'EXPLAIN %'
+        AND UPPER(statement) NOT LIKE 'ADVISE %'
+        AND UPPER(statement) NOT LIKE '% SYSTEM:%'
+    GROUP BY statement
+    LETTING queries = COUNT(1)
+    ORDER BY queries DESC
+    LIMIT $limit
+    """
+
+    return _run_query_tool_with_empty_message(
+        ctx,
+        query,
+        limit=limit,
+        empty_message=(
+            "No completed queries were available to calculate most frequent queries."
+        ),
+    )
+
+
+def get_queries_with_largest_response_sizes(
+    ctx: Context, limit: int = 10
+) -> list[dict[str, Any]]:
+    """Get queries with the largest response sizes from the system:completed_requests catalog.
+
+    Args:
+        limit: Number of queries to return (default: 10)
+
+    Returns:
+        List of queries with their average result size in bytes, KB, and MB
+    """
+    query = """
+    SELECT statement,
+        avgResultSize AS avgResultSizeBytes,
+        (avgResultSize / 1000) AS avgResultSizeKB,
+        (avgResultSize / 1000000) AS avgResultSizeMB,
+        COUNT(1) AS queries
+    FROM system:completed_requests
+    WHERE UPPER(statement) NOT LIKE 'INFER %'
+        AND UPPER(statement) NOT LIKE 'CREATE INDEX%'
+        AND UPPER(statement) NOT LIKE 'CREATE PRIMARY INDEX%'
+        AND UPPER(statement) NOT LIKE '% SYSTEM:%'
+    GROUP BY statement
+    LETTING avgResultSize = AVG(resultSize)
+    ORDER BY avgResultSize DESC
+    LIMIT $limit
+    """
+
+    return _run_query_tool_with_empty_message(
+        ctx,
+        query,
+        limit=limit,
+        empty_message=(
+            "No completed queries were available to calculate response sizes."
+        ),
+    )
+
+
+def get_queries_with_large_result_count(
+    ctx: Context, limit: int = 10
+) -> list[dict[str, Any]]:
+    """Get queries with the largest result counts from the system:completed_requests catalog.
+
+    Args:
+        limit: Number of queries to return (default: 10)
+
+    Returns:
+        List of queries with their average result count
+    """
+    query = """
+    SELECT statement,
+        avgResultCount,
+        COUNT(1) AS queries
+    FROM system:completed_requests
+    WHERE UPPER(statement) NOT LIKE 'INFER %' AND
+        UPPER(statement) NOT LIKE 'CREATE INDEX%' AND
+        UPPER(statement) NOT LIKE 'CREATE PRIMARY INDEX%' AND
+        UPPER(statement) NOT LIKE '% SYSTEM:%'
+    GROUP BY statement
+    LETTING avgResultCount = AVG(resultCount)
+    ORDER BY avgResultCount DESC
+    LIMIT $limit
+    """
+
+    return _run_query_tool_with_empty_message(
+        ctx,
+        query,
+        limit=limit,
+        empty_message=(
+            "No completed queries were available to calculate result counts."
+        ),
+    )
+
+
+def get_queries_using_primary_index(
+    ctx: Context, limit: int = 10
+) -> list[dict[str, Any]]:
+    """Get queries that use a primary index from the system:completed_requests catalog.
+
+    Args:
+        limit: Number of queries to return (default: 10)
+
+    Returns:
+        List of queries that use primary indexes, ordered by result count
+    """
+    query = """
+    SELECT *
+    FROM system:completed_requests
+    WHERE phaseCounts.`primaryScan` IS NOT MISSING
+        AND UPPER(statement) NOT LIKE '% SYSTEM:%'
+    ORDER BY resultCount DESC
+    LIMIT $limit
+    """
+
+    return _run_query_tool_with_empty_message(
+        ctx,
+        query,
+        limit=limit,
+        empty_message=(
+            "No queries using the primary index were found in system:completed_requests."
+        ),
+    )
+
+
+def get_queries_not_using_covering_index(
+    ctx: Context, limit: int = 10
+) -> list[dict[str, Any]]:
+    """Get queries that don't use a covering index from the system:completed_requests catalog.
+
+    Args:
+        limit: Number of queries to return (default: 10)
+
+    Returns:
+        List of queries that perform index scans but also require fetches (not covering)
+    """
+    query = """
+    SELECT *
+    FROM system:completed_requests
+    WHERE phaseCounts.`indexScan` IS NOT MISSING
+        AND phaseCounts.`fetch` IS NOT MISSING
+        AND UPPER(statement) NOT LIKE '% SYSTEM:%'
+    ORDER BY resultCount DESC
+    LIMIT $limit
+    """
+
+    return _run_query_tool_with_empty_message(
+        ctx,
+        query,
+        limit=limit,
+        empty_message=(
+            "No queries that require fetches after index scans were found "
+            "in system:completed_requests."
+        ),
+    )
+
+
+def get_queries_not_selective(ctx: Context, limit: int = 10) -> list[dict[str, Any]]:
+    """Get queries that are not very selective from the system:completed_requests catalog.
+
+    Args:
+        limit: Number of queries to return (default: 10)
+
+    Returns:
+        List of queries where index scans return significantly more documents than the final result
+    """
+    query = """
+    SELECT statement,
+       AVG(phaseCounts.`indexScan` - resultCount) AS diff
+    FROM system:completed_requests
+    WHERE phaseCounts.`indexScan` > resultCount
+    GROUP BY statement
+    ORDER BY diff DESC
+    LIMIT $limit
+    """
+
+    return _run_query_tool_with_empty_message(
+        ctx,
+        query,
+        limit=limit,
+        empty_message=(
+            "No non-selective queries were found in system:completed_requests."
+        ),
+    )