内容
# KurrentDB MCP 服务器
这是一个简单的 MCP 服务器，帮助您在 KurrentDB 之上更快地探索数据和原型化投影。
## 推荐用法
- Claude Desktop
- 顺序思考 MCP 用于复杂任务
## 安装
### KurrentDB 设置
您需要在 KurrentDB 上启用 `--run-projections=all` 和 `--start-standard-projections`
`$streams` 流用于查找可用流。
### Python 依赖项
确保使用 pip 安装 `requirements.txt` 中的包
### 操作系统依赖项
确保在运行 MCP 服务器的机器上安装了 `vu` 包
对于 Mac: `brew install uv`
### MCP 客户端设置（VS Code）
```json
{
"servers": {
"KurrentDB": {
"type": "stdio",
"command": "uv",
"args": [
"--directory",
"路径到 mcp-server 文件夹",
"run",
"server.py"
],
"env": {
"KURRENTDB_CONNECTION_STRING": "在此处插入 kurrentdb 连接字符串"
}
}
}
}
```
此配置文件应在 VS Code 中生效（.vscode/mcp.json）。
### MCP 客户端设置（Claude）
```json
{
"mcpServers": {
"KurrentDB": {
"type": "stdio",
"command": "uv",
"args": [
"--directory",
"路径到 mcp-server 文件夹",
"run",
"server.py"
],
"env": {
"KURRENTDB_CONNECTION_STRING": "在此处插入 kurrentdb 连接字符串"
}
}
}
}
```
此配置文件应在 Claude Desktop 中生效（https://modelcontextprotocol.io/quickstart/user）。
### MCP 客户端设置（Cursor 或 Windsurf）
```json
{
"mcpServers": {
"kurrentdb": {
"command": "python",
"args": ["路径到 mcp-server 文件夹\\server.py"],
"env": {
"KURRENTDB_CONNECTION_STRING": "在此处插入 kurrentdb 连接字符串"
}
}
}
}
```
此配置文件应在 Cursor (\.cursor\mcp.json) 和 Windsurf (\.codeium\windsurf\mcp_config.json) 中生效。
## 概述
此 MCP 服务器旨在使流数据可用于 MCP 客户端。
它提供了一个简单的接口用于查询和检索流数据。
它还可以创建、测试和调试投影。
访问控制使用在配置时作为环境变量提供的 KurrentDB 连接字符串。
## 组件
### 工具
服务器公开了 8 个工具调用：
1. `读取流`
2. `列出流`
3. `构建投影`
4. `创建投影`
5. `更新投影`
6. `测试投影`
7. `向流写入事件`
8. `获取投影状态`
### 配置
- 连接字符串：这是包含用户凭证的 KurrentDB 连接字符串。根据使用的客户端，这可以来自环境变量或 JSON 配置文件，如 Claude Desktop 的情况。
# 使用文档
## 可用工具
### 1. 流操作
#### `读取流`
从 KurrentDB 中的特定流读取事件。
**参数：**
- `流`（必填）：要读取的流名称
- `向后`（可选，默认值：false）：读取方向 - true 表示最新的事件优先，false 表示最旧的事件优先
- `限制`（可选，默认值：10）：要返回的事件数量
**示例提示：**
- "从 '订单' 流中读取最后 5 个事件"
- "显示 '用户活动' 流中的前 20 个事件"
- "从库存流中读取所有事件，向后读取"
**示例用法：**
```
工具：读取流
参数：
- 流："订单"
- 向后：true
- 限制：5
```
#### `向流写入事件`
向 KurrentDB 中的流写入新事件。
**参数：**
- `流`（必填）：要写入的流名称
- `数据`（必填）：包含事件数据的 JSON 对象
- `事件类型`（必填）：事件的类型/类别
- `元数据`（必填）：包含额外事件信息的 JSON 对象
**示例提示：**
- "将新的订单事件添加到订单流中，客户 ID 为 123"
- "记录用户登录事件，包含时间戳和 IP 地址"
- "在库存流中创建产品更新事件"
**示例用法：**
```
工具：向流写入事件
参数：
- 流："订单"
- 数据：{"订单 ID": "ORD-001", "客户 ID": 123, "金额": 99.99}
- 事件类型："订单已创建"
- 元数据：{"时间戳": "2025-05-19T10:00:00Z", "来源": "网页"}
```
#### `列出流`
列出 KurrentDB 数据库中的所有可用流。
**参数：**
- `限制`（可选，默认值：100）：要返回的流数量
- `向后读取`（可选，默认值：true）： `$streams` 流的读取方向
**示例提示：**
- "显示数据库中的所有流"
- "列出前 10 个流"
- "KurrentDB 中有哪些流可用？"
**示例用法：**
```
工具：列出流
参数：
- 限制：20
- 向后读取：true
```
### 2. 投影操作
KurrentDB 中的投影是计算视图，它们处理流中的事件以创建可查询的数据结构。
#### `构建投影`
根据您的要求，使用 AI 助手构建投影。
**参数：**
- `用户提示`（必填）：投影应该执行的操作的描述
**示例提示：**
- "创建一个投影，统计每个客户的总订单数"
- "构建一个投影，显示每日收入总额"
- "我需要一个实时跟踪库存水平的投影"
**示例用法：**
```
工具：构建投影
参数：
- 用户提示："创建一个投影，按天汇总订单总额并计算滚动总额"
```
#### `创建投影`
使用提供的代码在 KurrentDB 中创建投影。
**参数：**
- `投影名称`（必填）：投影的名称
- `代码`（必填）：生成的投影代码
**示例提示：**
- "使用生成的代码创建客户分析投影"
- "将此订单摘要投影部署到 KurrentDB"
**注意：** 客户端通常在创建投影之前始终要求用户确认。
#### `更新投影`
更新现有的投影，使其包含新的代码。
**参数：**
- `投影名称`（必填）：要更新的投影名称
- `代码`（必填）：更新的投影代码
**示例提示：**
- "更新销售投影以包含税金计算"
- "修改用户分析投影以跟踪更多指标"
#### `获取投影状态`
检索特定投影的状态和统计信息。
**参数：**
- `投影名称`（必填）：投影的名称
**示例提示：**
- "检查销售投影的状态"
- "显示用户分析投影的统计信息"
- "库存投影是否正常运行？"
#### `测试投影`
向投影写入测试事件以验证其功能。验证通过读取发出的流或投影的状态进行。
**示例提示：**
- "使用样本数据测试订单分析投影"
**参数：**
- `投影名称`（必填）：要测试的投影名称
**示例提示：**
- "如何测试订单分析投影？"
- "给我提供客户细分投影的测试指南"
## 示例事件
现代大型语言模型可以为各种用例生成示例事件，只需提供足够的信息。
### 订单事件
```json
{
"数据": {
"订单 ID": "ORD-12345",
"客户 ID": "CUST-789",
"项目": [
{"产品 ID": "PROD-001", "数量": 2, "价格": 29.99}
],
"总计": 59.98
},
"事件类型": "订单已创建",
"元数据": {
"时间戳": "2025-05-19T14:30:00Z",
"来源": "电子商务 API",
"关联 ID": "corr-123"
}
}
```
### 用户活动事件
```json
{
"数据": {
"用户 ID": "USER-456",
"操作": "页面浏览",
"页面": "/products/electronics",
"会话 ID": "sess-789"
},
"事件类型": "用户活动",
"元数据": {
"时间戳": "2025-05-19T14:35:00Z",
"用户代理": "Mozilla/5.0...",
"IP地址": "192.168.1.100"
}
}
```
MCP 市场