关键词

SSB流处理数据分析LLM集成Cloudera

项目简介

SSB MCP服务器是一个基于Model Context Protocol (MCP) 的应用后端，旨在将SQL Stream Builder (SSB) 的强大功能以标准化的方式暴露给大型语言模型（LLM）客户端，如Claude Desktop。它支持对SSB进行数据访问、任务管理、监控诊断等80多项操作，兼容独立部署和Cloudera Data Platform (CDP) 部署的SSB环境。

主要功能点

  • 全面SSB管理: 通过80多种工具，覆盖SSB API的80%以上，实现SQL流管理、任务生命周期控制、表和数据源操作、UDF管理等。
  • 多重认证支持: 支持SSB直连的基础认证，以及Apache Knox集成的Bearer Token、Cookie和密码令牌等多种认证方式。
  • 安全操作: 默认开启只读模式（CDP部署），可配置启用写入操作，确保数据安全。
  • 实时数据采样: 支持灵活的SQL查询执行，提供实时数据采样，包括“采样所有消息”模式和自定义采样配置。
  • 监控与诊断: 提供系统健康检查、性能计数器、SQL查询分析等功能，帮助监控SSB运行状态。
  • Kafka集成: 允许创建和注册基于Kafka的虚拟表，方便LLM查询实时流数据。
  • 会话和能力声明: 遵循MCP协议，与LLM客户端进行JSON-RPC通信，支持会话管理和能力声明。

安装步骤

  1. 克隆仓库: 
    git clone https://github.com/BrooksIan/SSB-MCP-Server.git
cd SSB-MCP-Server
  2. 创建并激活Python虚拟环境: 
    python3 -m venv .venv
source .venv/bin/activate
  3. 安装项目依赖: 
    pip install -e .
  4. 配置SSB连接信息: 根据您的SSB部署类型（独立部署或CDP部署），通过环境变量设置SSB连接凭据。您可以在运行MCP服务器的脚本或MCP客户端的配置中设置这些环境变量：
    • 独立SSB部署:
      • 'SSB_API_BASE': 您的SSB API基础URL，例如 'http://localhost:18121'
      • 'SSB_USER': SSB用户名，例如 'admin'
      • 'SSB_PASSWORD': SSB密码，例如 'admin'
    • CDP SSB部署 (通过Knox):
      • 'KNOX_GATEWAY_URL': Knox网关URL，例如 'https://<your-ssb-host>/gateway/ssb'
      • 'KNOX_TOKEN': 您的Knox JWT令牌 (从CDP UI获取)
      • 'SSB_API_BASE': CDP环境下SSB API的完整路径，例如 'https://<your-ssb-host>/ssb/api/v1'
      • 可选：'SSB_READONLY': 设置为 'false' 可启用写入操作 (CDP部署默认为只读)
  5. 启动SSB服务 (仅Docker Compose部署): 如果您使用Docker Compose进行本地Standalone SSB部署，需要先启动相关的SSB服务。在项目根目录执行： 
    docker-compose up -d

服务器配置

MCP客户端（如Claude Desktop）通过JSON格式的配置文件来连接MCP服务器。以下是配置示例及说明：

  • 本地运行 (在虚拟环境中): 将以下JSON片段添加到您的MCP客户端配置（例如 '~/Library/Application Support/Claude/claude_desktop_config.json'）中。请确保替换路径和令牌为您的实际值。

    {
  "mcpServers": {
    "ssb-mcp-server": {
      "command": "/FULL/PATH/TO/SSB-MCP-Server/.venv/bin/python",
      "args": [
        "-m",
        "ssb_mcp_server.server"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "SSB_API_BASE": "https://ssb-gateway.yourshere.cloudera.site/ssb/api/v1",
        "KNOX_TOKEN": "<your_knox_bearer_token>",
        "SSB_READONLY": "true"
      }
    }
  }
}
    • '"ssb-mcp-server"': 您为该MCP服务器指定的唯一名称。
    • 'command': MCP服务器的可执行命令的完整路径。在这里是您的虚拟环境中的Python解释器路径。
    • 'args': 传递给命令的参数列表。'-m ssb_mcp_server.server' 指示Python解释器运行 'ssb_mcp_server' 模块内的服务器代码。
    • 'env': 环境变量，用于配置MCP服务器的行为：
      • 'MCP_TRANSPORT': 指定通信协议，'"stdio"' (标准输入输出) 是常用方式。
      • 'SSB_API_BASE': SSB API的完整基础URL。
      • 'KNOX_TOKEN': 您的Knox JWT认证令牌。
      • 'SSB_READONLY': 设置为 '"true"' 或 '"false"' 控制服务器是否为只读模式。

  • 通过'uvx'远程安装 (适用于Cloudera Agent Studio): 在您的Cloudera Agent Studio配置中，您可以使用'uvx'命令来远程安装和运行MCP服务器。

    {
  "mcpServers": {
    "ssb-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/your-org/ssb-mcp-server@main",
        "run-server"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "SSB_API_BASE": "https://ssb-gateway.yourshere.cloudera.site/ssb/api/v1",
        "KNOX_TOKEN": "<your_knox_bearer_token>",
        "SSB_READONLY": "true"
      }
    }
  }
}
    • 'command': 使用 'uvx' 工具作为启动命令。
    • 'args': 'uvx' 的参数，'--from git+...' 指定从Git仓库安装，'run-server' 告诉'uvx'运行仓库中的服务器。
    • 'env': 环境变量，其含义与本地运行配置中的相同。

基本使用方法

配置完成后，重启您的MCP客户端（如Claude Desktop）。现在，您就可以通过自然语言与SSB环境进行交互了：

  • 查询信息:
    • “我的SSB版本是多少？”
    • “列出所有我的SQL流。”
    • “有哪些表可以查询？”
    • “列出所有Kafka主题。”
    • “集群健康状况如何？”
  • 数据查询与获取:
    • “执行这个查询：'SELECT * FROM NVDA LIMIT 10'。”
    • “创建一个只采样所有消息的任务：'SELECT * FROM my_stream'。”
    • “显示任务1234的状态。”
    • “获取任务1234的采样数据。”
  • 任务管理:
    • “停止任务1234。”
    • “重启任务1234并采样所有消息。”
  • 流管理:
    • “创建一个名为'sales_analysis'的新流，SQL是'SELECT * FROM sales WHERE amount > 1000'。”
    • “显示'user_events'流的详细信息。”
  • Kafka表管理:
    • “创建一个名为'user_events'的本地Kafka表，主题是'user-events'。”

MCP服务器将解析您的自然语言请求，调用相应的SSB API工具，并将操作结果或数据以LLM易于理解的格式返回给客户端。

信息

分类

商业系统

访问项目