mcp-server

# 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" } } ```