# Couchbase MCP Server

[![Validate](https://github.com/tirth1263/couchbase-mcp-server/actions/workflows/validate.yml/badge.svg)](https://github.com/tirth1263/couchbase-mcp-server/actions/workflows/validate.yml)
[![Live Demo Site](https://img.shields.io/badge/site-live-0f766e)](https://tirth1263.github.io/couchbase-mcp-server/)
[![Python](https://img.shields.io/badge/python-3.11%2B-2563eb)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-f59e0b)](LICENSE)

A production-shaped demo that connects a natural-language AI agent to Couchbase through the Model Context Protocol (MCP). It uses the OpenAI Agents SDK as the agent runtime, a stdio MCP server as the tool bridge, Couchbase `travel-sample` as the data source, and a Nebius-hosted OpenAI-compatible model as the LLM backend.

**Live project site:** https://tirth1263.github.io/couchbase-mcp-server/

## Why This Project Exists

LLMs are good at understanding intent, but they need trustworthy tools to answer questions grounded in private or operational data. MCP gives those tools a standard shape. This repository demonstrates that pattern end to end:

- A user asks a plain-English travel question.
- The OpenAI Agents SDK agent decides whether it needs database context.
- The agent calls a Couchbase MCP tool over stdio.
- The MCP server executes scoped SQL++ against the `travel-sample.inventory` data.
- The agent turns the database result into a clear recommendation or answer.

Example questions:

- "List out the top 5 hotels by the highest aggregate rating."
- "Recommend me a flight and hotel from New York to San Francisco."
- "Which airports are near San Francisco and what routes connect to them?"

## Architecture

```mermaid
flowchart LR
    U["User question"] --> N["main.ipynb / CLI demo"]
    N --> A["OpenAI Agents SDK agent"]
    A --> M["MCPServerStdio client"]
    M <--> S["Couchbase MCP server"]
    S --> C["Couchbase travel-sample bucket"]
    A --> L["Nebius OpenAI-compatible LLM"]
    C --> S --> M --> A --> R["Natural-language answer"]
```

## What Is Included

- `src/couchbase_mcp_server/mcp_server.py` - the stdio MCP server.
- `src/couchbase_mcp_server/couchbase_client.py` - Couchbase SDK wrapper and JSON serialization.
- `src/couchbase_mcp_server/demo_agent.py` - command-line OpenAI Agents SDK demo.
- `main.ipynb` - Jupyter notebook version of the demo.
- `.env.example` - environment variables for Couchbase and Nebius.
- `docs/` - static GitHub Pages website.
- `tests/` - focused safety tests for SQL++ mutation detection.

## MCP Tools Exposed

| Tool | Purpose |
| --- | --- |
| `get_connection_summary` | Shows the configured bucket, scope, host, and read/write mode without exposing secrets. |
| `get_scopes_and_collections` | Lists scopes and collections in the configured Couchbase bucket. |
| `run_sql_plus_plus_query` | Runs SQL++ in the configured bucket/scope query context. |
| `get_document_by_id` | Fetches a document from a named collection in the inventory scope. |
| `get_sample_queries` | Returns useful SQL++ examples for the travel-sample inventory data. |

By default, `run_sql_plus_plus_query` blocks mutations such as `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `CREATE`, `DROP`, and `ALTER`. Set `COUCHBASE_ALLOW_MUTATIONS=true` only when you intentionally want write-capable tools.

## Prerequisites

- Python 3.11 or newer. Python 3.12 is recommended.
- Jupyter Notebook or JupyterLab for `main.ipynb`.
- A running Couchbase Server or Couchbase Capella instance.
- The `travel-sample` bucket loaded with the `inventory` scope.
- A Nebius API key for an OpenAI-compatible chat model endpoint.

## Quick Start

Clone and install:

```bash
git clone https://github.com/tirth1263/couchbase-mcp-server.git
cd couchbase-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e ".[notebook]"
```

On Windows PowerShell:

```powershell
git clone https://github.com/tirth1263/couchbase-mcp-server.git
cd couchbase-mcp-server
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[notebook]"
```

Create your environment file:

```bash
cp .env.example .env
```

Then edit `.env`:

```dotenv
COUCHBASE_HOST=couchbases://your-capella-endpoint
COUCHBASE_BUCKET_NAME=travel-sample
COUCHBASE_SCOPE_NAME=inventory
COUCHBASE_USERNAME=your_couchbase_username
COUCHBASE_PASSWORD=your_couchbase_password
NEBIUS_API_KEY=your_nebius_api_key
NEBIUS_BASE_URL=https://api.studio.nebius.ai/v1/
NEBIUS_MODEL=meta-llama/Meta-Llama-3.1-8B-Instruct
```

## Run the MCP Server

You can start the MCP server directly:

```bash
python -m couchbase_mcp_server.mcp_server --env-file .env
```

The server uses stdio, so it is usually launched by an MCP client rather than run interactively. Logs are written to stderr so stdout stays reserved for MCP messages.

## Run the Agent Demo

Notebook:

```bash
jupyter lab main.ipynb
```

CLI:

```bash
couchbase-agent-demo "List the top 5 hotels by aggregate rating."
```

Or:

```bash
python -m couchbase_mcp_server.demo_agent \
  --env-file .env \
  "Recommend a flight and hotel from New York to San Francisco."
```

## Agent Instructions

The demo agent is intentionally explicit about Couchbase structure:

- A Couchbase cluster contains buckets.
- A bucket contains scopes.
- A scope contains collections.
- Collections contain JSON documents.
- The target demo data lives in the `inventory` scope.
- SQL++ queries should run in a scoped query context, so the `FROM` clause can use collection names like `` `hotel` `` rather than fully qualified paths.
- All identifiers should be wrapped in backticks.

That last point matters because SQL++ collection and field names can collide with keywords or include characters that need quoting.

## Website

The public website is served from `docs/` using GitHub Pages:

https://tirth1263.github.io/couchbase-mcp-server/

The site is a static deployment artifact, so it can also be hosted on Netlify, Vercel, Cloudflare Pages, or any static web server without a build step.

## Development

Run validation:

```bash
python scripts/validate_project.py
python -m compileall src
pytest
```

Format and lint if you install the dev extras:

```bash
pip install -e ".[dev,notebook]"
ruff check .
ruff format .
```

## Security Notes

- Do not commit `.env`; it is intentionally ignored.
- Keep `COUCHBASE_ALLOW_MUTATIONS=false` for demos, workshops, and public examples.
- Use a least-privilege Couchbase user with access only to the demo bucket/scope.
- Prefer read-only database credentials unless you are intentionally demonstrating write tools.
- Treat LLM-generated SQL++ as untrusted input and keep server-side guardrails in place.

## References

- OpenAI Agents SDK: https://openai.github.io/openai-agents-python/
- Agents SDK MCP integration: https://openai.github.io/openai-agents-python/mcp/
- Model Context Protocol: https://modelcontextprotocol.io/
- Couchbase Python SDK: https://docs.couchbase.com/python-sdk/current/hello-world/start-using-sdk.html
- Couchbase travel-sample: https://docs.couchbase.com/server/current/getting-started/do-a-quick-install.html#install-sample-buckets