couchbase-mcp-server 0.4.0rc1__tar.gz → 0.5.1__tar.gz

couchbase_mcp_server-0.5.1/.github/workflows/alert-on-pr.yml

@@ -0,0 +1,74 @@
+name: Alert on PR Changes
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  pull_request_target:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  alert:
+    # Only run this job if:
+    # - The event is 'pull_request' and the PR is from the same repository (not a fork), OR
+    # - The event is 'pull_request_target' and the PR is from a forked repository.
+    # This ensures that PRs from forks are handled with 'pull_request_target' (for security),
+    # while PRs from the same repo are handled with 'pull_request'.
+    if: >-
+      (
+        github.event_name == 'pull_request' &&
+        github.event.pull_request.head.repo.full_name == github.repository
+      ) ||
+      (
+        github.event_name == 'pull_request_target' &&
+        github.event.pull_request.head.repo.full_name != github.repository
+      )
+    runs-on: ubuntu-latest
+    steps:
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install requests
+        run: |
+          python -m pip install --upgrade pip
+          pip install requests
+
+      - name: Send Slack alert on PR changes
+        env:
+          SLACK_WEBHOOK: ${{ secrets.DEVEX_ALERTS_SECRET }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+        shell: python
+        run: |
+          import os, requests
+          repo = os.environ['REPO']
+          pr_number = os.environ['PR_NUMBER']
+          token = os.environ['GITHUB_TOKEN']
+          api_url = f"https://api.github.com/repos/{repo}/pulls/{pr_number}"
+          headers = {'Authorization': f'token {token}', 'Accept': 'application/vnd.github.v3+json'}
+          pr_resp = requests.get(api_url, headers=headers, timeout=15)
+          if pr_resp.ok:
+              pr = pr_resp.json()
+              branch_name = pr.get('head', {}).get('ref') or os.environ.get('GITHUB_HEAD_REF', '')
+              pr_title = pr.get('title', '')
+              pr_body = pr.get('body', '')
+              pr_user = pr.get('user', {}).get('login', '')
+              pr_url = pr.get('html_url', '')
+              prefix = "PR Alert from Forked Repo!" if pr.get('head', {}).get('repo', {}).get('fork') else "PR Alert!"
+              message = f"{prefix}\nTitle: {pr_title}\nBranch: {branch_name}\nAuthor: {pr_user}\nURL: {pr_url}\nDescription: {pr_body}"
+          else:
+              message = f"PR Alert!\nUnable to fetch PR details.\nStatus Code: {pr_resp.status_code}\nResponse: {pr_resp.text}"
+          webhook = os.environ.get('SLACK_WEBHOOK', '').strip()
+          if webhook and webhook.startswith(("http://", "https://")):
+              try:
+                  resp = requests.post(webhook, json={"text": message}, timeout=15)
+                  resp.raise_for_status()
+              except Exception as e:
+                  print(f"Slack notification failed: {e}")
+          else:
+              print("SLACK_WEBHOOK missing or invalid; skipping Slack notification.")

couchbase_mcp_server-0.5.1/.github/workflows/docker.yml

@@ -0,0 +1,71 @@
+name: Build and Push Docker Image
+
+on:
+  push:
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+env:
+  REGISTRY: docker.io
+  IMAGE_NAME: couchbaseecosystem/mcp-server-couchbase
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Docker Hub
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest
+
+      - name: Set build timestamp
+        id: timestamp
+        run: echo "BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ')" >> $GITHUB_OUTPUT
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            GIT_COMMIT_HASH=${{ github.sha }}
+            BUILD_DATE=${{ steps.timestamp.outputs.BUILD_DATE }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Update Docker Hub description
+        if: github.ref_type == 'tag'
+        uses: peter-evans/dockerhub-description@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+          repository: ${{ env.IMAGE_NAME }}
+          readme-filepath: ./DOCKER.md

couchbase_mcp_server-0.5.1/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: PyPI Release
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+*" # Match tags like v0.1.0, v1.2.3, v1.2.3-alpha.1
+  workflow_dispatch:
+
+jobs:
+  pypi-publish:
+    name: Build and publish Python distributions to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # Required for trusted publishing
+      contents: write # Required for creating releases
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv with python 3.11
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: latest
+          python-version: 3.11
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Generate changelog and create release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          prerelease: false
+          files: dist/*

couchbase_mcp_server-0.5.1/.github/workflows/test_release.yml

@@ -0,0 +1,32 @@
+name: Test PyPI Release
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+*" # Match tags like v0.1.0, v1.2.3, v1.2.3-alpha.1
+  workflow_dispatch:
+
+jobs:
+  test-pypi-publish:
+    name: Build and publish Python distributions to Test PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # Required for trusted publishing
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv with python 3.11
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: latest
+          python-version: 3.11
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

couchbase_mcp_server-0.5.1/.gitignore

@@ -0,0 +1,12 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+# Environment variables
+.env

couchbase_mcp_server-0.5.1/.pre-commit-config.yaml

@@ -0,0 +1,37 @@
+# Pre-commit hooks configuration
+# See https://pre-commit.com for more information
+
+repos:
+  # Ruff linter and formatter
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.0
+    hooks:
+      # Run the linter
+      - id: ruff
+        name: ruff-lint
+        args: [--fix]
+        types_or: [python, pyi, jupyter]
+      # Run the formatter
+      - id: ruff-format
+        name: ruff-format
+        types_or: [python, pyi, jupyter]
+
+  # Additional useful hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: debug-statements
+
+  # Check for Python syntax errors
+  - repo: https://github.com/pre-commit/pygrep-hooks
+    rev: v1.10.0
+    hooks:
+      - id: python-check-blanket-noqa
+      - id: python-no-log-warn

couchbase_mcp_server-0.5.1/CONTRIBUTING.md

@@ -0,0 +1,234 @@
+# Contributing to Couchbase MCP Server
+
+Thank you for your interest in contributing to the Couchbase MCP Server! This guide will help you set up your development environment and understand our development workflow.
+
+## 🚀 Development Setup
+
+### Prerequisites
+
+- **Python 3.10+**: Required for the project
+- **[uv](https://docs.astral.sh/uv/)**: Fast Python package installer and dependency manager
+- **Git**: For version control
+- **VS Code** (recommended): With Python extension for the best development experience
+
+### Clone and Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/Couchbase-Ecosystem/mcp-server-couchbase.git
+cd mcp-server-couchbase
+
+# Install dependencies (including development tools)
+uv sync --extra dev
+```
+
+### Install Development Tools
+
+```bash
+# Install pre-commit hooks (runs linting on every commit)
+uv run pre-commit install
+
+# Verify installation
+uv run pre-commit run --all-files
+```
+
+## 🧹 Code Quality & Linting
+
+We use **[Ruff](https://docs.astral.sh/ruff/)** for fast linting and code formatting to maintain consistent code quality.
+
+### Manual Linting
+
+```bash
+# Check code quality (no changes made)
+./scripts/lint.sh
+# or: uv run ruff check src/
+
+# Auto-fix issues
+./scripts/fix_lint.sh
+# or: uv run ruff check src/ --fix && uv run ruff format src/
+```
+
+### Automatic Linting
+
+- **Pre-commit hooks**: Ruff runs automatically on every `git commit`
+- **VS Code**: Auto-format on save using [Ruff extension](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff)
+
+### Linting Rules
+
+Our Ruff configuration includes:
+
+- **Code style**: PEP 8 compliance with 88-character line limit
+- **Import organization**: Automatic import sorting and cleanup
+- **Code quality**: Detection of unused variables, simplification opportunities
+- **Modern Python**: Encourages modern Python patterns with `pyupgrade`
+
+## 🏗️ Project Structure
+
+```
+mcp-server-couchbase/
+├── src/
+│   ├── mcp_server.py              # MCP server entry point
+│   ├── certs/                     # SSL/TLS certificates
+│   │   ├── __init__.py            # Package marker
+│   │   └── capella_root_ca.pem    # Capella root CA certificate (for Capella connections)
+│   ├── tools/                     # MCP tool implementations
+│   │   ├── __init__.py            # Tool exports and ALL_TOOLS list
+│   │   ├── server.py              # Server status and connection tools
+│   │   ├── kv.py                  # Key-value operations (CRUD)
+│   │   ├── query.py               # SQL++ query operations
+│   │   └── index.py               # Index operations and recommendations
+│   └── utils/                     # Utility modules
+│       ├── __init__.py            # Utility exports
+│       ├── constants.py           # Project constants
+│       ├── config.py              # Configuration management
+│       ├── connection.py          # Couchbase connection handling
+│       ├── context.py             # Application context management
+│       └── index_utils.py         # Index-related helper functions
+├── scripts/                       # Development scripts
+│   ├── lint.sh                    # Manual linting script
+│   └── lint_fix.sh                # Auto-fix linting issues
+├── .pre-commit-config.yaml        # Pre-commit hook configuration
+├── pyproject.toml                 # Project dependencies and Ruff config
+├── CONTRIBUTING.md                # Contribution Guide
+└── README.md                      # Usage
+```
+
+## 🛠️ Development Workflow
+
+### Making Changes
+
+1. **Create a branch** for your feature/fix:
+
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** following the existing patterns
+
+3. **Test your changes**:
+
+   ```bash
+   # Run linting
+   ./scripts/lint.sh
+
+   # Test the MCP server
+   uv run src/mcp_server.py --help
+   ```
+
+4. **Commit your changes**:
+
+   ```bash
+   git add .
+   git commit -m "feat: add your feature description"
+   ```
+
+   The pre-commit hooks will automatically run and fix any formatting issues.
+
+### Adding New Tools
+
+When adding new MCP tools:
+
+1. **Create the tool function** in the appropriate module (in `tools` directory)
+2. **Export the tool** in `tools/__init__.py`
+3. **Add to ALL_TOOLS** list in `tools/__init__.py`
+4. **Test the tool** with an MCP client
+
+### Code Style Guidelines
+
+- **Line length**: 88 characters (enforced by Ruff)
+- **Import organization**: Use isort-style grouping (standard library, third-party, local)
+- **Type hints**: Use modern Python type hints where helpful
+- **Docstrings**: Add docstrings for public functions and classes
+- **Error handling**: Include appropriate exception handling with logging
+
+## 🧪 Testing
+
+### Manual Testing
+
+Currently, testing is done manually with MCP clients:
+
+1. **Set up environment variables** for your Couchbase cluster
+2. **Run the server** with an MCP client like Claude Desktop
+3. **Test tool functionality** through the client interface
+
+### Future Testing Plans
+
+We plan to add:
+
+- Unit tests for utility functions
+- Integration tests
+- Automated testing in CI/CD
+
+## 📋 Adding New Features
+
+### Before You Start
+
+1. **Check existing issues** to see if someone is already working on it
+2. **Open an issue** to discuss larger changes
+3. **Review the codebase** to understand existing patterns
+
+### Implementation Guidelines
+
+1. **Follow existing patterns**: Look at similar tools for guidance
+2. **Use the utility modules**: Leverage existing connection and context management
+3. **Add proper logging**: Use the hierarchical logging system
+4. **Handle errors gracefully**: Provide helpful error messages
+5. **Update documentation**: Update README.md if adding user-facing features
+
+## 🤝 Submitting Changes
+
+1. **Run final checks**:
+
+   ```bash
+   # Ensure all linting passes
+   ./scripts/lint.sh
+
+   # Test with pre-commit
+   uv run pre-commit run --all-files
+   ```
+
+2. **Push your branch** and create a pull request
+
+3. **Describe your changes** in the PR description:
+   - What does this change do?
+   - Why is this change needed?
+   - How have you tested it?
+
+## 💡 Tips for Contributors
+
+### Common Development Tasks
+
+```bash
+# Install new dependencies
+uv add package-name
+
+# Install new dev dependencies
+uv add --dev package-name
+
+# Update dependencies
+uv sync
+
+# Run the server for testing
+uv run src/mcp_server.py --connection-string "..." --username "..." --password "..." --bucket-name "..."
+```
+
+### Debugging
+
+- **Use logging**: The project uses hierarchical logging with the pattern `logger = logging.getLogger(f"{MCP_SERVER_NAME}.module.name")`
+- **Check connection**: Ensure your Couchbase cluster is accessible
+- **Validate configuration**: Make sure all required environment variables are set
+
+## 📖 Additional Resources
+
+- **[Model Context Protocol Documentation](https://modelcontextprotocol.io/)**
+- **[Couchbase Python SDK Documentation](https://docs.couchbase.com/python-sdk/current/hello-world/start-using-sdk.html)**
+- **[SQL++ Query Language](https://www.couchbase.com/sqlplusplus/)**
+- **[Ruff Documentation](https://docs.astral.sh/ruff/)**
+
+## 🆘 Getting Help
+
+- **Open an issue** for bugs or feature requests
+- **Check existing issues** for similar problems
+- **Review the code** for examples and patterns
+
+Thank you for contributing to the Couchbase MCP Server! 🚀

couchbase_mcp_server-0.5.1/DOCKER.md

@@ -0,0 +1,78 @@
+# 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
+
+- 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
+  - 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
+
+## 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_QUERY_MODE` | Prevent data modification queries via SQL++                                                               | `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`                                                         |

couchbase_mcp_server-0.5.1/Dockerfile

@@ -0,0 +1,61 @@
+# Build stage - use official uv image with Python 3.10
+FROM ghcr.io/astral-sh/uv:python3.10-bookworm-slim AS builder
+
+# Set uv configuration
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy
+
+WORKDIR /build
+
+# Copy dependency files for caching
+COPY pyproject.toml README.md ./
+COPY src/ ./src/
+
+# Create virtual environment and install dependencies
+RUN uv venv /opt/venv && \
+    uv pip install --python /opt/venv/bin/python .
+
+# Runtime stage - use Python image with same version as builder
+FROM python:3.10-slim-bookworm AS runtime
+
+# Accept build arguments for labels
+ARG GIT_COMMIT_HASH="unknown"
+ARG BUILD_DATE="unknown"
+
+# Add metadata labels
+LABEL org.opencontainers.image.revision="${GIT_COMMIT_HASH}" \
+    org.opencontainers.image.created="${BUILD_DATE}" \
+    org.opencontainers.image.title="MCP Server Couchbase" \
+    org.opencontainers.image.description="Model Context Protocol server for Couchbase" \
+    org.opencontainers.image.source="https://github.com/Couchbase-Ecosystem/mcp-server-couchbase"\
+    io.modelcontextprotocol.server.name="io.github.Couchbase-Ecosystem/mcp-server-couchbase"
+
+# Create non-root user
+RUN useradd --system --uid 1001 mcpuser
+
+WORKDIR /app
+
+# Copy virtual environment and application from builder
+COPY --from=builder /opt/venv /opt/venv
+
+# Set up Python environment
+ENV PATH="/opt/venv/bin:$PATH" \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+# Change ownership to non-root user
+RUN chown -R mcpuser:mcpuser /app /opt/venv
+
+# Switch to non-root user
+USER 1001
+
+# Environment variables with stdio defaults (override for network mode)
+ENV CB_MCP_READ_ONLY_QUERY_MODE="true" \
+    CB_MCP_TRANSPORT="stdio" \
+    CB_MCP_PORT="8000"
+
+# Expose default port for HTTP/SSE mode
+EXPOSE 8000
+
+# Use the installed console script
+ENTRYPOINT ["couchbase-mcp-server"]