couchbase-mcp-server 0.5.2rc6__tar.gz → 0.6.0__tar.gz

couchbase_mcp_server-0.6.0/.github/workflows/test.yml

@@ -0,0 +1,297 @@
+name: Tests
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  # Default test credentials for Couchbase
+  CB_USERNAME: Administrator
+  CB_PASSWORD: password
+  CB_MCP_TEST_BUCKET: travel-sample
+
+jobs:
+  # ============================================
+  # Integration Tests - All Transport Modes
+  # ============================================
+  integration-tests:
+    name: Integration (${{ matrix.transport }} transport)
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        transport: ["stdio", "http", "sse"]
+
+    services:
+      couchbase:
+        image: couchbase:enterprise-8.0.0
+        ports:
+          - 8091:8091
+          - 8092:8092
+          - 8093:8093
+          - 8094:8094
+          - 8095:8095
+          - 8096:8096
+          - 9102:9102
+          - 11210:11210
+          - 11207:11207
+        options: >-
+          --health-cmd "curl -s http://localhost:8091/pools || exit 1"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 30
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python (latest)
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Wait for Couchbase to be ready
+        run: |
+          echo "Waiting for Couchbase to be fully ready..."
+          for i in {1..60}; do
+            if curl -s http://localhost:8091/pools > /dev/null 2>&1; then
+              echo "Couchbase REST API is responding"
+              break
+            fi
+            echo "Waiting for Couchbase... ($i/60)"
+            sleep 2
+          done
+
+      - name: Initialize Couchbase cluster
+        run: |
+          echo "Initializing Couchbase cluster..."
+
+          # Initialize node
+          curl -s -X POST http://localhost:8091/nodes/self/controller/settings \
+            -d 'path=/opt/couchbase/var/lib/couchbase/data' \
+            -d 'index_path=/opt/couchbase/var/lib/couchbase/data'
+
+          # Set up services
+          curl -s -X POST http://localhost:8091/node/controller/setupServices \
+            -d 'services=kv,n1ql,index,fts'
+
+          # Set memory quotas
+          curl -s -X POST http://localhost:8091/pools/default \
+            -d 'memoryQuota=512' \
+            -d 'indexMemoryQuota=256' \
+            -d 'ftsMemoryQuota=256'
+
+          # Set credentials
+          curl -s -X POST http://localhost:8091/settings/web \
+            -d "password=${{ env.CB_PASSWORD }}" \
+            -d "username=${{ env.CB_USERNAME }}" \
+            -d 'port=SAME'
+
+          echo "Cluster initialization complete"
+
+      - name: Load travel-sample bucket
+        run: |
+          echo "Loading travel-sample bucket..."
+
+          # Wait for cluster to be fully initialized
+          sleep 5
+
+          # Load the travel-sample sample bucket (includes inventory scope with airline, route, hotel, airport collections)
+          curl -s -X POST http://localhost:8091/sampleBuckets/install \
+            -u "${{ env.CB_USERNAME }}:${{ env.CB_PASSWORD }}" \
+            -H "Content-Type: application/json" \
+            -d '["travel-sample"]'
+
+          # Wait for bucket to be ready (sample buckets take longer to load)
+          echo "Waiting for travel-sample bucket to be ready..."
+          for i in {1..60}; do
+            if curl -s -u "${{ env.CB_USERNAME }}:${{ env.CB_PASSWORD }}" \
+               http://localhost:8091/pools/default/buckets/travel-sample 2>/dev/null | grep -q '"status":"healthy"'; then
+              echo "Bucket is healthy"
+              break
+            fi
+            echo "Waiting for bucket... ($i/60)"
+            sleep 3
+          done
+
+          # Additional wait for data to be fully loaded
+          echo "Waiting for sample data to be fully loaded..."
+          sleep 10
+
+      - name: Set indexer storage mode
+        run: |
+          echo "Setting indexer storage mode..."
+          # Wait for indexer service to be ready
+          sleep 5
+          # Set storage mode to plasma (Couchbase 7.1+)
+          # Use cluster settings API which is more reliable
+          curl -s -X POST http://localhost:8091/settings/indexes \
+            -u "${{ env.CB_USERNAME }}:${{ env.CB_PASSWORD }}" \
+            -d 'storageMode=plasma' \
+            || echo "Storage mode may already be set or indexer not ready"
+          # Wait for storage mode to be applied
+          echo "Waiting for storage mode to be applied..."
+          sleep 5
+
+      - name: Setup test data (indexes and queries)
+        env:
+          CB_CONNECTION_STRING: couchbase://localhost
+          CB_USERNAME: ${{ env.CB_USERNAME }}
+          CB_PASSWORD: ${{ env.CB_PASSWORD }}
+          CB_MCP_TEST_BUCKET: ${{ env.CB_MCP_TEST_BUCKET }}
+          PYTHONPATH: src
+        run: |
+          echo "Running setup_test_data.py to create indexes and populate test data..."
+          uv run python scripts/setup_test_data.py
+
+      # ============================================
+      # STDIO Transport Tests
+      # ============================================
+      - name: Run STDIO integration tests
+        if: matrix.transport == 'stdio'
+        env:
+          CB_CONNECTION_STRING: couchbase://localhost
+          CB_MCP_TRANSPORT: stdio
+          CB_MCP_TEST_SCOPE: inventory
+          CB_MCP_TEST_COLLECTION: airline
+          PYTHONPATH: src
+        run: |
+          echo "Running tests with STDIO transport..."
+          uv run pytest tests/ -v --tb=short
+
+      # ============================================
+      # HTTP Transport Tests
+      # ============================================
+      - name: Start MCP server (HTTP)
+        if: matrix.transport == 'http'
+        env:
+          CB_CONNECTION_STRING: couchbase://localhost
+          CB_MCP_TRANSPORT: http
+          CB_MCP_HOST: 127.0.0.1
+          CB_MCP_PORT: 8000
+          PYTHONPATH: src
+        run: |
+          echo "Starting MCP server with HTTP transport..."
+          uv run python -m mcp_server &
+          SERVER_PID=$!
+          echo "SERVER_PID=$SERVER_PID" >> $GITHUB_ENV
+
+          # Wait for server to be ready (check if port is listening)
+          echo "Waiting for HTTP server to be ready..."
+          for i in {1..30}; do
+            if nc -z 127.0.0.1 8000 2>/dev/null; then
+              echo "HTTP server is ready"
+              break
+            fi
+            echo "Waiting for HTTP server... ($i/30)"
+            sleep 1
+          done
+
+      - name: Run HTTP transport tests
+        if: matrix.transport == 'http'
+        env:
+          CB_CONNECTION_STRING: couchbase://localhost
+          CB_MCP_TRANSPORT: http
+          CB_MCP_HOST: 127.0.0.1
+          CB_MCP_PORT: 8000
+          MCP_SERVER_URL: http://127.0.0.1:8000/mcp
+          CB_MCP_TEST_SCOPE: inventory
+          CB_MCP_TEST_COLLECTION: airline
+          PYTHONPATH: src
+        run: |
+          echo "Running tests with HTTP transport..."
+          uv run pytest tests/ -v --tb=short
+
+      - name: Stop HTTP server
+        if: matrix.transport == 'http' && always()
+        run: |
+          if [ -n "$SERVER_PID" ]; then
+            kill $SERVER_PID 2>/dev/null || true
+          fi
+
+      # ============================================
+      # SSE Transport Tests
+      # ============================================
+      - name: Start MCP server (SSE)
+        if: matrix.transport == 'sse'
+        env:
+          CB_CONNECTION_STRING: couchbase://localhost
+          CB_MCP_TRANSPORT: sse
+          CB_MCP_HOST: 127.0.0.1
+          CB_MCP_PORT: 8000
+          PYTHONPATH: src
+        run: |
+          echo "Starting MCP server with SSE transport..."
+          uv run python -m mcp_server &
+          SERVER_PID=$!
+          echo "SERVER_PID=$SERVER_PID" >> $GITHUB_ENV
+
+          # Wait for server to be ready (check if port is listening)
+          echo "Waiting for SSE server to be ready..."
+          for i in {1..30}; do
+            if nc -z 127.0.0.1 8000 2>/dev/null; then
+              echo "SSE server is ready"
+              break
+            fi
+            echo "Waiting for SSE server... ($i/30)"
+            sleep 1
+          done
+
+      - name: Run SSE transport tests
+        if: matrix.transport == 'sse'
+        env:
+          CB_CONNECTION_STRING: couchbase://localhost
+          CB_MCP_TRANSPORT: sse
+          CB_MCP_HOST: 127.0.0.1
+          CB_MCP_PORT: 8000
+          MCP_SERVER_URL: http://127.0.0.1:8000/sse
+          CB_MCP_TEST_SCOPE: inventory
+          CB_MCP_TEST_COLLECTION: airline
+          PYTHONPATH: src
+        run: |
+          echo "Running tests with SSE transport..."
+          uv run pytest tests/ -v --tb=short
+
+      - name: Stop SSE server
+        if: matrix.transport == 'sse' && always()
+        run: |
+          if [ -n "$SERVER_PID" ]; then
+            kill $SERVER_PID 2>/dev/null || true
+          fi
+
+  # ============================================
+  # Test Summary
+  # ============================================
+  test-summary:
+    name: Test Summary
+    permissions: {}
+    runs-on: ubuntu-latest
+    needs: [integration-tests]
+    if: always()
+    steps:
+      - name: Check test results
+        run: |
+          echo "=== Test Results Summary ==="
+          echo "Integration Tests: ${{ needs.integration-tests.result }}"
+          echo ""
+
+          if [ "${{ needs.integration-tests.result }}" == "failure" ]; then
+            echo "❌ Some tests failed"
+            exit 1
+          elif [ "${{ needs.integration-tests.result }}" == "cancelled" ]; then
+            echo "⚠️ Tests were cancelled"
+            exit 1
+          else
+            echo "✅ All tests passed!"
+          fi

