# Couchbase-Analytics-MCP

A production-grade **Model Context Protocol (MCP) server** for the **Couchbase Enterprise Analytics** service. Exposes the full Analytics API surface as 25 strongly-typed MCP tools, with a built-in GUI console, structured logging, Prometheus metrics, OpenTelemetry tracing, and comprehensive test coverage.

> **Important:** This server targets the Analytics service (Apache AsterixDB engine, SQL++, port 8095) — *not* the Couchbase Query (N1QL) service. All tools call `cluster.analyticsQuery()` and `/analytics/*` REST endpoints exclusively.

---

## Feature matrix

| Feature | Status |
|---|---|
| 25 MCP tools covering full Analytics API | ✅ |
| stdio transport (Claude Desktop) | ✅ |
| SSE/HTTP transport (remote agents) | ✅ |
| Connection pool (min/max/idle reaper) | ✅ |
| JWT + API key auth on SSE endpoint | ✅ |
| Structured JSON logging (Pino) | ✅ |
| Daily log rotation (pino-roll) | ✅ |
| Optional Loki push transport | ✅ |
| Prometheus `/metrics` endpoint | ✅ |
| OpenTelemetry traces → Jaeger | ✅ |
| `/health/live` + `/health/ready` probes | ✅ |
| React GUI console at `/console` | ✅ |
| Monaco SQL++ editor | ✅ |
| Schema browser (dataverse → dataset tree) | ✅ |
| Live tool call inspector | ✅ |
| Unit tests (≥90% coverage) | ✅ |
| Integration tests (real Couchbase) | ✅ |
| E2E tests (Supertest SSE transport) | ✅ |
| Docker multi-stage image | ✅ |
| Docker Compose (CB + Prometheus + Grafana + Jaeger) | ✅ |
| Helm chart | ✅ |
| GitHub Actions CI/CD | ✅ |
| Architecture docs + ADRs | ✅ |
| Operational runbooks | ✅ |

---

## Quick start

### Prerequisites

- Node.js ≥ 20
- Docker + Docker Compose
- Couchbase Server Enterprise ≥ 7.2 with Analytics service enabled

### Local development (Docker Compose)

```bash
git clone https://github.com/your-org/couchbase-analytics-mcp
cd couchbase-analytics-mcp

# Copy and edit environment
cp .env.example .env

# Start Couchbase + MCP server + Prometheus + Grafana + Jaeger
docker-compose up -d

# GUI console: http://localhost:3000/console
# Prometheus:  http://localhost:9091
# Grafana:     http://localhost:3001  (admin/admin)
# Jaeger:      http://localhost:16686
```

### Run against an existing Couchbase cluster

```bash
npm install

CB_CONNECTION_STRING=couchbase://my-cluster \
CB_USERNAME=Administrator \
CB_PASSWORD=password \
TRANSPORT=stdio \
node packages/mcp-server/dist/index.js
```

### Claude Desktop integration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "couchbase-analytics": {
      "command": "node",
      "args": ["/path/to/couchbase-analytics-mcp/packages/mcp-server/dist/index.js"],
      "env": {
        "CB_CONNECTION_STRING": "couchbase://your-cluster",
        "CB_USERNAME": "Administrator",
        "CB_PASSWORD": "your-password",
        "TRANSPORT": "stdio"
      }
    }
  }
}
```

---

## Environment variables

| Variable | Default | Description |
|---|---|---|
| `CB_CONNECTION_STRING` | *(required)* | `couchbase://host` or `couchbases://host` for TLS |
| `CB_USERNAME` | *(required)* | Couchbase RBAC username |
| `CB_PASSWORD` | *(required)* | Couchbase RBAC password |
| `CB_ANALYTICS_PORT` | `8095` | Analytics REST port (18095 for TLS) |
| `CB_ANALYTICS_TLS` | `false` | Enable TLS for REST calls |
| `TRANSPORT` | `stdio` | `stdio` or `sse` |
| `PORT` | `3000` | HTTP server port (SSE + health + GUI) |
| `POOL_MIN` | `2` | Minimum pool connections |
| `POOL_MAX` | `10` | Maximum pool connections |
| `POOL_IDLE_TIMEOUT_MS` | `30000` | Idle connection reap threshold |
| `QUERY_DEFAULT_TIMEOUT_MS` | `60000` | Default query timeout |
| `LOG_LEVEL` | `info` | `trace\|debug\|info\|warn\|error\|fatal` |
| `LOG_FORMAT` | `json` | `json\|pretty` |
| `LOG_FILE_ENABLED` | `false` | Enable file transport |
| `LOG_FILE_PATH` | `/var/log/cba-mcp/server.log` | Log file path |
| `LOKI_HOST` | *(optional)* | Loki push endpoint |
| `METRICS_ENABLED` | `true` | Expose `/metrics` |
| `OTEL_ENABLED` | `false` | Enable OpenTelemetry tracing |
| `JAEGER_ENDPOINT` | `http://localhost:14268/api/traces` | Jaeger HTTP collector |
| `JWT_SECRET` | *(optional)* | JWT signing secret for SSE auth |
| `API_KEY` | *(optional)* | Static API key for SSE auth |
| `GUI_ENABLED` | `true` | Serve GUI at `/console` |

