流消息管理服务器

SSM MCP服务器

Streams Messaging Manager主界面显示集群概述和导航

模型上下文协议服务器提供对Cloudera Streams消息传递管理器（SMM）的访问，支持直接SMM访问和CDP集成。

适用于独立SMM部署和Cloudera数据平台（CDP）SMM部署 -通过Claude Desktop提供核心SMM功能。

⚠️ 当前状态

成功率34.4% -64个MCP工具中有22个目前正在工作。核心功能，包括集群管理、主题列表和管理操作，都是可操作的。由于API端点限制，许多高级功能（指标、警报、用户组）尚未工作。

工作特点：

• ✅ 核心SMM管理（100%）
• ✅ 集群管理（100%）
• ✅ 经纪人管理（100%）
• ✅ 主题管理（100%）
• ✅ 配置管理（100%）
• ✅ 管理端点（100%）- 新

特性

• 多种身份验证方法:
  • 直接SMM身份验证：独立SMM部署的基本身份验证
  • Apache Knox集成：用于CDP部署的JWT令牌、Cookie和密码令牌
• 默认情况下为只读 -SMM集群和配置的安全探索
• 工作SMM API覆盖范围 随着 22个经过验证的MCP工具 对于核心SMM管理：
  • ✅ 核心SMM管理：版本信息、系统详细信息（100%有效）
  • ✅ 群集管理：集群详细信息、代理信息（100%有效）
  • ✅ 经纪人管理：经纪人详细信息、指标、配置（100%有效）
  • ✅ 主题管理：列出主题，获取主题信息，配置（100%有效）
  • ✅ 配置管理：代理配置、主题配置（100%有效）
  • ✅ 管理端点：详细的集群、代理和主题数据（100%有效）
  • ⚠️ 消费者群体管理：无法通过SMM API获得（0%工作）
  • ⚠️ 度量与监控：无法通过SMM API获得（0%工作）
  • ⚠️ 警报管理：无法通过SMM API获得（0%工作）
  • ⚠️ 主题数据采样：无法通过SMM API获得（0%工作）
  • ⚠️ Kafka连接：无法通过SMM API获得（0%工作）
  • ⚠️ 健康监测：无法通过SMM API获得（0%工作）

快速开始

Streams Messaging Manager主界面显示集群概述和导航

用于独立SMM部署

1. 安装和设置：

   复制

   git clone https://github.com/your-org/ssm-mcp-server.git
   cd ssm-mcp-server
   
   # Option A: Using uv (recommended)
   make setup  # Installs uv if needed and dependencies
   
   # Option B: Using pip
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -e .
   

2. 配置Claude桌面 -编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

   复制

   {
     "mcpServers": {
       "ssm-mcp-server": {
         "command": "/FULL/PATH/TO/SSM-MCP-Server/run_mcp_server.sh",
         "args": [],
         "cwd": "/FULL/PATH/TO/SSM-MCP-Server",
         "env": {
           "MCP_TRANSPORT": "stdio",
           "SMM_API_BASE": "http://localhost:8080/api/v2",
           "SMM_USER": "admin",
           "SMM_PASSWORD": "admin",
           "SMM_READONLY": "true"
         }
       }
     }
   }
   

3. 设置您的凭据:

   复制

   # Option A: Interactive setup (recommended)
   python setup_config.py
   
   # Option B: Manual setup
   cp config.template .env
   nano .env  # Edit with your actual credentials
   

4. 重新启动克劳德桌面 并开始与您的SMM集群交互！

用于CDP SMM部署（通过Apache Knox）

您的Knox网关URL通常为：

https://<your-knox-gateway>:8444/gateway/smm

从CDP UI获取Knox JWT令牌，并将其与以下配置一起使用。

Knox配置示例

选项A:JWT令牌身份验证

{
  "mcpServers": {
    "ssm-mcp-server": {
      "command": "/FULL/PATH/TO/SSM-MCP-Server/run_mcp_server.sh",
      "args": [],
      "cwd": "/FULL/PATH/TO/SSM-MCP-Server",
      "env": {
        "MCP_TRANSPORT": "stdio",
        "KNOX_GATEWAY_URL": "https://your-knox-gateway:8444/gateway/smm",
        "KNOX_TOKEN": "your-knox-jwt-token",
        "SMM_READONLY": "true"
      }
    }
  }
}

