Kurrentdb Mcp Server

KurrentDB MCP サーバー

KurrentDB 上でデータを調べ、プロジェクションをすばやくプロトタイプできる、シンプルな MCP サーバーです。

推奨される使い方

• Claude Desktop
• 複雑なタスクには Sequential Thinking MCP

インストール

KurrentDB のセットアップ

KurrentDB で --run-projections=all と --start-standard-projections を有効にする必要があります。 利用可能なストリームを探すために、$streams ストリームが使用されます。

Python の依存関係

requirements.txt に記載されたパッケージが pip でインストールされていることを確認してください。

OS の依存関係

MCP サーバーを実行するマシンに vu パッケージがインストールされていることを確認してください。

Mac の場合：brew install uv

MCP クライアントのセットアップ（VS Code）

{
    "servers": {
      "KurrentDB": {
        "type": "stdio",
        "command": "uv",
            "args": [
                "--directory",
                "path to mcp-server folder",
                "run",
                "server.py"
            ],
	    "env": {
             "KURRENTDB_CONNECTION_STRING": "insert kurrentdb connection here"
        }
      }
    }
  }

この設定ファイルは VS Code（.vscode/mcp.json）で動作します。

MCP クライアントのセットアップ（Claude）

{
    "mcpServers": {
      "KurrentDB": {
        "type": "stdio",
        "command": "uv",
            "args": [
                "--directory",
                "path to mcp-server folder",
                "run",
                "server.py"
            ],
	    "env": {
             "KURRENTDB_CONNECTION_STRING": "insert kurrentdb connection here"
        }
      }
    }
  }

この設定ファイルは Claude Desktop（https://modelcontextprotocol.io/quickstart/user）で動作します。

MCP クライアントのセットアップ（Cursor または Windsurf）

{
  "mcpServers": {
    "kurrentdb": {
      "command": "python",
      "args": ["path to mcp-server folder\\server.py"],
      "env": {
             "KURRENTDB_CONNECTION_STRING": "insert kurrentdb connection here" 
         }
    }
  }
}

この設定ファイルは Cursor（.cursor\mcp.json）および Windsurf（.codeium\windsurf\mcp_config.json）で動作します。

概要

この MCP サーバーは、ストリームデータを MCP クライアントで利用できるように設計されています。 ストリームデータのクエリと取得のためのシンプルなインターフェースを提供します。 プロジェクションの作成、テスト、デバッグもできます。

アクセス制御には、設定時に環境変数として指定する KurrentDB の接続文字列を使用します。

コンポーネント

ツール

サーバーは、次の 8 つのツール呼び出しを公開します。

1. read_stream
2. list_streams
3. build_projection
4. create_projection
5. update_projection
6. test_projection
7. write_events_to_stream
8. get_projections_status

設定

• ConnectionString：ユーザー認証情報を含む KurrentDB の接続文字列です。使用するクライアントによっては、環境変数から取得する場合と、Claude Desktop のように JSON 設定ファイルから取得する場合があります。

使用方法のドキュメント

利用可能なツール

1. ストリーム操作

read_stream

KurrentDB の特定のストリームからイベントを読み取ります。

パラメーター：

• stream（必須）：読み取るストリーム名
• backwards（任意、デフォルト：false）：読み取り方向。true の場合は新しい順、false の場合は古い順
• limit（任意、デフォルト：10）：返すイベント数

プロンプトの例：

• 「'orders' ストリームから最後の 5 件のイベントを読み取ってください」
• 「user-activity ストリームの最初の 20 件のイベントを表示してください」
• 「inventory ストリームから、逆順ですべてのイベントを取得してください」

使用例：

Tool: read_stream
Parameters:
- stream: "orders"
- backwards: true
- limit: 5

write_events_to_stream

KurrentDB のストリームに新しいイベントを書き込みます。

パラメーター：

• stream（必須）：書き込み先のストリーム名
• data（必須）：イベントデータを含む JSON オブジェクト
• event_type（必須）：イベントの種類／カテゴリー
• metadata（必須）：イベントに関する追加情報を含む JSON オブジェクト

プロンプトの例：

• 「顧客 ID 123 の新しい注文イベントを orders ストリームに追加してください」
• 「タイムスタンプと IP アドレスを含むユーザーログインイベントを記録してください」
• 「inventory ストリームに商品更新イベントを作成してください」