---

## Tool reference

See [docs/api/TOOLS.md](docs/api/TOOLS.md) for full input/output schemas.

| Tool | Group | Description |
|---|---|---|
| `analytics_execute` | Query | Execute SQL++ statement |
| `analytics_explain` | Query | Return query execution plan |
| `analytics_cancel` | Query | Cancel running query |
| `analytics_query_status` | Query | Check async query status |
| `analytics_pending_mutations` | Query | KV→Analytics replication lag |
| `analytics_list_dataverses` | Schema | List all dataverses |
| `analytics_list_datasets` | Schema | List datasets |
| `analytics_describe_dataset` | Schema | Field-level dataset description |
| `analytics_infer_schema` | Schema | INFER DATASET → JSON Schema |
| `analytics_list_indexes` | Schema | List Analytics secondary indexes |
| `analytics_create_dataverse` | Dataverse | CREATE DATAVERSE |
| `analytics_drop_dataverse` | Dataverse | DROP DATAVERSE |
| `analytics_create_dataset` | Dataverse | CREATE DATASET (shadow collection) |
| `analytics_drop_dataset` | Dataverse | DROP DATASET |
| `analytics_alter_dataset` | Dataverse | Modify dataset WHERE predicate |
| `analytics_list_links` | Links | List data source links |
| `analytics_create_link` | Links | Create CB/S3/Azure/GCS link |
| `analytics_alter_link` | Links | Update link configuration |
| `analytics_drop_link` | Links | Delete a link |
| `analytics_connect_link` | Links | Start ingestion (CONNECT LINK) |
| `analytics_disconnect_link` | Links | Pause ingestion (DISCONNECT LINK) |
| `analytics_create_index` | Indexes | CREATE Analytics secondary index |
| `analytics_drop_index` | Indexes | DROP Analytics secondary index |
| `analytics_analyze_dataset` | Indexes | Collect optimizer statistics |
| `analytics_node_agg_stats` | Cluster | Per-node resource stats |
| `analytics_service_health` | Cluster | Composite health summary |
| `analytics_cluster_config` | Cluster | Analytics service configuration |
| `analytics_set_config_param` | Cluster | Mutate config param (guarded) |
| `analytics_restart_node` | Cluster | Restart Analytics node(s) (guarded) |

---

## Development

```bash
# Install all workspace dependencies
npm install

# Build all packages
npm run build

# Run unit tests with coverage
npm run test:coverage

# Run integration tests (requires Couchbase)
docker-compose up -d couchbase
npm run test:integration -w packages/mcp-server

# Start dev server (hot reload)
npm run dev

# Generate API docs
npm run docs
```

## Support Policy
I truly appreciate your interest in this project! This project is community-maintained. However, I actively monitor and maintain this repo and will try to resolve issues on a best-effort basis.

All inquiries should be through GitHub.

    Bug reports: Open a GitHub issue
    Feature requests: Open a GitHub issue with the "enhancement" label
    Questions: Open a GitHub issue

Your collaboration helps me move forward together - thank you! Pull requests and contributions from the community are welcome and encouraged.

---

## Architecture

See [docs/architecture/ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md) for the full component diagram, data flow description, and design decisions.