选项B：用户名/密码验证

{
  "mcpServers": {
    "ssm-mcp-server": {
      "command": "/FULL/PATH/TO/SSM-MCP-Server/run_mcp_server.sh",
      "args": [],
      "cwd": "/FULL/PATH/TO/SSM-MCP-Server",
      "env": {
        "MCP_TRANSPORT": "stdio",
        "KNOX_GATEWAY_URL": "https://your-knox-gateway:8444/gateway/smm",
        "KNOX_USER": "your-username",
        "KNOX_PASSWORD": "your-password",
        "KNOX_TOKEN_ENDPOINT": "https://your-knox-gateway:8444/gateway/knoxsso/api/v1/websso",
        "SMM_READONLY": "true"
      }
    }
  }
}

配置选项

所有配置都是通过环境变量完成的：

直接SMM身份验证（独立）

Knox身份验证（CDP）

*要么 SMM_API_BASE （直接）或 KNOX_GATEWAY_URL （适用于诺克斯）为必填项

uv开发

此项目使用 紫外线 用于快速依赖管理和Python项目管理。

快速命令

# Install uv and dependencies
make setup

# Run the server
make run

# Run tests
make test

# Run linting
make lint

# Format code
make format

# Show all available commands
make help

手动uv命令

# Install dependencies
uv sync

# Run the server
uv run python -m ssm_mcp_server.server

# Run tests
uv run python test_connection_uv.py

# Add a new dependency
uv add package-name

# Add a development dependency
uv add --dev package-name

# Update dependencies
uv sync --upgrade

示例用法

配置后，您可以向Claude提出以下问题：

基本信息

• “我运行的是哪个版本的SMM？”
• “显示集群详细信息”
• “列出群集中的所有经纪人”
• “有哪些可用的主题？”
• “显示所有消费者群体”

示例：群集运行状况和代理信息显示

主题管理

• “显示主题“销售数据”的配置”
• “显示主题'logs'分区0的内容”
• “列出群集中的所有主题”
• “主题‘用户事件’的指标是什么？”

示例：列出集群中的所有用户主题

示例：详细的主题信息和配置

示例：主题配置管理和分析

备注SMM主要是一种监控工具。要创建/删除主题，请使用Kafka管理工具：

• kafka-topics.sh --create --topic user-events --partitions 3 --bootstrap-server localhost:9092
• kafka-topics.sh --delete --topic test-topic --bootstrap-server localhost:9092

经纪人管理

• “显示集群中的所有经纪人”
• “经纪人1的详细信息是什么？”
• “显示过去一小时的经纪人指标”
• “代理配置是什么？”

示例：详细的经纪人信息和监控

配置管理

• “显示代理配置”
• “‘心跳’的主题配置是什么？”
• “显示默认主题配置”
• “群集配置详细信息是什么？”

可用工具

当前状态：34.4%的成功率（64个MCP工具中有22个有效）

目前有以下工具 工作和功能:

🔧 核心SMM管理层（100%工作）

• get_smm_info() -获取SMM版本和系统信息
• get_smm_version() -获取SMM版本详细信息

🏢 集群管理（100%有效）

• get_cluster_details() -获取集群详细信息

🖥️ 经纪人管理（100%工作）

• get_brokers() -获取集群中的所有经纪人
• get_broker(broker_id) -获取特定经纪人的详细信息
• get_broker_metrics(broker_id, duration?, from_time?, to_time?) -获取特定经纪商的指标
• get_all_broker_details() -通过配置获取所有代理详细信息
• get_broker_details(broker_id) -获取包括配置在内的详细代理信息

📊 主题管理（100%有效）

• get_all_topic_infos() -获取所有主题信息
• get_topic_description(topic_name) -获取特定主题的详细描述
• get_topic_info(topic_name) -获取特定主题的基本信息
• get_topic_partitions(topic_name) -获取特定主题的分区信息
• get_topic_partition_infos(topic_name) -获取特定主题的详细分区信息
• get_topic_configs(topic_name) -获取特定主题的配置
• get_all_topic_configs() -获取所有主题的配置
• get_default_topic_configs() -获取默认主题配置

⚙️ 配置管理（100%有效）

• get_broker_configs() -获取代理配置

🔧 管理端点（100%工作）- 新