{couchbase_mcp_server-0.5.2rc6 → couchbase_mcp_server-0.6.0}/.github/workflows/update-mcp-registry.yml

@@ -141,7 +141,9 @@ jobs:
 
       - name: Notify completion
         if: success()
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
         run: |
-          echo "MCP Registry updated successfully for version ${{ steps.version.outputs.version }}"
-          echo "Docker image: docker.io/couchbaseecosystem/mcp-server-couchbase:${{ steps.version.outputs.version }}"
-          echo "PyPI package: couchbase-mcp-server==${{ steps.version.outputs.version }}"
+          echo "MCP Registry updated successfully for version $VERSION"
+          echo "Docker image: docker.io/couchbaseecosystem/mcp-server-couchbase:$VERSION"
+          echo "PyPI package: couchbase-mcp-server==$VERSION"

couchbase_mcp_server-0.6.0/DOCKER.md

@@ -0,0 +1,194 @@
+# Couchbase MCP Server
+
+Pre-built images for the [Couchbase](https://www.couchbase.com/) MCP Server.
+
+A Model Context Protocol (MCP) server that allows AI agents to interact with Couchbase databases.
+
+Github Repo: https://github.com/Couchbase-Ecosystem/mcp-server-couchbase
+
+Dockerfile: https://github.com/Couchbase-Ecosystem/mcp-server-couchbase/blob/main/Dockerfile
+
+## 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) |
+
+## Usage
+
+The Docker images can be used in the supported MCP clients such as Claude Desktop, Cursor, Windsurf, etc in combination with Docker.
+
+### Configuration
+
+Add the configuration specified below to the MCP configuration in your MCP client.
+
+- Claude Desktop: https://modelcontextprotocol.io/quickstart/user
+- Cursor: https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers
+- Windsurf: https://docs.windsurf.com/windsurf/cascade/mcp#adding-a-new-mcp-plugin
+
+```json
+{
+  "mcpServers": {
+    "couchbase": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "-i",
+        "-e",
+        "CB_CONNECTION_STRING=<couchbase_connection_string>",
+        "-e",
+        "CB_USERNAME=<database_username>",
+        "-e",
+        "CB_PASSWORD=<database_password>",
+        "couchbaseecosystem/mcp-server-couchbase:latest"
+      ]
+    }
+  }
+}
+```
+
+### Environment Variables
+
+The detailed explanation for the environment variables can be found on the [Github Repo](https://github.com/Couchbase-Ecosystem/mcp-server-couchbase?tab=readme-ov-file#additional-configuration-for-mcp-server).
+
+| Variable                      | Description                                                                                               | Default                                                        |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `CB_CONNECTION_STRING`        | Couchbase Connection string                                                                               | **Required**                                                   |
+| `CB_USERNAME`                 | Database username                                                                                         | **Required (or Client Certificate and Key needed for mTLS)**   |
+| `CB_PASSWORD`                 | Database password                                                                                         | **Required (or Client Certificate and Key needed for mTLS)**   |
+| `CB_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`          | Path to the client key file for mTLS authentication                                                       | **Required if using mTLS (or Username and Password required)** |
+| `CB_CA_CERT_PATH`             | Path to server root certificate for TLS if server is configured with a self-signed/untrusted certificate. |                                                                |
+| `CB_MCP_READ_ONLY_MODE`       | Prevent all data modifications (KV and Query). When `true`, KV write tools are not loaded.                   | `true`                                                         |
+| `CB_MCP_TRANSPORT`            | Transport mode (stdio/http/sse)                                                                           | `stdio`                                                        |
+| `CB_MCP_HOST`                 | Server host (HTTP/SSE modes)                                                                              | `127.0.0.1`                                                    |
+| `CB_MCP_PORT`                 | Server port (HTTP/SSE modes)                                                                              | `8000`                                                         |
+| `CB_MCP_DISABLED_TOOLS`       | Tools to disable                                                                                          |                                                                |
+
+### 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), which disables all write operations (KV and Query), 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 `CB_MCP_READ_ONLY_MODE=true` (the default) for comprehensive write protection, and tool disabling as an additional layer to guide LLM behavior.