使用例：

Tool: write_events_to_stream
Parameters:
- stream: "orders"
- data: {"orderId": "ORD-001", "customerId": 123, "amount": 99.99}
- event_type: "OrderCreated"
- metadata: {"timestamp": "2025-05-19T10:00:00Z", "source": "web"}

list_streams

KurrentDB データベース内の利用可能なすべてのストリームを一覧表示します。

パラメーター：

• limit（任意、デフォルト：100）：返すストリーム数
• read_backwards（任意、デフォルト：true）：$streams ストリームの読み取り方向

プロンプトの例：

• 「データベース内のすべてのストリームを表示してください」
• 「最初の 10 件のストリームを一覧表示してください」
• 「KurrentDB ではどのストリームを利用できますか？」

使用例：

Tool: list_streams
Parameters:
- limit: 20
- read_backwards: true

2. プロジェクション操作

KurrentDB のプロジェクションは、ストリームのイベントを処理してクエリ可能なデータ構造を作成する、計算されたビューです。

build_projection

要件に基づいたプロジェクションの構築をAIの支援を受けて行います。

パラメーター：

• user_prompt（必須）：プロジェクションに実行させたい処理の説明

プロンプトの例：

• 「顧客ごとの注文総数をカウントするプロジェクションを作成して」
• 「1日の売上合計を表示するプロジェクションを構築して」
• 「在庫レベルをリアルタイムで追跡するプロジェクションが必要です」

使用例：

Tool: build_projection
Parameters:
- user_prompt: "Create a projection that aggregates order totals by day and calculates running totals"

create_projection

指定されたコードを使用して、KurrentDBにプロジェクションを作成します。

パラメーター：

• projection_name（必須）：プロジェクションの名前
• code（必須）：生成されたプロジェクションコード

プロンプトの例：

• 「生成されたコードで顧客分析プロジェクションを作成して」
• 「この注文概要プロジェクションをKurrentDBにデプロイして」

注： クライアントは通常、プロジェクションを作成する前に必ずユーザーに確認を求めます。

update_projection

既存のプロジェクションを新しいコードで更新します。

パラメーター：

• projection_name（必須）：更新するプロジェクションの名前
• code（必須）：更新後のプロジェクションコード

プロンプトの例：

• 「売上プロジェクションを更新して、税額計算を追加して」
• 「ユーザー分析プロジェクションを変更して、より多くの指標を追跡して」

get_projections_status

特定のプロジェクションのステータスと統計情報を取得します。

パラメーター：

• projection_name（必須）：プロジェクションの名前

プロンプトの例：

• 「売上プロジェクションのステータスを確認して」
• 「user-analyticsプロジェクションの統計情報を表示して」
• 「在庫プロジェクションは正しく実行されていますか？」

test_projection

プロジェクションにテストイベントを書き込み、機能を検証します。検証は、出力されたストリームまたはプロジェクションの状態を読み取って行います。

プロンプトの例：

• 「order-analytics-projectionをサンプルデータでテストして」

パラメーター：

• projection_name（必須）：テストするプロジェクションの名前

プロンプトの例：

• 「注文分析プロジェクションをテストする方法を教えて」
• 「顧客セグメンテーションプロジェクションのテストガイドラインを教えて」

サンプルイベント

最新のLLMは、十分な情報があれば、さまざまなユースケース向けのサンプルイベントを生成できます。

注文イベント

{
  "data": {
    "orderId": "ORD-12345",
    "customerId": "CUST-789",
    "items": [
      {"productId": "PROD-001", "quantity": 2, "price": 29.99}
    ],
    "total": 59.98
  },
  "event_type": "OrderCreated",
  "metadata": {
    "timestamp": "2025-05-19T14:30:00Z",
    "source": "ecommerce-api",
    "correlationId": "corr-123"
  }
}

ユーザーアクティビティイベント

{
  "data": {
    "userId": "USER-456",
    "action": "page_view",
    "page": "/products/electronics",
    "sessionId": "sess-789"
  },
  "event_type": "UserActivity",
  "metadata": {
    "timestamp": "2025-05-19T14:35:00Z",
    "userAgent": "Mozilla/5.0...",
    "ipAddress": "192.168.1.100"
  }
}