couchbase-mcp-server 0.5.0__tar.gz → 0.5.2__tar.gz

couchbase_mcp_server-0.5.2/.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.2/.github/workflows/docker.yml

@@ -0,0 +1,94 @@
+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: Check if stable release
+        id: check-stable
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          TAG_NAME="${GITHUB_REF#refs/tags/}"
+          echo "Checking tag: $TAG_NAME"
+
+          # Only match vX.Y.Z format (no suffixes like rc, alpha, beta)
+          if [[ "$TAG_NAME" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "is_stable=true" >> $GITHUB_OUTPUT
+            echo "This is a STABLE release: $TAG_NAME"
+          else
+            echo "is_stable=false" >> $GITHUB_OUTPUT
+            echo "This is a PRE-RELEASE: $TAG_NAME (will not update 'latest' or major.minor tags)"
+          fi
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          flavor: |
+            # Disable automatic 'latest' tag to have explicit control
+            latest=false
+          tags: |
+            # For PRs: tag as pr-<number>
+            type=ref,event=pr
+            # For all tags: extract full version without 'v' prefix (e.g., 0.5.2 or 0.5.2rc3)
+            type=match,pattern=v(.*),group=1
+            # For stable releases only: extract major.minor (e.g., 0.5 from v0.5.2)
+            type=match,pattern=v(\d+\.\d+),group=1,enable=${{ steps.check-stable.outputs.is_stable == 'true' }}
+            # For stable releases only: tag as 'latest'
+            type=raw,value=latest,enable=${{ steps.check-stable.outputs.is_stable == 'true' }}
+
+      - 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.2/.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.2/.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.2/.github/workflows/update-mcp-registry.yml

@@ -0,0 +1,149 @@
+name: Update MCP Registry
+
+on:
+  workflow_run:
+    workflows: ["Build and Push Docker Image"]
+    types:
+      - completed
+
+jobs:
+  check-and-update-registry:
+    # Only run on tag pushes and if the docker workflow succeeded
+    if: |
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push' &&
+      startsWith(github.event.workflow_run.head_branch, 'v')
+
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # Required for GitHub OIDC authentication with MCP Registry
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.workflow_run.head_branch }}
+
+      - name: Wait for PyPI release to complete
+        uses: fountainhead/action-wait-for-check@v1.2.0
+        id: wait-for-pypi
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          checkName: "Build and publish Python distributions to PyPI"
+          ref: ${{ github.event.workflow_run.head_sha }}
+          timeoutSeconds: 600
+          intervalSeconds: 10
+
+      - name: Check PyPI release status
+        if: steps.wait-for-pypi.outputs.conclusion != 'success'
+        run: |
+          echo "PyPI release did not succeed. Status: ${{ steps.wait-for-pypi.outputs.conclusion }}"
+          exit 1
+
+      - name: Validate version consistency
+        id: version
+        env:
+          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
+        run: |
+          # Read versions from files
+          ROOT_VERSION=$(jq -r '.version' server.json)
+          # Only get versions from packages that have a version field (exclude null/empty)
+          PACKAGE_VERSIONS=$(jq -r '.packages[] | select(.version != null) | .version' server.json | sort -u)
+          PYPROJECT_VERSION=$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
+          # Get tag from the triggering workflow (Docker), not current workflow
+          # Use environment variable to prevent code injection
+          TAG_VERSION=${HEAD_BRANCH#v}
+
+          echo "Version Check:"
+          echo "  server.json root:    $ROOT_VERSION"
+          echo "  server.json packages:"
+          jq -r '.packages[] |
+            if .version != null then
+              "     - \(.registryType):\(.identifier) = \(.version)"
+            else
+              "     - \(.registryType):\(.identifier) (no version field)"
+            end' server.json
+          echo "  pyproject.toml:      $PYPROJECT_VERSION"
+          echo "  Git tag:             $TAG_VERSION"
+          echo ""
+
+          # Check if all package versions match root version (only for packages with version field)
+          MISMATCH=false
+          if [ -n "$PACKAGE_VERSIONS" ]; then
+            while IFS= read -r pkg_ver; do
+              if [ "$pkg_ver" != "$ROOT_VERSION" ]; then
+                echo "ERROR: Package version ($pkg_ver) doesn't match root version ($ROOT_VERSION)"
+                MISMATCH=true
+              fi
+            done <<< "$PACKAGE_VERSIONS"
+          fi
+
+          if [ "$MISMATCH" = true ]; then
+            echo ""
+            echo "Fix: Update server.json so all package versions match the root version"
+            exit 1
+          fi
+
+          # Check if root version matches tag
+          if [ "$ROOT_VERSION" != "$TAG_VERSION" ]; then
+            echo "ERROR: server.json version ($ROOT_VERSION) doesn't match tag ($TAG_VERSION)"
+            echo "Fix: Update server.json root version to match the tag"
+            exit 1
+          fi
+
+          # Warn if pyproject.toml doesn't match
+          if [ "$PYPROJECT_VERSION" != "$TAG_VERSION" ]; then
+            echo "WARNING: pyproject.toml version ($PYPROJECT_VERSION) doesn't match tag ($TAG_VERSION)"
+            echo "This may cause PyPI issues"
+          fi
+
+          # Check Docker image tags in OCI identifiers
+          echo ""
+          echo "Checking Docker image tags..."
+          OCI_PACKAGES=$(jq -r '.packages[] | select(.registryType == "oci") | .identifier' server.json)
+          if [ -n "$OCI_PACKAGES" ]; then
+            OCI_TAG_MISMATCH=false
+            while IFS= read -r oci_id; do
+              # Extract tag from identifier (everything after last :)
+              IMAGE_TAG="${oci_id##*:}"
+              echo "  - Image: $oci_id"
+              echo "    Tag: $IMAGE_TAG"
+
+              if [ "$IMAGE_TAG" != "$ROOT_VERSION" ]; then
+                echo "    ERROR: Docker image tag ($IMAGE_TAG) doesn't match version ($ROOT_VERSION)"
+                OCI_TAG_MISMATCH=true
+              else
+                echo "    Tag matches"
+              fi
+            done <<< "$OCI_PACKAGES"
+
+            if [ "$OCI_TAG_MISMATCH" = true ]; then
+              echo ""
+              echo "Fix: Update Docker image tags in server.json to match the version"
+              exit 1
+            fi
+          fi
+
+          echo ""
+          echo "All version checks passed!"
+          echo "version=$ROOT_VERSION" >> $GITHUB_OUTPUT
+
+      - name: Install MCP Publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+
+      - name: Login to MCP Registry
+        run: ./mcp-publisher login github-oidc
+
+      - name: Publish to MCP Registry
+        run: ./mcp-publisher publish
+
+      - name: Notify completion
+        if: success()
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          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.5.2/.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.2/.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.2/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! 🚀