Kurrentdb Mcp Server

KurrentDB MCP 服务

这是一个简单的 MCP 服务，可帮助你探索数据，并在 KurrentDB 上更快地构建原型投影。

推荐用法

• Claude Desktop
• 复杂任务可使用 Sequential Thinking MCP

安装

KurrentDB 设置

你需要在 KurrentDB 上启用 --run-projections=all 和 --start-standard-projections。 $streams 流用于查找可用流。

Python 依赖项

使用 pip 确保已安装 requirements.txt 中的包。

操作系统依赖项

确保在运行 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 连接字符串。根据所用客户端的不同，它可以来自环境变量，也可以来自 JSON 配置文件（例如 Claude Desktop 使用的配置文件）。

使用文档

可用工具

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 对象

提示词示例：

• “向 orders 流添加一个包含客户 ID 123 的新订单事件”
• “记录一条包含时间戳和 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（必填）：描述投影应执行的操作

提示词示例：

• “创建一个按客户统计订单总数的投影”
• “构建一个展示每日收入总额的投影”
• “我需要一个实时跟踪库存水平的投影”

使用示例：

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（必填）：要测试的投影名称

提示词示例：

• “如何测试订单分析投影？”
• “提供客户细分投影的测试指南”

示例事件

现代大模型只要获得足够的信息，就能针对各种用例生成示例事件。

订单事件

{
  "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"
  }
}