Skip to main content
Glama
deenesjakoruzh
celticht32

Couchbase-Analytics-MCP

by celticht32
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Couchbase-Analytics-MCP

Couchbase Enterprise Analyticsサービス向けのプロダクショングレードのModel Context Protocol (MCP) サーバーです。Analytics APIの全機能を25個の型安全なMCPツールとして公開し、組み込みのGUIコンソール、構造化ログ、Prometheusメトリクス、OpenTelemetryトレーシング、包括的なテストカバレッジを備えています。

重要: このサーバーはAnalyticsサービス（Apache AsterixDBエンジン、SQL++、ポート8095）を対象としており、Couchbase Query (N1QL) サービスは対象外です。すべてのツールは cluster.analyticsQuery() および /analytics/* RESTエンドポイントのみを呼び出します。

機能マトリックス

機能

ステータス

Analytics APIを網羅する25個のMCPツール

✅

stdioトランスポート (Claude Desktop)

✅

SSE/HTTPトランスポート (リモートエージェント)

✅

コネクションプール (最小/最大/アイドル解放)

✅

SSEエンドポイントでのJWT + APIキー認証

✅

構造化JSONログ (Pino)

✅

日次ログローテーション (pino-roll)

✅

オプションのLokiプッシュトランスポート

✅

Prometheus /metrics エンドポイント

✅

OpenTelemetryトレース → Jaeger

✅

/health/live + /health/ready プローブ

✅

/console でのReact GUIコンソール

✅

Monaco SQL++エディタ

✅

スキーマブラウザ (データバース → データセットツリー)

✅

ライブツール呼び出しインスペクター

✅

ユニットテスト (カバレッジ90%以上)

✅

統合テスト (実際のCouchbase)

✅

E2Eテスト (Supertest SSEトランスポート)

✅

Dockerマルチステージイメージ

✅

Docker Compose (CB + Prometheus + Grafana + Jaeger)

✅

Helmチャート

✅

GitHub Actions CI/CD

✅

アーキテクチャドキュメント + ADR

✅

運用ランブック

✅

クイックスタート

前提条件

  • Node.js ≥ 20

  • Docker + Docker Compose

  • Couchbase Server Enterprise ≥ 7.2 (Analyticsサービス有効)

ローカル開発 (Docker Compose)

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

既存のCouchbaseクラスターに対して実行

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との統合

~/Library/Application Support/Claude/claude_desktop_config.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"
      }
    }
  }
}

環境変数

変数

デフォルト

説明

CB_CONNECTION_STRING

(必須)

couchbase://host またはTLS用 couchbases://host

CB_USERNAME

(必須)

Couchbase RBACユーザー名

CB_PASSWORD

(必須)

Couchbase RBACパスワード

CB_ANALYTICS_PORT

8095

Analytics RESTポート (TLS時は18095)

CB_ANALYTICS_TLS

false

REST呼び出しのTLS有効化

TRANSPORT

stdio

stdio または sse

PORT

3000

HTTPサーバーポート (SSE + ヘルスチェック + GUI)

POOL_MIN

2

最小プール接続数

POOL_MAX

10

最大プール接続数

POOL_IDLE_TIMEOUT_MS

30000

アイドル接続の解放しきい値

QUERY_DEFAULT_TIMEOUT_MS

60000

デフォルトのクエリタイムアウト

LOG_LEVEL

info

`trace

debug

info

warn

error

fatal`

LOG_FORMAT

json

`json

pretty`

LOG_FILE_ENABLED

false

ファイルトランスポートの有効化

LOG_FILE_PATH

/var/log/cba-mcp/server.log

ログファイルのパス

LOKI_HOST

(オプション)

Lokiプッシュエンドポイント

METRICS_ENABLED

true

/metrics の公開

OTEL_ENABLED

false

OpenTelemetryトレーシングの有効化

JAEGER_ENDPOINT

http://localhost:14268/api/traces

Jaeger HTTPコレクター

JWT_SECRET

(オプション)

SSE認証用JWT署名シークレット

API_KEY

(オプション)

SSE認証用静的APIキー

GUI_ENABLED

true

/console でGUIを提供

ツールリファレンス

完全な入出力スキーマについては docs/api/TOOLS.md を参照してください。

ツール

グループ

説明

analytics_execute

Query

SQL++ステートメントの実行

analytics_explain

Query

クエリ実行計画の取得

analytics_cancel

Query

実行中のクエリのキャンセル

analytics_query_status

Query

非同期クエリステータスの確認

analytics_pending_mutations

Query

KV→Analyticsレプリケーション遅延

analytics_list_dataverses

Schema

全データバースのリスト表示

analytics_list_datasets

Schema

データセットのリスト表示

analytics_describe_dataset

Schema

フィールドレベルのデータセット説明

analytics_infer_schema

Schema

INFER DATASET → JSONスキーマ

analytics_list_indexes

Schema

Analyticsセカンダリインデックスのリスト表示

analytics_create_dataverse

Dataverse

CREATE DATAVERSE

analytics_drop_dataverse

Dataverse

DROP DATAVERSE

analytics_create_dataset

Dataverse

CREATE DATASET (シャドウコレクション)

analytics_drop_dataset

Dataverse

DROP DATASET

analytics_alter_dataset

Dataverse

データセットWHERE述語の変更

analytics_list_links

Links

データソースリンクのリスト表示

analytics_create_link

Links

CB/S3/Azure/GCSリンクの作成

analytics_alter_link

Links

リンク設定の更新

analytics_drop_link

Links

リンクの削除

analytics_connect_link

Links

インジェストの開始 (CONNECT LINK)

analytics_disconnect_link

Links

インジェストの一時停止 (DISCONNECT LINK)

analytics_create_index

Indexes

Analyticsセカンダリインデックスの作成

analytics_drop_index

Indexes

Analyticsセカンダリインデックスの削除

analytics_analyze_dataset

Indexes

オプティマイザ統計の収集

analytics_node_agg_stats

Cluster

ノードごとのリソース統計

analytics_service_health

Cluster

複合ヘルスサマリー

analytics_cluster_config

Cluster

Analyticsサービス設定

analytics_set_config_param

Cluster

設定パラメータの変更 (保護付き)

analytics_restart_node

Cluster

Analyticsノードの再起動 (保護付き)

開発

# 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

サポートポリシー

本プロジェクトにご関心をお寄せいただき、誠にありがとうございます！本プロジェクトはコミュニティによって維持されています。ただし、私はこのリポジトリを積極的に監視・保守しており、ベストエフォートベースで問題を解決するよう努めます。

お問い合わせはすべてGitHubを通じて行ってください。

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

皆様のご協力がプロジェクトの推進力となります。ありがとうございます！コミュニティからのプルリクエストや貢献を歓迎し、推奨しています。

アーキテクチャ

完全なコンポーネント図、データフローの説明、設計上の決定については docs/architecture/ARCHITECTURE.md を参照してください。

This server cannot be deployed

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Resources

Related MCP Connectors