• get_admin_cluster() -使用详细的代理和控制器数据获取管理集群信息
• get_admin_brokers() -获取管理员代理信息和详细的代理数据
• get_admin_topics() -获取具有详细主题和分区数据的管理主题信息
• get_admin_topic_details(topic_name) -获取特定主题的管理主题详细信息
• get_admin_topic_partitions(topic_name) -获取特定主题的管理主题分区

📋 有关非工作工具和限制的完整信息，请参阅 限制README.md

写入操作

默认情况下，服务器在CDP部署中以只读模式运行，在独立部署中启用写。要更改此设置，请执行以下操作：

1. 集 SMM_READONLY=false （允许写入）或 SMM_READONLY=true （只读）
2. 重新启动MCP服务器

⚠️ 重要限制：SMM主要是一个监控工具，实际上并不对主题执行写入操作。

支持的写入操作：

• 创建和管理警报策略
• 管理Kafka Connect连接器
• 架构注册表操作
• 消费者群体抵消管理

不支持（SMM限制）：

• 主题创建/删除：SMM API接受请求，但不创建/删除主题
• 主题配置更改：SMM API接受请求，但不修改主题配置
• 分区管理：SMM API接受请求，但不创建/修改分区

对于主题管理，直接使用Kafka管理工具或Kafka admin API。

局限性

有关当前限制、非工作功能和已知问题的详细信息，请参阅：

📋 限制README.md -全面的文件记录：

• SMM主题创建限制
• 不工作的MCP工具（65.6%目前不工作）
• 使用MCP工具（成功率34.4%）
• API端点限制和解析状态
• 修复的贡献指南

快速摘要：由于SMM API的限制，服务器当前的成功率为34.4%（22/64个工具工作）。集群管理、主题列表、代理监控和管理操作等核心功能是可操作的。许多高级功能无法通过SMM API获得。

安全

• 所有敏感数据（密码、令牌、机密）都会在响应中自动编辑
• 大型收藏被截断，以防止淹没LLM
• 默认情况下，CDP部署启用只读模式，以防止意外修改
• 直接SMM身份验证使用HTTP上的基本身份验证（适用于本地开发）
• CDP集成使用安全的JWT令牌身份验证

故障排除

常见问题

1. “未经授权”的错误：检查您的身份验证凭据

   • 对于直接SMM：验证 SMM_USER 和 SMM_PASSWORD
   • 对于CDP：验证 SMM_TOKEN 或 SMM_USER/SMM_PASSWORD

2. “连接被拒绝”错误：确保SMM服务正在运行

   • 检查SMM服务状态
   • 验证端口映射和网络连接

3. “未找到主题”错误：验证主题名称和群集访问权限

   • 使用 get_all_topic_infos() 列出可用主题
   • 检查主题权限和访问权限

4. SSL证书错误：用于CDP部署

   • 集 SMM_VERIFY_SSL=false 用于自签名证书
   • 或提供适当的CA捆绑包 SMM_CA_BUNDLE

调试模式

通过设置环境变量启用调试日志记录：

export MCP_LOG_LEVEL=DEBUG

总结

SSM MCP服务器是 专注管理平台 对于Cloudera Streams消息传递管理器，通过以下方式为Claude Desktop提供对核心SMM功能的访问 22个经过验证的MCP工具.

🎯 您将获得：

• 核心SMM控制：管理集群、代理和主题
• 综合监控：详细的集群和代理信息
• 配置管理：代理和主题配置访问
• 管理操作：高级集群、代理和主题数据访问
• 企业功能：多环境支持和安全身份验证

🚀 主要优势：

• API覆盖率为34.4%：访问实际可用的核心SMM功能
• 22工作工具：用于基本SMM操作的可靠工具集
• 6功能类别：有组织、可发现的能力
• 生产就绪：稳定、经过测试的功能，可供实际使用
• 用户友好：通过Claude Desktop进行自然语言交互
• 灵活的：支持独立部署和CDP部署

📈 非常适合：

• 数据工程师：主题管理、集群监控、配置分析
• DevOps团队：集群管理、代理监控、系统运行状况
• 平台管理员：系统监控、配置管理、集群监督
• Kafka用户：主题探索、经纪人详细信息、集群信息

SSM MCP服务器将Claude Desktop转换为可靠的SMM管理界面，使您能够与Streams Messaging Manager环境进行自然语言交互！ 🎉

许可证

Apache许可证2.0